1Expr(3)               User Contributed Perl Documentation              Expr(3)
2
3
4

NAME

6       HTML::Template::Expr - HTML::Template extension adding expression
7       support
8

SYNOPSIS

10         use HTML::Template::Expr;
11
12         my $template = HTML::Template::Expr->new(filename => 'foo.tmpl');
13         $template->param(banana_count => 10);
14         print $template->output();
15

DESCRIPTION

17       This module provides an extension to HTML::Template which allows
18       expressions in the template syntax.  This is purely an addition - all
19       the normal HTML::Template options, syntax and behaviors will still
20       work.  See HTML::Template for details.
21
22       Expression support includes comparisons, math operations, string
23       operations and a mechanism to allow you add your own functions at
24       runtime.  The basic syntax is:
25
26          <TMPL_IF EXPR="banana_count > 10">
27            I've got a lot of bananas.
28          </TMPL_IF>
29
30       This will output "I've got a lot of bananas" if you call:
31
32          $template->param(banana_count => 100);
33
34       In your script.  <TMPL_VAR>s also work with expressions:
35
36          I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.
37
38       This will output "I'd like to have 200 bananas." with the same param()
39       call as above.
40

MOTIVATION

42       Some of you may wonder if I've been replaced by a pod person.  Just for
43       the record, I still think this sort of thing should be avoided.
44       However, I realize that there are some situations where allowing the
45       template author some programatic leeway can be invaluable.
46
47       If you don't like it, don't use this module.  Keep using plain ol'
48       HTML::Template - I know I will!  However, if you find yourself needing
49       a little programming in your template, for whatever reason, then this
50       module may just save you from HTML::Mason.
51

BASIC SYNTAX

53       Variables are unquoted alphanumeric strings with the same restrictions
54       as variable names in HTML::Template.  Their values are set through
55       param(), just like normal HTML::Template variables.  For example, these
56       two lines are equivalent:
57
58          <TMPL_VAR EXPR="foo">
59
60          <TMPL_VAR NAME="foo">
61
62       Numbers are unquoted strings of numbers and may have a single "." to
63       indicate a floating point number.  For example:
64
65          <TMPL_VAR EXPR="10 + 20.5">
66
67       String constants must be enclosed in quotes, single or double.  For
68       example:
69
70          <TMPL_VAR EXPR="sprintf('%d', foo)">
71
72       You can string together operators to produce complex booleans:
73
74         <TMPL_IF EXPR="(foo || bar || baz || (bif && bing) || (bananas > 10))">
75             I'm in a complex situation.
76         </TMPL_IF>
77
78       The parser is pretty simple, so you may need to use parenthesis to get
79       the desired precedence.
80

COMPARISON

82       Here's a list of supported comparison operators:
83
84       •   Numeric Comparisons
85
86           •   <
87
88           •   >
89
90           •   ==
91
92           •   !=
93
94           •   >=
95
96           •   <=
97
98           •   <=>
99
100       •   String Comparisons
101
102           •   gt
103
104           •   lt
105
106           •   eq
107
108           •   ne
109
110           •   ge
111
112           •   le
113
114           •   cmp
115

MATHEMATICS

117       The basic operators are supported:
118
119       •   +
120
121       •   -
122
123       •   *
124
125       •   /
126
127       •   %
128
129       There are also some mathy functions.  See the FUNCTIONS section below.
130

LOGIC

132       Boolean logic is available:
133
134       •   && (synonym: and)
135
136       •   || (synonym: or)
137

FUNCTIONS

139       The following functions are available to be used in expressions.  See
140       perldoc perlfunc for details.
141
142       •   sprintf
143
144       •   substr (2 and 3 arg versions only)
145
146       •   lc
147
148       •   lcfirst
149
150       •   uc
151
152       •   ucfirst
153
154       •   length
155
156       •   defined
157
158       •   abs
159
160       •   atan2
161
162       •   cos
163
164       •   exp
165
166       •   hex
167
168       •   int
169
170       •   log
171
172       •   oct
173
174       •   rand
175
176       •   sin
177
178       •   sqrt
179
180       •   srand
181
182       All functions must be called using full parenthesis.  For example, this
183       is a syntax error:
184
185          <TMPL_IF expr="defined foo">
186
187       But this is good:
188
189          <TMPL_IF expr="defined(foo)">
190

DEFINING NEW FUNCTIONS

192       To define a new function, pass a "functions" option to new:
193
194         $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
195                                        functions =>
196                                          { func_name => \&func_handler });
197
198       Or, you can use "register_function" class method to register the
199       function globally:
200
201         HTML::Template::Expr->register_function(func_name => \&func_handler);
202
203       You provide a subroutine reference that will be called during output.
204       It will recieve as arguments the parameters specified in the template.
205       For example, here's a function that checks if a directory exists:
206
207         sub directory_exists {
208           my $dir_name = shift;
209           return 1 if -d $dir_name;
210           return 0;
211         }
212
213       If you call HTML::Template::Expr->new() with a "functions" arg:
214
215         $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
216                                        functions => {
217                                           directory_exists => \&directory_exists
218                                        });
219
220       Then you can use it in your template:
221
222         <tmpl_if expr="directory_exists('/home/sam')">
223
224       This can be abused in ways that make my teeth hurt.
225

MOD_PERL TIP

227       "register_function" class method can be called in mod_perl's startup.pl
228       to define widely used common functions to HTML::Template::Expr. Add
229       something like this to your startup.pl:
230
231         use HTML::Template::Expr;
232
233         HTML::Template::Expr->register_function(foozicate => sub { ... });
234         HTML::Template::Expr->register_function(barify    => sub { ... });
235         HTML::Template::Expr->register_function(baznate   => sub { ... });
236
237       You might also want to pre-compile some commonly used templates and
238       cache them.  See HTML::Template's FAQ for instructions.
239

CAVEATS

241       Currently the module forces the HTML::Template global_vars option to be
242       set.  This will hopefully go away in a future version, so if you need
243       global_vars in your templates then you should set it explicitely.
244
245       The module won't work with HTML::Template's file_cache or shared_cache
246       modes, but normal memory caching should work.  I hope to address this
247       is a future version.
248
249       The module is inefficient, both in parsing and evaluation.  I'll be
250       working on this for future versions and patches are always welcome.
251

BUGS

253       I am aware of no bugs - if you find one, join the mailing list and tell
254       us about it.  You can join the HTML::Template mailing-list by visiting:
255
256         http://lists.sourceforge.net/lists/listinfo/html-template-users
257
258       Of course, you can still email me directly (sam@tregar.com) with bugs,
259       but I reserve the right to forward bug reports to the mailing list.
260
261       When submitting bug reports, be sure to include full details, including
262       the VERSION of the module, a test script and a test template
263       demonstrating the problem!
264

CREDITS

266       The following people have generously submitted bug reports, patches and
267       ideas:
268
269          Peter Leonard
270          Tatsuhiko Miyagawa
271          Don Brodale
272
273       Thanks!
274

AUTHOR

276       Sam Tregar <sam@tregar.com>
277

LICENSE

279       HTML::Template::Expr : HTML::Template extension adding expression
280       support
281
282       Copyright (C) 2001 Sam Tregar (sam@tregar.com)
283
284       This module is free software; you can redistribute it and/or modify it
285       under the terms of either:
286
287       a) the GNU General Public License as published by the Free Software
288       Foundation; either version 1, or (at your option) any later version, or
289
290       b) the "Artistic License" which comes with this module.
291
292       This program is distributed in the hope that it will be useful, but
293       WITHOUT ANY WARRANTY; without even the implied warranty of
294       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
295       GNU General Public License or the Artistic License for more details.
296
297       You should have received a copy of the Artistic License with this
298       module, in the file ARTISTIC.  If not, I'll be glad to provide one.
299
300       You should have received a copy of the GNU General Public License along
301       with this program; if not, write to the Free Software Foundation, Inc.,
302       59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
303

POD ERRORS

305       Hey! The above document had some coding errors, which are explained
306       below:
307
308       Around line 496:
309           =back doesn't take any parameters, but you said =back 4
310
311       Around line 516:
312           =back doesn't take any parameters, but you said =back 4
313
314       Around line 518:
315           =back doesn't take any parameters, but you said =back 4
316
317       Around line 536:
318           =back doesn't take any parameters, but you said =back 4
319
320       Around line 550:
321           =back doesn't take any parameters, but you said =back 4
322
323       Around line 599:
324           =back doesn't take any parameters, but you said =back 4
325
326
327
328perl v5.38.0                      2023-07-20                           Expr(3)
Impressum