GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Text::ClearSilver(3) User Contributed Perl Documentation Text::ClearSilver(3)

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

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.

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.

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.

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"

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

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.

2010-04-27 perl v5.32.1

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

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