The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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

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.

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.

SEE ALSO

http://www.clearsilver.net/

Data::ClearSilver::HDF

Catalyst::View::ClearSilver

Template

AUTHORS

Craftworks <craftwork(at)cpan.org>

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

ACKNOWLEDGMENT

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.

LICENSE AND COPYRIGHT

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.