Current File : //proc/self/root/usr/local/share/man/man3/Template::Manual::Syntax.3pm
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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::Manual::Syntax 3"
.TH Template::Manual::Syntax 3 "2011-12-20" "perl v5.10.1" "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::Manual::Syntax \- Directive syntax, structure and semantics
.SH "Tag Styles"
.IX Header "Tag Styles"
By default, template directives are embedded within the character sequences
\&\f(CW\*(C`[%\*(C'\fR and \f(CW\*(C`%]\*(C'\fR.
.PP
.Vb 1
\& [% PROCESS header %]
\&
\& <h1>Hello World!</h1>
\& <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
\&
\& [% PROCESS footer %]
.Ve
.PP
You can change the tag characters using the \f(CW\*(C`START_TAG\*(C'\fR, \f(CW\*(C`END_TAG\*(C'\fR and
\&\f(CW\*(C`TAG_STYLE\*(C'\fR configuration options. You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to
define a new tag style for the current template file.
.PP
You can also set the \f(CW\*(C`INTERPOLATE\*(C'\fR option to allow simple variable references
to be embedded directly in templates, prefixed by a \f(CW\*(C`$\*(C'\fR.
.PP
.Vb 3
\& # INTERPOLATE = 0
\& <td>[% name %]</td>
\& <td>[% email %]</td>
\&
\& # INTERPOLATE = 1
\& <td>$name</td>
\& <td>$email</td>
.Ve
.PP
Directives may be embedded anywhere in a line of text and can be split
across several lines. Insignificant whitespace is generally ignored
within the directive.
.PP
.Vb 4
\& [% INCLUDE header
\& title = \*(AqHello World\*(Aq
\& bgcol = \*(Aq#ffffff\*(Aq
\& %]
\&
\& [%INCLUDE menu align=\*(Aqright\*(Aq%]
\&
\& Name: [% name %] ([%id%])
.Ve
.SH "Comments"
.IX Header "Comments"
The \f(CW\*(C`#\*(C'\fR character is used to indicate comments within a directive.
When placed immediately inside the opening directive tag, it causes
the entire directive to be ignored.
.PP
.Vb 3
\& [%# this entire directive is ignored no
\& matter how many lines it wraps onto
\& %]
.Ve
.PP
In any other position, it causes the remainder of the current line to
be treated as a comment.
.PP
.Vb 4
\& [% # this is a comment
\& theta = 20 # so is this
\& rho = 30 # <aol>me too!</aol>
\& %]
.Ve
.SH "Chomping Whitespace"
.IX Header "Chomping Whitespace"
You can add \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`+\*(C'\fR to the immediate start or end of a directive
tag to control the whitespace chomping options. See the \f(CW\*(C`PRE_CHOMP\*(C'\fR and
\&\f(CW\*(C`POST_CHOMP\*(C'\fR options for further details.
.PP
.Vb 3
\& [% BLOCK foo \-%] # remove trailing newline
\& This is block foo
\& [%\- END %] # remove leading newline
.Ve
.SH "Implicit Directives: GET and SET"
.IX Header "Implicit Directives: GET and SET"
The simplest directives are \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR which retrieve and update
variable values respectively. The \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`SET\*(C'\fR keywords are actually
optional as the parser is smart enough to see them for what they really are
(but note the caveat below on using side-effect notation). Thus, you'll
generally see:
.PP
.Vb 2
\& [% SET foo = 10 %]
\& [% GET foo %]
.Ve
.PP
written as:
.PP
.Vb 2
\& [% foo = 10 %]
\& [% foo %]
.Ve
.PP
You can also express simple logical statements as implicit \f(CW\*(C`GET\*(C'\fR directives:
.PP
.Vb 1
\& [% title or template.title or \*(AqDefault Title\*(Aq %]
\&
\& [% mode == \*(Aqgraphics\*(Aq ? "Graphics Mode Enabled" : "Text Mode" %]
.Ve
.PP
All other directives should start with a keyword specified in \s-1UPPER\s0
\&\s-1CASE\s0 (but see the \f(CW\*(C`ANYCASE\*(C'\fR option). All directives keywords are in
\&\s-1UPPER\s0 \s-1CASE\s0 to make them visually distinctive and to distinguish them
from variables of the same name but different case. It is perfectly
valid, for example, to define a variable called \f(CW\*(C`stop\*(C'\fR which is
entirely separate from the \f(CW\*(C`STOP\*(C'\fR directive.
.PP
.Vb 1
\& [% stop = \*(AqClackett Lane Bus Depot\*(Aq %]
\&
\& The bus will next stop at [% stop %] # variable
\&
\& [% STOP %] # directive
.Ve
.SH "Block Directives"
.IX Header "Block Directives"
Directives such as \f(CW\*(C`FOREACH\*(C'\fR, \f(CW\*(C`WHILE\*(C'\fR, \f(CW\*(C`BLOCK\*(C'\fR, \f(CW\*(C`FILTER\*(C'\fR, etc., mark the
start of a block which may contain text or other directives up to the matching
\&\f(CW\*(C`END\*(C'\fR directive. Blocks may be nested indefinitely. The \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR,
\&\f(CW\*(C`ELSIF\*(C'\fR and \f(CW\*(C`ELSE\*(C'\fR directives also define blocks and may be grouped together
in the usual manner.
.PP
.Vb 3
\& [% FOREACH item = [ \*(Aqfoo\*(Aq \*(Aqbar\*(Aq \*(Aqbaz\*(Aq ] %]
\& * Item: [% item %]
\& [% END %]
\&
\& [% BLOCK footer %]
\& Copyright 2000 [% me %]
\& [% INCLUDE company/logo %]
\& [% END %]
\&
\& [% IF foo %]
\& [% FOREACH thing = foo.things %]
\& [% thing %]
\& [% END %]
\& [% ELSIF bar %]
\& [% INCLUDE barinfo %]
\& [% ELSE %]
\& do nothing...
\& [% END %]
.Ve
.PP
Block directives can also be used in a convenient side-effect notation.
.PP
.Vb 1
\& [% INCLUDE userinfo FOREACH user = userlist %]
\&
\& [% INCLUDE debugtxt msg="file: $error.info"
\& IF debugging %]
\&
\& [% "Danger Will Robinson" IF atrisk %]
.Ve
.PP
versus:
.PP
.Vb 3
\& [% FOREACH user = userlist %]
\& [% INCLUDE userinfo %]
\& [% END %]
\&
\& [% IF debugging %]
\& [% INCLUDE debugtxt msg="file: $error.info" %]
\& [% END %]
\&
\& [% IF atrisk %]
\& Danger Will Robinson
\& [% END %]
.Ve
.SH "Capturing Block Output"
.IX Header "Capturing Block Output"
The output of a directive can be captured by simply assigning the directive
to a variable.
.PP
.Vb 1
\& [% headtext = PROCESS header title="Hello World" %]
\&
\& [% people = PROCESS userinfo FOREACH user = userlist %]
.Ve
.PP
This can be used in conjunction with the \f(CW\*(C`BLOCK\*(C'\fR directive for defining large
blocks of text or other content.
.PP
.Vb 6
\& [% poem = BLOCK %]
\& The boy stood on the burning deck,
\& His fleece was white as snow.
\& A rolling stone gathers no moss,
\& And Keith is sure to follow.
\& [% END %]
.Ve
.PP
Note one important caveat of using this syntax in conjunction with side-effect
notation. The following directive does not behave as might be expected:
.PP
.Vb 1
\& [% var = \*(Aqvalue\*(Aq IF some_condition %] # does not work
.Ve
.PP
In this case, the directive is interpreted as (spacing added for clarity)
.PP
.Vb 3
\& [% var = IF some_condition %]
\& value
\& [% END %]
.Ve
.PP
rather than
.PP
.Vb 3
\& [% IF some_condition %]
\& [% var = \*(Aqvalue\*(Aq %]
\& [% END %]
.Ve
.PP
The variable is assigned the output of the \f(CW\*(C`IF\*(C'\fR block which returns
\&\f(CW\*(Aqvalue\*(Aq\fR if true, but nothing if false. In other words, the following
directive will always cause 'var' to be cleared.
.PP
.Vb 1
\& [% var = \*(Aqvalue\*(Aq IF 0 %]
.Ve
.PP
To achieve the expected behaviour, the directive should be written as:
.PP
.Vb 1
\& [% SET var = \*(Aqvalue\*(Aq IF some_condition %]
.Ve
.SH "Chaining Filters"
.IX Header "Chaining Filters"
Multiple \f(CW\*(C`FILTER\*(C'\fR directives can be chained together in sequence. They
are called in the order defined, piping the output of one into the
input of the next.
.PP
.Vb 1
\& [% PROCESS somefile FILTER truncate(100) FILTER html %]
.Ve
.PP
The pipe character, \f(CW\*(C`|\*(C'\fR, can also be used as an alias for \f(CW\*(C`FILTER\*(C'\fR.
.PP
.Vb 1
\& [% PROCESS somefile | truncate(100) | html %]
.Ve
.SH "Multiple Directive Blocks"
.IX Header "Multiple Directive Blocks"
Multiple directives can be included within a single tag when delimited
by semi-colons. Note however that the \f(CW\*(C`TAGS\*(C'\fR directive must always
be specified in a tag by itself.
.PP
.Vb 6
\& [% IF title;
\& INCLUDE header;
\& ELSE;
\& INCLUDE other/header title="Some Other Title";
\& END
\& %]
.Ve
.PP
versus
.PP
.Vb 5
\& [% IF title %]
\& [% INCLUDE header %]
\& [% ELSE %]
\& [% INCLUDE other/header title="Some Other Title" %]
\& [% END %]
.Ve
Mini Shell