| Path : /usr/local/share/man/man3/ |
|
|
| Current File : //usr/local/share/man/man3/Template::Toolkit::Simple.3pm |
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Template::Toolkit::Simple 3"
.TH Template::Toolkit::Simple 3 "2014-12-09" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Toolkit::Simple \- A Simple Interface to Template Toolkit
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Template::Toolkit::Simple;
\&
\& print tt
\& \->path([\*(Aq./\*(Aq, \*(Aqtemplate/\*(Aq])
\& \->data(\*(Aqvalues.yaml\*(Aq)
\& \->post_chomp
\& \->render(\*(Aqfoo.tt\*(Aq);
.Ve
.PP
or from the command line:
.PP
.Vb 1
\& tt\-render \-\-path=./:template/ \-\-data=values.yaml \-\-post\-chomp foo.tt
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Template Toolkit is the best Perl template framework. The only problem with it
is that using it for simple stuff is a little bit cumbersome. Also there is no
good utility for using it from the command line.
.PP
This module is a simple wrapper around Template Toolkit. It exports a function
called \f(CW\*(C`tt\*(C'\fR which returns a new Template::Toolkit::Simple object. The object
supports method calls for setting all the Template Toolkit options.
.PP
This module also installs a program called \f(CW\*(C`tt\-render\*(C'\fR which you can use
from the command line to render templates with all the power of the Perl
object. All of the object methods become command line arguments in the
command line version.
.SH "COMMAND LINE USAGE"
.IX Header "COMMAND LINE USAGE"
This command renders the named file and prints the output to \s-1STDOUT.\s0 If an
error occurs, it is printed to \s-1STDERR.\s0
.PP
.Vb 1
\& tt\-render [template\-options] file\-name
.Ve
.SH "TEMPLATE PATH"
.IX Header "TEMPLATE PATH"
When using Template::Toolkit::Simple or \f(CW\*(C`tt\-render\*(C'\fR, the most common
parameters you will use are the main template file name and the directory of
supporting templates. As a convenience, you can specify these together.
.PP
This:
.PP
.Vb 2
\& tt\->render(\*(Aqfoo//bar/baz.tt\*(Aq);
\& > tt\-render foo//bar/baz.tt # command line version
.Ve
.PP
is the same as:
.PP
.Vb 2
\& tt\->include_path(\*(Aqfoo/\*(Aq)\->render(\*(Aqbar/baz.tt\*(Aq);
\& > tt\-render \-\-include_path=foo/ bar/baz.tt # command line version
.Ve
.PP
Just use a double slash to separate the path from the template. This is extra
handy on the command line, because (at least in Bash) tab completion still
works after you specify the '//'.
.SH "EXPORTED SUBROUTINES"
.IX Header "EXPORTED SUBROUTINES"
.IP "tt" 4
.IX Item "tt"
Simply returns a new Template::Toolkit::Simple object. This is Simple
sugar for:
.Sp
.Vb 1
\& Template::Toolkit::Simple\->new();
.Ve
.Sp
It takes no parameters.
.SH "METHODS"
.IX Header "METHODS"
This section describes the methods that are not option setting methods. Those
methods are described below.
.IP "\fInew()\fR" 4
.IX Item "new()"
Return a new Template::Toolkit::Simple object. Takes no parameters.
.ie n .IP "render($template, $data);" 4
.el .IP "render($template, \f(CW$data\fR);" 4
.IX Item "render($template, $data);"
This is the method that actually renders the template. It is similar to the
Template Toolkit \f(CW\*(C`process\*(C'\fR method, except that it actually returns the
template result as a string. It returns undef if an error occurs.
.Sp
The \f(CW$data\fR field is optional and can be set with the \f(CW\*(C`data\*(C'\fR method.
.Sp
If you need more control, see the process command below:
.ie n .IP "process($template, $data, $output, %options);" 4
.el .IP "process($template, \f(CW$data\fR, \f(CW$output\fR, \f(CW%options\fR);" 4
.IX Item "process($template, $data, $output, %options);"
This command is simply a proxy to the Template Toolkit \f(CW\*(C`process\*(C'\fR command. All
the parameters you give it are passed to the real \f(CW\*(C`process\*(C'\fR command and the
result is returned. See Template for more information.
.IP "output($filepath)" 4
.IX Item "output($filepath)"
Specify a filepath to print the template result to.
.IP "\fIerror()\fR" 4
.IX Item "error()"
This method is a proxy to the Template Toolkit \f(CW\*(C`error\*(C'\fR method. It returns the
error message if there was an error.
.SH "OPTION METHODS"
.IX Header "OPTION METHODS"
All of the Template Toolkit options are available as methods to
Template::Toolkit::Simple objects, and also as command line options to the \f(CW\*(C`tt\-
render\*(C'\fR command.
.PP
For example, the \f(CW\*(C`POST_CHOMP\*(C'\fR options is available in the following ways:
.PP
.Vb 3
\& tt\->post_chomp # turn POST_CHOMP on
\& tt\->post_chomp(1) # turn POST_CHOMP on
\& tt\->post_chomp(0) # turn POST_CHOMP off
\&
\& \-\-post_chomp # turn POST_CHOMP on
\& \-\-post\-chomp # same. use \- instead of _
\& \-\-post_chomp=1 # turn POST_CHOMP on
\& \-\-post_chomp=0 # turn POST_CHOMP off
.Ve
.PP
If the method functionality is not explained below, please refer to
Template.
.ie n .IP """config($file_name || $hash)""" 4
.el .IP "\f(CWconfig($file_name || $hash)\fR" 4
.IX Item "config($file_name || $hash)"
If you have a common set of Template Toolkit options stored in a file, you can
use this method to read and parse the file, and set the appropriate options.
.Sp
The currently supported file formats are \s-1YAML, JSON\s0 and \s-1XML.\s0 The format
is determined by the file extension, so use the appropriate one. Note
that XML::Simple is used to parse \s-1XML\s0 files and \s-1JSON::XS\s0 is used to parse
\&\s-1JSON\s0 files.
.ie n .IP """data($file_name || $hash)""" 4
.el .IP "\f(CWdata($file_name || $hash)\fR" 4
.IX Item "data($file_name || $hash)"
Most templates use a hash object of data to access values while rendering. You
can specify this data in a file or with a hash reference.
.Sp
The currently supported file formats are \s-1YAML, JSON\s0 and \s-1XML.\s0 The format is
determined by the file extension, so use the appropriate one. Note the
XML::Simple is used to parse \s-1XML\s0 files.
.ie n .IP """include_path($template_directories)""" 4
.el .IP "\f(CWinclude_path($template_directories)\fR" 4
.IX Item "include_path($template_directories)"
Default is undef
.Sp
This method allows you to specify the directories that are searched to find
templates. You can specify this as a string containing a single directory, an
array ref of strings containing directory names, or as a string containing
multiple directories separated by ':'.
.ie n .IP """path()""" 4
.el .IP "\f(CWpath()\fR" 4
.IX Item "path()"
Default is undef
.Sp
This is a shorter name for \f(CW\*(C`include_path\*(C'\fR. It does the exact same thing.
.ie n .IP """start_tag()""" 4
.el .IP "\f(CWstart_tag()\fR" 4
.IX Item "start_tag()"
Default is '[%'
.ie n .IP """end_tag()""" 4
.el .IP "\f(CWend_tag()\fR" 4
.IX Item "end_tag()"
Default is '%]'
.ie n .IP """tag_style()""" 4
.el .IP "\f(CWtag_style()\fR" 4
.IX Item "tag_style()"
Default is 'template'
.ie n .IP """pre_chomp()""" 4
.el .IP "\f(CWpre_chomp()\fR" 4
.IX Item "pre_chomp()"
Default is 0
.ie n .IP """post_chomp()""" 4
.el .IP "\f(CWpost_chomp()\fR" 4
.IX Item "post_chomp()"
Default is 0
.ie n .IP """trim()""" 4
.el .IP "\f(CWtrim()\fR" 4
.IX Item "trim()"
Default is 0
.ie n .IP """interpolate()""" 4
.el .IP "\f(CWinterpolate()\fR" 4
.IX Item "interpolate()"
Default is 0
.ie n .IP """anycase()""" 4
.el .IP "\f(CWanycase()\fR" 4
.IX Item "anycase()"
Default is 0
.ie n .IP """delimiter()""" 4
.el .IP "\f(CWdelimiter()\fR" 4
.IX Item "delimiter()"
Default is ':'
.ie n .IP """absolute()""" 4
.el .IP "\f(CWabsolute()\fR" 4
.IX Item "absolute()"
Default is 0
.ie n .IP """relative()""" 4
.el .IP "\f(CWrelative()\fR" 4
.IX Item "relative()"
Default is 0
.ie n .IP """strict()""" 4
.el .IP "\f(CWstrict()\fR" 4
.IX Item "strict()"
Default is 0
.ie n .IP """default()""" 4
.el .IP "\f(CWdefault()\fR" 4
.IX Item "default()"
Default is undef
.ie n .IP """blocks()""" 4
.el .IP "\f(CWblocks()\fR" 4
.IX Item "blocks()"
Default is undef
.ie n .IP """auto_reset()""" 4
.el .IP "\f(CWauto_reset()\fR" 4
.IX Item "auto_reset()"
Default is 1
.ie n .IP """recursion()""" 4
.el .IP "\f(CWrecursion()\fR" 4
.IX Item "recursion()"
Default is 0
.ie n .IP """eval_perl()""" 4
.el .IP "\f(CWeval_perl()\fR" 4
.IX Item "eval_perl()"
Default is 0
.ie n .IP """pre_process()""" 4
.el .IP "\f(CWpre_process()\fR" 4
.IX Item "pre_process()"
Default is undef
.ie n .IP """post_process()""" 4
.el .IP "\f(CWpost_process()\fR" 4
.IX Item "post_process()"
Default is undef
.ie n .IP """process_template()""" 4
.el .IP "\f(CWprocess_template()\fR" 4
.IX Item "process_template()"
Default is undef
.Sp
This is a proxy to the Template Toolkit \s-1PROCESS\s0 option. The \f(CW\*(C`process\*(C'\fR method
is used to actually process a template.
.ie n .IP """error_template()""" 4
.el .IP "\f(CWerror_template()\fR" 4
.IX Item "error_template()"
Default is undef
.Sp
This is a proxy to the Template Toolkit \s-1ERROR\s0 option. The \f(CW\*(C`error()\*(C'\fR method
returns the error message on a failure.
.ie n .IP """debug()""" 4
.el .IP "\f(CWdebug()\fR" 4
.IX Item "debug()"
Default is 0
.ie n .IP """cache_size()""" 4
.el .IP "\f(CWcache_size()\fR" 4
.IX Item "cache_size()"
Default is undef
.ie n .IP """compile_ext()""" 4
.el .IP "\f(CWcompile_ext()\fR" 4
.IX Item "compile_ext()"
Default is undef
.ie n .IP """compile_dir()""" 4
.el .IP "\f(CWcompile_dir()\fR" 4
.IX Item "compile_dir()"
Default is undef
.ie n .IP """encoding()""" 4
.el .IP "\f(CWencoding()\fR" 4
.IX Item "encoding()"
Default is 'utf8'
.SH "AUTHOR"
.IX Header "AUTHOR"
Ingy do\*:t Net <ingy@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2008\-2014. Ingy do\*:t Net.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
See <http://www.perl.com/perl/misc/Artistic.html>