.\" 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
.\" ========================================================================
.\"
.IX Title "Expr 3pm"
.TH Expr 3pm "2021-01-05" "perl v5.32.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"
HTML::Template::Expr \- HTML::Template extension adding expression support
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use HTML::Template::Expr;
\&
\& my $template = HTML::Template::Expr\->new(filename => \*(Aqfoo.tmpl\*(Aq);
\& $template\->param(banana_count => 10);
\& print $template\->output();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an extension to HTML::Template which allows
expressions in the template syntax. This is purely an addition \- all
the normal HTML::Template options, syntax and behaviors will still
work. See HTML::Template for details.
.PP
Expression support includes comparisons, math operations, string
operations and a mechanism to allow you add your own functions at
runtime. The basic syntax is:
.PP
.Vb 3
\&
\& I\*(Aqve got a lot of bananas.
\&
.Ve
.PP
This will output \*(L"I've got a lot of bananas\*(R" if you call:
.PP
.Vb 1
\& $template\->param(banana_count => 100);
.Ve
.PP
In your script. <\s-1TMPL_VAR\s0>s also work with expressions:
.PP
.Vb 1
\& I\*(Aqd like to have bananas.
.Ve
.PP
This will output \*(L"I'd like to have 200 bananas.\*(R" with the same \fBparam()\fR
call as above.
.SH "MOTIVATION"
.IX Header "MOTIVATION"
Some of you may wonder if I've been replaced by a pod person. Just
for the record, I still think this sort of thing should be avoided.
However, I realize that there are some situations where allowing the
template author some programmatic leeway can be invaluable.
.PP
If you don't like it, don't use this module. Keep using plain ol'
HTML::Template \- I know I will! However, if you find yourself needing
a little programming in your template, for whatever reason, then this
module may just save you from HTML::Mason.
.SH "BASIC SYNTAX"
.IX Header "BASIC SYNTAX"
Variables are unquoted alphanumeric strings with the same restrictions
as variable names in HTML::Template. Their values are set through
\&\fBparam()\fR, just like normal HTML::Template variables. For example,
these two lines are equivalent:
.PP
.Vb 1
\&
\&
\&
.Ve
.PP
Numbers are unquoted strings of numbers and may have a single \*(L".\*(R" to
indicate a floating point number. For example:
.PP
.Vb 1
\&
.Ve
.PP
String constants must be enclosed in quotes, single or double. For example:
.PP
.Vb 1
\&
.Ve
.PP
You can string together operators to produce complex booleans:
.PP
.Vb 3
\&
\& I\*(Aqm in a complex situation.
\&
.Ve
.PP
The parser is pretty simple, so you may need to use parenthesis to get
the desired precedence.
.SH "COMPARISON"
.IX Header "COMPARISON"
Here's a list of supported comparison operators:
.IP "\(bu" 4
Numeric Comparisons
.RS 4
.IP "\(bu" 4
<
.IP "\(bu" 4
>
.IP "\(bu" 4
==
.IP "\(bu" 4
!=
.IP "\(bu" 4
>=
.IP "\(bu" 4
<=
.IP "\(bu" 4
<=>
.RE
.RS 4
.RE
.IP "\(bu" 4
String Comparisons
.RS 4
.IP "\(bu" 4
gt
.IP "\(bu" 4
lt
.IP "\(bu" 4
eq
.IP "\(bu" 4
ne
.IP "\(bu" 4
ge
.IP "\(bu" 4
le
.IP "\(bu" 4
cmp
.RE
.RS 4
.RE
.SH "MATHEMATICS"
.IX Header "MATHEMATICS"
The basic operators are supported:
.IP "\(bu" 4
+
.IP "\(bu" 4
\&\-
.IP "\(bu" 4
*
.IP "\(bu" 4
/
.IP "\(bu" 4
%
.PP
There are also some mathy functions. See the \s-1FUNCTIONS\s0 section below.
.SH "LOGIC"
.IX Header "LOGIC"
Boolean logic is available:
.IP "\(bu" 4
&& (synonym: and)
.IP "\(bu" 4
|| (synonym: or)
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions are available to be used in expressions. See
perldoc perlfunc for details.
.IP "\(bu" 4
sprintf
.IP "\(bu" 4
substr (2 and 3 arg versions only)
.IP "\(bu" 4
lc
.IP "\(bu" 4
lcfirst
.IP "\(bu" 4
uc
.IP "\(bu" 4
ucfirst
.IP "\(bu" 4
length
.IP "\(bu" 4
defined
.IP "\(bu" 4
abs
.IP "\(bu" 4
atan2
.IP "\(bu" 4
cos
.IP "\(bu" 4
exp
.IP "\(bu" 4
hex
.IP "\(bu" 4
int
.IP "\(bu" 4
log
.IP "\(bu" 4
oct
.IP "\(bu" 4
rand
.IP "\(bu" 4
sin
.IP "\(bu" 4
sqrt
.IP "\(bu" 4
srand
.PP
All functions must be called using full parenthesis. For example,
this is a syntax error:
.PP
.Vb 1
\&
.Ve
.PP
But this is good:
.PP
.Vb 1
\&
.Ve
.SH "DEFINING NEW FUNCTIONS"
.IX Header "DEFINING NEW FUNCTIONS"
To define a new function, pass a \f(CW\*(C`functions\*(C'\fR option to new:
.PP
.Vb 3
\& $t = HTML::Template::Expr\->new(filename => \*(Aqfoo.tmpl\*(Aq,
\& functions =>
\& { func_name => \e&func_handler });
.Ve
.PP
Or, you can use \f(CW\*(C`register_function\*(C'\fR class method to register
the function globally:
.PP
.Vb 1
\& HTML::Template::Expr\->register_function(func_name => \e&func_handler);
.Ve
.PP
You provide a subroutine reference that will be called during output.
It will receive as arguments the parameters specified in the template.
For example, here's a function that checks if a directory exists:
.PP
.Vb 5
\& sub directory_exists {
\& my $dir_name = shift;
\& return 1 if \-d $dir_name;
\& return 0;
\& }
.Ve
.PP
If you call HTML::Template::Expr\->\fBnew()\fR with a \f(CW\*(C`functions\*(C'\fR arg:
.PP
.Vb 4
\& $t = HTML::Template::Expr\->new(filename => \*(Aqfoo.tmpl\*(Aq,
\& functions => {
\& directory_exists => \e&directory_exists
\& });
.Ve
.PP
Then you can use it in your template:
.PP
.Vb 1
\&
.Ve
.PP
This can be abused in ways that make my teeth hurt.
.SH "MOD_PERL TIP"
.IX Header "MOD_PERL TIP"
\&\f(CW\*(C`register_function\*(C'\fR class method can be called in mod_perl's
startup.pl to define widely used common functions to
HTML::Template::Expr. Add something like this to your startup.pl:
.PP
.Vb 1
\& use HTML::Template::Expr;
\&
\& HTML::Template::Expr\->register_function(foozicate => sub { ... });
\& HTML::Template::Expr\->register_function(barify => sub { ... });
\& HTML::Template::Expr\->register_function(baznate => sub { ... });
.Ve
.PP
You might also want to pre-compile some commonly used templates and
cache them. See HTML::Template's \s-1FAQ\s0 for instructions.
.SH "CAVEATS"
.IX Header "CAVEATS"
Currently the module forces the HTML::Template global_vars option to
be set. This will hopefully go away in a future version, so if you
need global_vars in your templates then you should set it explicitly.
.PP
The module won't work with HTML::Template's file_cache or shared_cache
modes, but normal memory caching should work. I hope to address this
is a future version.
.PP
The module is inefficient, both in parsing and evaluation. I'll be
working on this for future versions and patches are always welcome.
.SH "BUGS"
.IX Header "BUGS"
I am aware of no bugs \- if you find one, join the mailing list and
tell us about it. You can join the HTML::Template mailing-list by
visiting:
.PP
.Vb 1
\& http://lists.sourceforge.net/lists/listinfo/html\-template\-users
.Ve
.PP
Of course, you can still email me directly (sam@tregar.com) with bugs,
but I reserve the right to forward bug reports to the mailing list.
.PP
When submitting bug reports, be sure to include full details,
including the \s-1VERSION\s0 of the module, a test script and a test template
demonstrating the problem!
.SH "CREDITS"
.IX Header "CREDITS"
The following people have generously submitted bug reports, patches
and ideas:
.PP
.Vb 3
\& Peter Leonard
\& Tatsuhiko Miyagawa
\& Don Brodale
.Ve
.PP
Thanks!
.SH "AUTHOR"
.IX Header "AUTHOR"
Sam Tregar
.SH "LICENSE"
.IX Header "LICENSE"
HTML::Template::Expr : HTML::Template extension adding expression support
.PP
Copyright (C) 2001 Sam Tregar (sam@tregar.com)
.PP
This module is free software; you can redistribute it and/or modify it
under the terms of either:
.PP
a) the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version,
or
.PP
b) the \*(L"Artistic License\*(R" which comes with this module.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either
the \s-1GNU\s0 General Public License or the Artistic License for more details.
.PP
You should have received a copy of the Artistic License with this
module, in the file \s-1ARTISTIC.\s0 If not, I'll be glad to provide one.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA 02111\-1307
USA\s0