.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Rex::Template 3pm"
.TH Rex::Template 3pm "2023-08-09" "perl v5.36.0" "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"
Rex::Template \- simple template engine
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Rex::Template;
\&
\& my $template = Rex::Template\->new;
\&
\& print $template\->parse($content, \e%template_vars);
\& print $template\->parse($content, @template_vars);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a simple template engine for configuration files. It is included mostly for backwards compatibility, and it is recommended to use Rex::Template::NG instead (for better control of chomping new lines, and better diagnostics if things go wrong).
.SS "\s-1SYNTAX\s0"
.IX Subsection "SYNTAX"
The following syntax is recognized:
.IP "\(bu" 4
anything between \f(CW\*(C`<%\*(C'\fR and \f(CW\*(C`%>\*(C'\fR markers are considered as a template directive, which is treated as Perl code
.IP "\(bu" 4
if the opening marker is followed by an equal sign (\f(CW\*(C`<%=\*(C'\fR) or a plus sign (\f(CW\*(C`<%+\*(C'\fR), then the directive is replaced with the value it evaluates to
.IP "\(bu" 4
if the closing marker is prefixed with a minus sign (\f(CW\*(C`\-%>\*(C'\fR), then any trailing newlines are chomped for that directive
.PP
The built-in template support is intentionally kept basic and simple. For anything more sophisticated, please use your favorite template engine.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
Plain text is unchanged:
.PP
.Vb 1
\& my $result = $template\->parse( \*(Aqone two three\*(Aq, {} );
\&
\& # $result is \*(Aqone two three\*(Aq
.Ve
.PP
Variable interpolation:
.PP
.Vb 4
\& my $result = template\->parse( \*(AqHello, this is <%= $::name %>\*(Aq, { name => \*(Aqfoo\*(Aq } ); # original format
\& my $result = template\->parse( \*(AqHello, this is <%+ $::name %>\*(Aq, { name => \*(Aqfoo\*(Aq } ); # alternative format with + sign
\& my $result = template\->parse( \*(AqHello, this is <%= $name %>\*(Aq,   { name => \*(Aqfoo\*(Aq } ); # local variables
\& my $result = template\->parse( \*(AqHello, this is <%= $name %>\*(Aq,     name => \*(Aqfoo\*(Aq   ); # array of variables, instead of hashref
\&
\& # $result is \*(AqHello, this is foo\*(Aq for all cases above
.Ve
.PP
Simple evaluation:
.PP
.Vb 2
\& my $result = $template\->parse( \*(Aq<%= join("/", @{$elements} ) %>\*(Aq, elements => [qw(one two three)] );
\& # $result is \*(Aqone/two/three\*(Aq
.Ve
.PP
Embedded code blocks:
.PP
.Vb 5
\& my $content = \*(Aq<% if ($logged_in) { %>
\& Logged in!
\& <% } else { %>
\& Logged out!
\& <% } %>\*(Aq;
\&
\& my $result = $template\->parse( $content, logged_in => 1 );
\&
\& # $result is "\enLogged in!\en"
.Ve
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Not much, mainly due to the internal approach of the module.
.PP
If there was a problem, it prints an \f(CW\*(C`INFO\*(C'\fR level \fI\*(L"syntax error at ...\*(R"\fR, followed by a \f(CW\*(C`WARN\*(C'\fR about \fI\*(L"It seems that there was an error processing the template because the result is empty.\*(R"\fR, and finally \fI\*(L"Error processing template at ...\*(R"\fR.
.PP
The beginning of the reported syntax error might give some clue where the error happened in the template, but that's it.
.PP
Use Rex::Template::NG instead for better diagnostics.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
If \f(CW$Rex::Template::BE_LOCAL\fR is set to a true value, then local template variables are supported instead of only global ones (\f(CW$foo\fR vs \f(CW$::foo\fR). The default value is \f(CW1\fR since Rex\-0.41. It can be disabled with the no_local_template_vars feature flag.
.PP
If \f(CW$Rex::Template::DO_CHOMP\fR is set to a true value, then any trailing new line character resulting from template directives are chomped. Defaults to \f(CW0\fR.
.PP
This module does not support any environment variables.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .SS "parse($content, $variables)"
.el .SS "parse($content, \f(CW$variables\fP)"
.IX Subsection "parse($content, $variables)"
Parse \f(CW$content\fR as a template, using \f(CW$variables\fR hash reference to pass name-value pairs of variables to make them available for the template function.
.PP
Alternatively, the variables may be passed as an array instead of a hash reference.
.ie n .SS "is_defined($variable, $default_value)"
.el .SS "is_defined($variable, \f(CW$default_value\fP)"
.IX Subsection "is_defined($variable, $default_value)"
This function will check if \f(CW$variable\fR is defined. If yes, it will return the value of \f(CW$variable\fR, otherwise it will return \f(CW$default_value\fR.
.PP
You can use this function inside your templates, for example:
.PP
.Vb 1
\& ServerTokens <%= is_defined( $::server_tokens, \*(AqProd\*(Aq ) %>
.Ve
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
It might not be able to chomp new line characters resulting from templates in every case.
.PP
It can't report useful diagnostic messages upon errors.
.PP
Use Rex::Template::NG instead.