Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TEXT::CLEARSILVER (3)

.ds Aq ’


Text::ClearSilver - Perl interface to the ClearSilver template engine



This document describes Text::ClearSilver version v0.10.5.4.


    use Text::ClearSilver;

    my $cs = Text::ClearSilver->new(
        # core configuration
        VarEscapeMode => html, # html,js,url, or none
        TagStart      => cs,   # <?cs ... >

        # extended configuratin
        load_path => [qw(/path/to/template)],
        dataset   => { common_foo => value },
        functions => [qw(string html)],

    $cs->register_function( ucfirst => sub{ ucfirst $_[0] } );

    my %vars = (
        foo => bar,         # as var:foo
        baz => { qux => 42 }, # as var:baz.qux

    $cs->process(\q{<?cs var:ucfirst(foo) ?>}, \%vars); # => Bar

    # with encodings
    $cs->process(\q{<?cs var:foo ?>}, \%vars, \my $out,
        encoding => utf8, # may be utf8 or bytes


Text::ClearSilver is a Perl binding to the <B>ClearSilverB> template engine.


    The Text::ClearSilver class

Text::ClearSilver->new(%config | \%config) :TCS

Creates a Text::ClearSilver processor.

Configuration parameters may be:
VarEscapeMode => ( none | html | js | url ) Sets the default variable escaping mode. If it is not none, template variables will be automatically escaped. Default to none.

This is ClearSilver core feature, and a shortcut for dataset => { Config => VarEscapeMode => ... }.

TagStart => $str Sets the ClearSilver starting tag. Default to cs.

This is ClearSilver core feature, and a shortcut for dataset => { Config => TagStart => ... }.

load_path => \@path Sets paths which are used to find template files.

This is a shortcut for dataset => { hdf => { loadpaths => \@path } }.

dataset => $hdf_source Sets a dataset which is used in common.

$hdf_source may be references to data or HDF string.

functions => \@sets Installs sets of functions.

Currently <B>stringB> (for substr, sprintf, lc, uc, lcfirst, ucfirst and trim) and <B>htmlB> (for nl2br) are supported.

encoding => utf8 | bytes Specifies the encoding. Note that utf8 works as the use utf8 pragma.
$tcs->dataset :HDF

Returns the dataset that the processor uses in common.

$tcs->register_function($name, \&func, $n_args = -1 ) :Void

Registers a named function in the TCS processor.

If you set the number of arguments >= 0, it will be checked at parsing time, rather than runtime.

Note that Text::ClearSilver defines some builtin functions, and you cannot re-define them.

Builtin functions are as follows:
subcount(var) Returns the number of child nodes for the HDF variable.
len(var) A synonym to subcount().
name(local) Returns the HDF variable name for a local variable alias.
first(lolca) Returns true if and only if the local variable is the first in a loop or each.
last(local) Returns true if and only if the local variable is the last in a loop or each.
abs(num) Returns the absolute value of the numeric expressions.
max(num1, num2) Returns the larger of two numeric expressions.
min(num1, num2) Returns the smaller of two numeric expressions.
string.slice(expr, start, end) Returns the string slice starting at start and ending at end.
string.find(expr, substr) Returns the numeric position of the substring in the string (if found), otherwise returns -1.
string.length(expr) Returns the length of the string expression.
html_escape(expr) Tries HTML escapes to the string expression. This converts characters such as >, <, and &, into their HTML entities such as >, <, and &.
url_escape(expr) Tries URL encodes to the string expression. This converts characters such as ?, &, and = into their URL safe equivalents using the %hh syntax.
js_escape(expr) Tries JavaScript escapes to the string expression into valid data for placement into a JavaScript string. This converts characters such as , ’, and \ into their JavaScript string safe equivalents \, \’, and \\.
text_html(expr) Returns an HTML fragment formatted from a plain text.
strip_html(expr) Returns a plain text from an HTML text, removing HTML tags and converting entities into plain characters.
$tcs->process($source, $data, ?$output, %config) :Void

Processes a ClearSilver template. The first parameter, $source, indicates the input template as a filename, filehandle, or scalar reference. The second, $data, indicates template variables which may be a HDF dataset, HASH reference, ARRAY reference. The result of process is printed to the optional third parameter, $output, which may be a filename, filehandle, or scalar reference. If the third parameter is omitted, the default filehandle will be used. Optional %config are stored into Config.*, i.e. VarEscapeMode => html changes the escaping mode temporally.

$tcs->clear_cache :HASH

Clears the global file cache, and returns the old one.

    The Text::ClearSilver::HDF class

This is a low-level interface to the HDF* (Hierarchial Data Format) data structure.

Text::ClearSilver::HDF->new($hdf_source) :HDF

Creates a HDF dataset and initializes it with $hdf_source, which may be a reference to data structure or an HDF string.

o that any scalar values, including blessed references, will be simply stringified.
o undef is simply ignored.
o Cyclic references will not be converted correctly (TODO).
$hdf->add($hdf_source) :Void

Adds $hdf_source into the dataset.

$hdf_source may be a reference to data structure or an HDF string.

$hdf->get_value($name, ?$default_value) :Str

Returns the value of a named node in the dataset.

$hdf->get_obj($name) :HDF

Returns the dataset node at a named location.

$hdf->get_node($name) :HDF

Similar to get_obj except all the nodes are created if they do not exist.

$hdf->get_child($name) :HDF

Returns the first child of a named node.

$hdf->obj_child :HDF

Returns the first child of the dataset.

$hdf->obj_next :HDF

Returns the next node of the dataset.

$hdf->obj_name :Str

Returns the name of the node.

$hdf->obj_value :Str

Returns the value of the node.

$hdf->set_value($name) :Void

Sets the value of a named node.

$hdf->set_copy($dest_name, $src_name) :Void

Copies a value from one location in the dataset to another.

$hdf->set_symlink($link_name, $existing_name) :Void

Sets a part of the dataset to link to another.

$hdf->sort_obj(\&compare) :Void

Sorts the children of the dataset.

A &compare callback is given a pair of HDF nodes. For example, here is a function to sort a dataset by names:

    $hdf->sort_obj(sub {
        my($a, $b) = @_;
        return $a->obj_name cmp $b->obj_name;

$hdf->read_file($filename) :Void

Reads an HDF data file.

$hdf->write_file($filename) :Void

Writes an HDF data file.

$hdf->dump() :Str

Serializes the dataset to an HDF string, which can be passed into add().

$hdf->remove_tree($name) :Void

Removes a named node of the dataset.

$hdf->copy($name, $source) :Void

Copies a named node of a dataset to the dataset.

if $name is empty, all the $souece node will be copied.


This is a low-level interface to the CSPARSE* template engine.

Text::ClearSilver::CS->new($hdf_source) :CS

Creates a CS context with $hdf_source, which may be a reference to data structure or an HDF string..

$cs->parse_file($file) :Void

Parses a CS template file.

$cs->parse_string($string) :Void

Parses a CS template string.

$cs->render() :Str

Renders the CS parse tree and returns the result as a string.

$cs->render($filehandle) :Void

Renders the CS parse tree and print the result to a filehandle.

$cs->dump() :Str

Dumps the CS parse tree for debugging.


    ClearSilver keywords

Here are ClearSilver keywords.

See <> for details.



Given a dataset:

    my %vars = (
        Data => [qw(foo bar baz)],

and a template:

    <?cs each:item = Data ?>
    <?cs if:first(item) ?>first<?cs /if ?>
    <?cs var:name(item) ?>: <?cs var:item(name) ?>
    <?cs if:last(item) ?>last<?cs /if ?>
    <?cs /each ?>


    0: foo
    1: bar
    2: baz

with some white spaces.


Given a template:

    <?cs def:add(x, y) ?>[<?cs var:#x+#y ?>]<?cs /def ?>
    <?cs def:cat(x, y) ?>[<?cs var:x+y ?>]<?cs /def?>
    10 + 20 = <?cs call add(10, 20) ?> (as number)
    15 + 25 = <?cs call cat(15, 25) ?> (as string)


    10 + 20 = 30 (as number)
    15 + 25 = 1525 (as string)

with some white spaces.


Given a dataset:

    my %vars = (
        uri => q{<a href=""></a>},

and a template:

    escape: "none":
    <?cs escape: "none" ?><?cs var:uri ?><?cs /escape ?>

    escape: "html":
    <?cs escape: "html" ?><?cs var:uri ?><?cs /escape ?>

    escape: "js":
    <?cs escape: "js" ?><?cs var:uri ?><?cs /escape ?>

    escape: "url":
    <?cs escape: "url" ?><?cs var:uri ?><?cs /escape ?>


    escape: "none":
    <a href=""></a>

    escape: "html":
    <a href=""></a>

    escape: "js":
    \x3Ca href=\x22http:\x2F\\x22\\x3C\x2Fa\x3E

    escape: "url":


Perl 5.8.1 or later, and a C compiler.


All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.







Craftworks <craftwork(at)>

Goro Fuji (gfx) <gfuji(at)>


The ClearSilver template engine is developed by Neotonic Software Corp, and Copyright (c) 2003 Brandon Long.

This distribution includes the ClearSilver distribution. See <> for ClearSilver Software License.


Copyright (c) 2010, Craftworks. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl and perlartistic.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 TEXT::CLEARSILVER (3) 2010-04-27

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.