Expr(3pm)

💖 Expr(3pm) — HTML::Template::Expr 💖

okay bestie, so this is Expr(3pm), part of the User Contributed Perl Documentation family. it's the little extension that lets your HTML::Template templates do math and logic and generally have a whole personality. let's get into it 🦋

---

✨ NAME ✨

HTML::Template::Expr — it's an HTML::Template extension that adds expression support. that's the whole gig. 💅

---

🎀 SYNOPSIS 🎀

use HTML::Template::Expr;

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

look at that. clean. iconic. 🌸

---

💜 DESCRIPTION 💜

so basically this module is an extension to HTML::Template that lets you write expressions right inside the template syntax. and the tea is: it's purely an addition — every single normal HTML::Template option, syntax and behavior still works exactly like it always did. see HTML::Template for the deets.

what does expression support actually get you? comparisons, math operations, string operations, plus a whole mechanism where you can add your own functions at runtime. the basic syntax is giving:

<TMPL_IF EXPR="banana_count > 10">
  I've got a lot of bananas.
</TMPL_IF>

that's gonna output I've got a lot of bananas if you call:

$template->param(banana_count => 100);

in your script. and yes, <TMPL_VAR>s work with expressions too, bestie:

I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.

with that same param() call as above, this outputs I'd like to have 200 bananas. 🍌 obsessed.

---

😭 MOTIVATION 😭

some of you may be wondering if the author got replaced by a pod person. for the record: he still thinks this sort of thing should be avoided. HOWEVER — there are some situations where letting the template author have a lil programmatic leeway is genuinely invaluable.

if you don't like it, don't use this module. keep using plain ol' HTML::Template — he knows he will! but if you find yourself needing a little programming in your template, for whatever reason, then this module may just save you from HTML::Mason. slay. 💅

---

🌈 BASIC SYNTAX 🌈

Variables are unquoted alphanumeric strings with the same restrictions as variable names in HTML::Template. their values get set through param(), just like normal HTML::Template variables. for example, these two lines are equivalent:

<TMPL_VAR EXPR="foo">

<TMPL_VAR NAME="foo">

Numbers are unquoted strings of numbers and may have a single . to indicate a floating point number. like:

<TMPL_VAR EXPR="10 + 20.5">

String constants must be enclosed in quotes, single or double. like:

<TMPL_VAR EXPR="sprintf('%d', foo)">

you can string together operators to produce complex booleans:

<TMPL_IF EXPR="(foo || bar || baz || (bif && bing) || (bananas > 10))">
    I'm in a complex situation.
</TMPL_IF>

⚠️ the parser is pretty simple, so you may need to use parenthesis to get the precedence you want. no cap.

---

⭐ COMPARISON ⭐

here's the list of supported comparison operators, bestie:

• Numeric Comparisons
  • <
  • >
  • ==
  • !=
  • >=
  • <=
  • <=>
• String Comparisons
  • gt
  • lt
  • eq
  • ne
  • ge
  • le
  • cmp

---

🔥 MATHEMATICS 🔥

the basic operators are supported:

• +
• -
• *
• /
• %

there are also some mathy functions — see the FUNCTIONS section below. 💅

---

🧚 LOGIC 🧚

boolean logic is available:

• && (synonym: and)
• || (synonym: or)

---

👑 FUNCTIONS 👑

the following functions are available to be used in expressions. see perldoc perlfunc for details.

• sprintf
• substr (2 and 3 arg versions only)
• lc
• lcfirst
• uc
• ucfirst
• length
• defined
• abs
• atan2
• cos
• exp
• hex
• int
• log
• oct
• rand
• sin
• sqrt
• srand

🚨 ALL functions must be called using full parenthesis. so for example, this is a syntax error: <TMPL_IF expr="defined foo"> but this is good: <TMPL_IF expr="defined(foo)">

---

🫶 DEFINING NEW FUNCTIONS 🫶

to define a new function, pass a functions option to new:

$t = HTML::Template::Expr->new(filename => 'foo.tmpl',
                               functions =>
                                 { func_name => \&func_handler });

or, you can use the register_function class method to register the function globally:

HTML::Template::Expr->register_function(func_name => \&func_handler);

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:

sub directory_exists {
  my $dir_name = shift;
  return 1 if -d $dir_name;
  return 0;
}

if you call HTML::Template::Expr->new() with a functions arg:

$t = HTML::Template::Expr->new(filename => 'foo.tmpl',
                               functions => {
                                  directory_exists => \&directory_exists
                               });

then you can use it in your template:

<tmpl_if expr="directory_exists('/home/sam')">

💀 this can be abused in ways that make his teeth hurt. (his words, not mine.)

---

💅 MOD_PERL TIP 💅

the register_function 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:

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 { ... });

you might also want to pre-compile some commonly used templates and cache them. see HTML::Template's FAQ for instructions. ✨

---

🙈 CAVEATS 🙈

okay this is the part where we get real:

• 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.
• the module won't work with HTML::Template's file_cache or shared_cache modes, but normal memory caching should work. he hopes to address this in a future version.
• the module is inefficient, both in parsing and evaluation. he'll be working on this for future versions and patches are always welcome. 🫶

---

💀 BUGS 💀

he is aware of no bugs — if you find one, join the mailing list and tell them about it. you can join the HTML::Template mailing-list by visiting:

http://lists.sourceforge.net/lists/listinfo/html-template-users

of course, you can still email him directly (sam@tregar.com) with bugs, but he reserves the right to forward bug reports to the mailing list. 💅

🚨 when submitting bug reports, be sure to include full details, including the VERSION of the module, a test script and a test template demonstrating the problem!

---

🌸 CREDITS 🌸

the following people have generously submitted bug reports, patches and ideas:

Peter Leonard
Tatsuhiko Miyagawa
Don Brodale

thanks! 🫶

---

💖 AUTHOR 💖

Sam Tregar <sam@tregar.com>

---

📜 LICENSE 📜

HTML::Template::Expr : HTML::Template extension adding expression support

Copyright (C) 2001 Sam Tregar (sam@tregar.com)

this module is free software; you can redistribute it and/or modify it under the terms of either:

1. the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
2. the "Artistic License" which comes with this module.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see either the GNU General Public License or the Artistic License for more details.

you should have received a copy of the Artistic License with this module, in the file ARTISTIC. if not, he'll be glad to provide one.

you should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

---

and that's the whole page bestie!! 🌈✨ this was rendered by perl v5.32.0 on 2021-01-05, and yeah it's Expr(3pm) — go forth and put expressions in your templates, but like, responsibly. mwah 💋