.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
.\"
.\" 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 "Sympa::Template 3Sympa"
.TH Sympa::Template 3Sympa "2022-11-25" "6.2.70" "sympa 6.2.70"
.\" 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"
Sympa::Template \- Template parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Sympa::Template;
\&  
\&  $template = Sympa::Template\->new;
\&  $template\->parse($data, $tpl_file, \e$output);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Methods"
.IX Subsection "Methods"
.ie n .IP "new ( $that, [ property defaults ] )" 4
.el .IP "new ( \f(CW$that\fR, [ property defaults ] )" 4
.IX Item "new ( $that, [ property defaults ] )"
\&\fIConstructor\fR.
Creates new Sympa::Template instance.
.Sp
Parameters:
.RS 4
.ie n .IP "$that" 4
.el .IP "\f(CW$that\fR" 4
.IX Item "$that"
Context.  Site, Robot or List.
.IP "property defaults" 4
.IX Item "property defaults"
Pairs to specify property defaults.
.RE
.RS 4
.RE
.ie n .IP "parse ( $data, $tpl, $output, [ has_header => 1 ] )" 4
.el .IP "parse ( \f(CW$data\fR, \f(CW$tpl\fR, \f(CW$output\fR, [ has_header => 1 ] )" 4
.IX Item "parse ( $data, $tpl, $output, [ has_header => 1 ] )"
\&\fIInstance method\fR.
Parses template and outputs result.
.Sp
Parameters:
.RS 4
.ie n .IP "$data" 4
.el .IP "\f(CW$data\fR" 4
.IX Item "$data"
A \s-1HASH\s0 ref containing the data.
.ie n .IP "$tpl" 4
.el .IP "\f(CW$tpl\fR" 4
.IX Item "$tpl"
A string that contains the file name.
Or, scalarref or arrayref that contains the template.
.ie n .IP "$output" 4
.el .IP "\f(CW$output\fR" 4
.IX Item "$output"
A file descriptor or a reference to scalar for the output.
.IP "has_header => 0|1" 4
.IX Item "has_header => 0|1"
If 1 is set, prepended header fields are assumed,
i.e. one newline will be inserted at beginning of output.
.IP "is_not_template => 0|1" 4
.IX Item "is_not_template => 0|1"
This option was obsoleted.
.RE
.RS 4
.Sp
Returns:
.Sp
On success, returns \f(CW1\fR and clears {last_error} property.
Otherwise returns \f(CW\*(C`undef\*(C'\fR and sets {last_error} property.
.RE
.SS "Properties"
.IX Subsection "Properties"
Instance of Sympa::Template may have following attributes.
.IP "{allow_absolute}" 4
.IX Item "{allow_absolute}"
If set, absolute paths in \f(CW\*(C`INCLUDE\*(C'\fR directive are allowed.
.IP "{include_path}" 4
.IX Item "{include_path}"
Reference to array containing additional template search paths.
.IP "{last_error}" 4
.IX Item "{last_error}"
\&\fIRead only\fR.
Error occurred at the last execution of parse, or \f(CW\*(C`undef\*(C'\fR.
.IP "{subdir}, {lang}, {lang_only}" 4
.IX Item "{subdir}, {lang}, {lang_only}"
\&\s-1TBD.\s0
.SS "Filters"
.IX Subsection "Filters"
These custom filters are defined by Sympa::Template.
See Template::Manual::Filters about usage of filters.
.IP "canonic_email" 4
.IX Item "canonic_email"
Canonicalize e\-mail address.
.Sp
This filter was added by Sympa 6.2.17.
.IP "decode_utf8" 4
.IX Item "decode_utf8"
No longer used.
.IP "encode_utf8" 4
.IX Item "encode_utf8"
No longer used.
.IP "escape_cstr" 4
.IX Item "escape_cstr"
Applies C\-style escaping of a string (not enclosed by quotes).
.Sp
This filter was added on Sympa 6.2.37b.1.
.IP "escape_quote" 4
.IX Item "escape_quote"
Escape quotation marks.
.Sp
\&\fBDeprecated\fR.
Use escape_cstr.
.IP "escape_url" 4
.IX Item "escape_url"
Escapes \s-1URL.\s0
.Sp
This was \s-1OBSOLETED.\s0  Use \*(L"mailtourl\*(R" instead.
.IP "escape_xml" 4
.IX Item "escape_xml"
\&\s-1OBSOLETED.\s0  Use \*(L"xml\*(R" in Template::Manual::Filters.
.IP "helploc ( parameters )" 4
.IX Item "helploc ( parameters )"
.PD 0
.IP "l ( parameters )" 4
.IX Item "l ( parameters )"
.IP "loc ( parameters )" 4
.IX Item "loc ( parameters )"
.PD
Translates text using catalog.
Placeholders (\f(CW%1\fR, \f(CW%2\fR, ...) are replaced by parameters.
.IP "locdt ( argument )" 4
.IX Item "locdt ( argument )"
Generates formatted (i18n'ized) date/time.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
\&\fBstrftime()\fR style format string.
.IP "argument" 4
.IX Item "argument"
A string representing date/time:
\&\*(L"\s-1YYYY/MM\*(R", \*(L"YYYY/MM/DD\*(R", \*(L"YYYY/MM/DD/HH/MM\*(R"\s0 or \*(L"\s-1YYYY/MM/DD/HH/MM/SS\*(R".\s0
.RE
.RS 4
.RE
.IP "mailbox ( email, [ comment ] )" 4
.IX Item "mailbox ( email, [ comment ] )"
Generates mailbox string appropriately encoded to suit for addresses
in header fields.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
Display name, if any.
.IP "email" 4
.IX Item "email"
E\-mail address.
.IP "comment" 4
.IX Item "comment"
Comment, if any.
.RE
.RS 4
.Sp
This filter was introduced on Sympa 6.2.42.
.RE
.IP "mailto ( email, [ {key => val, ...}, [ nodecode ] ] )" 4
.IX Item "mailto ( email, [ {key => val, ...}, [ nodecode ] ] )"
Generates \s-1HTML\s0 fragment linking to \f(CW\*(C`mailto:\*(C'\fR \s-1URL,\s0
i.e. \f(CW\*(C`<a href="mailto:\f(CIemail\f(CW">\f(CIfiltered text\f(CW</a>\*(C'\fR.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
Content of linking element.
If it does not contain nonspaces, e\-mail address will be used.
.IP "email" 4
.IX Item "email"
E\-mail address(es) to be linked.
.IP "{key => val, ...}" 4
.IX Item "{key => val, ...}"
Optional query.
.IP "nodecode" 4
.IX Item "nodecode"
If true, assumes arguments are not encoded as \s-1HTML\s0 entities.
By default entities are decoded at first.
.Sp
This option does \fInot\fR affect filtered text.
.RE
.RS 4
.Sp
Note:
This filter was introduced by Sympa 6.2.14.
.RE
.IP "mailtourl ( [ {key = val, ...} ] )" 4
.IX Item "mailtourl ( [ {key = val, ...} ] )"
Generates \f(CW\*(C`mailto:\*(C'\fR \s-1URL.\s0
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
E\-mail address(es).
Note that any characters must not be encoded as \s-1HTML\s0 entities.
.IP "{key = val, ...}" 4
.IX Item "{key = val, ...}"
Optional query.
Note that any characters must not be encoded as \s-1HTML\s0 entities.
.RE
.RS 4
.Sp
Note:
This filter was introduced by Sympa 6.2.14.
.RE
.IP "obfuscate ( mode )" 4
.IX Item "obfuscate ( mode )"
Obfuscates email addresses in the \s-1HTML\s0 text according to mode.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
\&\s-1HTML\s0 document or fragment.
.IP "mode" 4
.IX Item "mode"
Obfuscation mode.  \f(CW\*(C`at\*(C'\fR or \f(CW\*(C`javascript\*(C'\fR.
Invalid mode will be silently ignored.
.RE
.RS 4
.Sp
Note:
This filter was introduced by Sympa 6.2.14.
.RE
.IP "optdesc ( type, withval )" 4
.IX Item "optdesc ( type, withval )"
Generates i18n'ed description of list parameter value.
.Sp
As of Sympa 6.2.17, if it is called by the web templates
(in \f(CW\*(C`web_tt2\*(C'\fR subdirectories),
special characters in result will be encoded.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
Parameter value.
.IP "type" 4
.IX Item "type"
Type of list parameter value:
Special types (See \*(L"field_type\*(R" in Sympa::ListDef)
or others (default).
.IP "withval" 4
.IX Item "withval"
If parameter value is added to the description.  False by default.
.RE
.RS 4
.RE
.IP "qencode" 4
.IX Item "qencode"
Encode string by \s-1MIME\s0 header encoding.
Despite its name, appropriate encoding scheme
(\f(CW\*(C`Q\*(C'\fR or \f(CW\*(C`B\*(C'\fR) will be chosen.
.IP "unescape" 4
.IX Item "unescape"
No longer used.
.IP "url_abs ( ... )" 4
.IX Item "url_abs ( ... )"
Same as \*(L"url_rel\*(R" but gives absolute \s-1URI.\s0
.Sp
Note:
This filter was introduced by Sympa 6.2.15.
.IP "url_rel ( [ paths, [ query, [ fragment ] ] ] )" 4
.IX Item "url_rel ( [ paths, [ query, [ fragment ] ] ] )"
Gives relative \s-1URI\s0 for specified action.
.Sp
If it is called by the web templates (in \f(CW\*(C`web_tt2\*(C'\fR subdirectories),
\&\s-1HTML\s0 entities in the arguments will be decoded
and special characters in resulting \s-1URL\s0 will be encoded.
.RS 4
.IP "Filtered text" 4
.IX Item "Filtered text"
Name of action.
.IP "paths" 4
.IX Item "paths"
Array.  Additional path components.
.IP "query" 4
.IX Item "query"
Hash.  Optional query.
.IP "fragment" 4
.IX Item "fragment"
Scalar.  Optional fragment.
.RE
.RS 4
.Sp
Note:
This filter was introduced by Sympa 6.2.15.
.RE
.IP "wrap ( init, subs, cols )" 4
.IX Item "wrap ( init, subs, cols )"
Generates folded text.
.RS 4
.IP "init" 4
.IX Item "init"
Indentation (or its length) of each paragraph if any.
.IP "subs" 4
.IX Item "subs"
Indentation (or its length) of other lines if any.
.IP "cols" 4
.IX Item "cols"
Line width, defaults to 78.
.RE
.RS 4
.RE
.PP
\&\fBNote\fR:
.PP
Calls of \*(L"helploc\*(R", \*(L"loc\*(R" and \*(L"locdt\*(R" in template files are
extracted during packaging process and are added to translation catalog.
.SS "Plugins"
.IX Subsection "Plugins"
Plugins may be placed under \fILIBDIR/Sympa/Template/Plugin\fR.
See <https://www.sympa.community/manual/customize/template\-plugins.html>
about usage of plugins.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template::Manual.
.SH "HISTORY"
.IX Header "HISTORY"
Sympa 4.2b.3 adopted template engine based on Template Toolkit.
.PP
Plugin feature was added on Sympa 6.2.
.PP
tt2 module was renamed to Sympa::Template on Sympa 6.2.