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 ClearSilver template engine.
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.
none
This is ClearSilver core feature, and a shortcut for dataset => { Config => VarEscapeMode => ... }.
dataset => { Config => VarEscapeMode => ... }
TagStart => $str
Sets the ClearSilver starting tag. Default to cs.
cs
This is ClearSilver core feature, and a shortcut for dataset => { Config => TagStart => ... }.
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 => { 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.
substr
sprintf
lc
uc
lcfirst
ucfirst
trim
nl2br
encoding => 'utf8' | 'bytes'
Specifies the encoding. Note that utf8 works as the use utf8 pragma.
utf8
use utf8
$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.
>= 0
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().
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.
Config.*
VarEscapeMode => 'html'
$tcs->clear_cache :HASH
Clears the global file cache, and returns the old one.
This is a low-level interface to the HDF* (Hierarchial Data Format) data structure.
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.
undef
Cyclic references will not be converted correctly (TODO).
Adds $hdf_source into the dataset.
$hdf_source may be a reference to data structure or an HDF string.
Returns the value of a named node in the dataset.
Returns the dataset node at a named location.
Similar to get_obj except all the nodes are created if they do not exist.
get_obj
Returns the first child of a named node.
Returns the first child of the dataset.
Returns the next node of the dataset.
Returns the name of the node.
Returns the value of the node.
Sets the value of a named node.
Copies a value from one location in the dataset to another.
Sets a part of the dataset to link to another.
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; });
Reads an HDF data file.
Writes an HDF data file.
Serializes the dataset to an HDF string, which can be passed into add().
add()
Removes a named node of the dataset.
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.
CSPARSE*
Creates a CS context with $hdf_source, which may be a reference to data structure or an HDF string..
Parses a CS template file.
Parses a CS template string.
Renders the CS parse tree and returns the result as a string.
Renders the CS parse tree and print the result to a filehandle.
Dumps the CS parse tree for debugging.
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
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.
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)
my %vars = ( uri => q{<a href="http://example.com">example.com</a>}, );
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="http://example.com">example.com</a> escape: "html": <a href="http://example.com">example.com</a> 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
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.
http://www.clearsilver.net/
Data::ClearSilver::HDF
Catalyst::View::ClearSilver
Template
Craftworks <craftwork(at)cpan.org>
Goro Fuji (gfx) <gfuji(at)cpan.org>
The ClearSilver template engine is developed by Neotonic Software Corp, and Copyright (c) 2003 Brandon Long.
This distribution includes the ClearSilver distribution. See http://www.clearsilver.net/license.hdf 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.
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.