Mini Shell

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Template::Manual::Syntax 3"
.TH Template::Manual::Syntax 3 "2024-06-21" "perl v5.32.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"
Template directives are embedded between start and end markers tags.
By default these tag markers are \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 "Outline Tags"
.IX Header "Outline Tags"
As of version 2.26, the Template Toolkit supports \*(L"outline\*(R" tags.  These have
a designated marker at the start of a line (\f(CW\*(C`%%\*(C'\fR by default) and continue to
the end of a line.  The newline character at the end of the line is discarded
(aka \*(L"chomped\*(R").
.PP
So rather than writing something like this:
.PP
.Vb 7
\&    [% IF some.list.size \-%]
\&      <ul>
\&    [%   FOREACH item IN some.list \-%]
\&        <li>[% item.html %]</li>
\&    [%   END \-%]
\&      </ul>
\&    [% END \-%]
.Ve
.PP
You can write it like this instead:
.PP
.Vb 7
\&    %% IF some.list.size
\&      <ul>
\&    %%   FOREACH item IN some.list
\&        <li>[% item.html %]</li>
\&    %%   END
\&      </ul>
\&    %% END
.Ve
.PP
Outline tags aren't enabled by default.  There are a numbers of ways you can
enable them.  The first is to use the \f(CW\*(C`TAGS\*(C'\fR directive to set the tag style
to \f(CW\*(C`outline\*(C'\fR in any templates where you want to use them.  This will enable
outline tags from that point on.
.PP
.Vb 2
\&    [% TAGS outline \-%]
\&    %% INCLUDE header
.Ve
.PP
You can set the \f(CW\*(C`TAGS\*(C'\fR back to the \f(CW\*(C`default\*(C'\fR value at some point later in the
template if you want to disable them:
.PP
.Vb 1
\&    [% TAGS default \-%]
.Ve
.PP
You can set the \f(CW\*(C`TAG_STYLE\*(C'\fR configuration option if you want then enabled in
all templates by default.  You can always use the \f(CW\*(C`[% TAGS default %]\*(C'\fR
directive to disable them in any templates or parts of templates if necessary.
.PP
.Vb 3
\&    my $tt = Template\->new({
\&        TAG_STYLE => \*(Aqoutline\*(Aq,
\&    });
.Ve
.PP
The \f(CW\*(C`OUTLINE_TAG\*(C'\fR option allows you to set the outline tag marker to something
else if you're not a fan of percent signs.  Setting this option will
automatically enable outline tags.
.PP
.Vb 3
\&    my $tt = Template\->new({
\&        OUTLINE_TAG => \*(Aq>>\*(Aq,
\&    });
.Ve
.PP
You can also use the \f(CW\*(C`TAGS\*(C'\fR directive to define your own custom tags (start,
end and now optionally, outline) for a template or part of a template.
.PP
.Vb 3
\&    [% TAGS <* *> >> %]
\&    >> INCLUDE header       # outline tag
\&    Hello <* name *>        # inline tag
.Ve
.PP
If you only specify a start and end tag then outline tags will be disabled.
.PP
.Vb 1
\&    [% TAGS <* *> %]        # no outline tags
.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
CASE\s0 (but see the \f(CW\*(C`ANYCASE\*(C'\fR option).  All directives keywords are in
\&\s-1UPPER CASE\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