NAME

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

VERSION

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

SYNOPSIS

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'
);

DESCRIPTION

Text::ClearSilver is a Perl binding to the ClearSilver template engine.

INTERFACE

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 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 >, <, 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.

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

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.

APPENDIX

ClearSilver keywords

Here are 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

Loops

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

DEPENDENCIES

Perl 5.8.1 or later, and a C compiler.

BUGS

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.

AUTHORS

Craftworks <craftwork(at)cpan.org>

Goro Fuji (gfx) <gfuji(at)cpan.org>

ACKNOWLEDGMENT

This distribution includes the ClearSilver distribution. See http://www.clearsilver.net/license.hdf for ClearSilver Software License.

LICENSE AND COPYRIGHT

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

To install Text::ClearSilver, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Text::ClearSilver

CPAN shell

perl -MCPAN -e shell
install Text::ClearSilver

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE

The Text::ClearSilver class

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

$tcs->dataset :HDF

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

$tcs->process($source, $data, ?$output, %config) :Void

$tcs->clear_cache :HASH

The Text::ClearSilver::HDF class

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

$hdf->add($hdf_source) :Void

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

$hdf->get_obj($name) :HDF

$hdf->get_node($name) :HDF

$hdf->get_child($name) :HDF

$hdf->obj_child :HDF

$hdf->obj_next :HDF

$hdf->obj_name :Str

$hdf->obj_value :Str

$hdf->set_value($name) :Void

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

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

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

$hdf->read_file($filename) :Void

$hdf->write_file($filename) :Void

$hdf->dump() :Str

$hdf->remove_tree($name) :Void

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

Text::ClearSilver::CS

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

$cs->parse_file($file) :Void

$cs->parse_string($string) :Void

$cs->render() :Str

$cs->render($filehandle) :Void

$cs->dump() :Str

APPENDIX

ClearSilver keywords

Examples

Loops

Macros

Escapes

DEPENDENCIES

BUGS

SEE ALSO

AUTHORS

ACKNOWLEDGMENT

LICENSE AND COPYRIGHT

Module Install Instructions

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

`$tcs->dataset :HDF`

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

`$tcs->process($source, $data, ?$output, %config) :Void`

`$tcs->clear_cache :HASH`