Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::ClearSilver(3)  User Contributed Perl Documentation Text::ClearSilver(3)

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:

       o   that	any scalar values, including blessed references, will be
	   simply stringified.

       o   "undef" is simply ignored.

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

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.

perl v5.32.1			  2010-04-27		  Text::ClearSilver(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | APPENDIX | DEPENDENCIES | BUGS | SEE ALSO | AUTHORS | ACKNOWLEDGMENT | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::ClearSilver&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help