The Text::ClearSilver class

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 string (for "substr", "sprintf", "lc", "uc", "lcfirst", "ucfirst" and "trim") and html (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 &gt;, &lt;, and &amp;.

"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

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.

Notes:

• that any scalar values, including blessed references, will be simply stringified.
• "undef" is simply ignored.
• 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.

Text::ClearSilver::CS

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

See <http://www.clearsilver.net/docs/man_templates.hdf> for details.

"name"

"var"

"uvar"

"evar"

"lvar"

"if"

"else"

"elseif"

"elif"

"each"

"with"

"include"

"linclude"

"def"

"call"

"set"

"loop"

"alt"

"escape"

Examples

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 ?>

makes:

    first
    0: foo
    1: bar
    2: baz
    last

with some white spaces.

Macros

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)

makes:

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

with some white spaces.

Escapes

Given a dataset:

    my %vars = (
        uri => q{<a href="http://example.com">example.com</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 ?>

makes:

    escape: "none":
    <a href="http://example.com">example.com</a>

    escape: "html":
    &lt;a href=&quot;http://example.com&quot;&gt;example.com&lt;/a&gt;

    escape: "js":
    \x3Ca href=\x22http:\x2F\x2Fexample.com\x22\x3Eexample.com\x3C\x2Fa\x3E

    escape: "url":
    %3Ca+href%3D%22http%3A%2F%2Fexample.com%22%3Eexample.com%3C%2Fa%3E