Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Expr(3)		      User Contributed Perl Documentation	       Expr(3)

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

SYNOPSIS
	 use HTML::Template::Expr;

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

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.

       Expression support includes comparisons,	math operations, string
       operations and a	mechanism to allow you add your	own functions at
       runtime.	 The basic syntax is:

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

       This will output	"I've got a lot	of bananas" if you call:

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

       In your script.	<TMPL_VAR>s also work with expressions:

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

       This will output	"I'd like to have 200 bananas."	with the same param()
       call as above.

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 programatic	leeway can be invaluable.

       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.

BASIC SYNTAX
       Variables are unquoted alphanumeric strings with	the same restrictions
       as variable names in HTML::Template.  Their values are 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.  For example:

	  <TMPL_VAR EXPR="10 + 20.5">

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

	  <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 desired precedence.

COMPARISON
       Here's a	list of	supported comparison operators:

       o   Numeric Comparisons

	   o   <

	   o   >

	   o   ==

	   o   !=

	   o   >=

	   o   <=

	   o   <=>

       o   String Comparisons

	   o   gt

	   o   lt

	   o   eq

	   o   ne

	   o   ge

	   o   le

	   o   cmp

MATHEMATICS
       The basic operators are supported:

       o   +

       o   -

       o   *

       o   /

       o   %

       There are also some mathy functions.  See the FUNCTIONS section below.

LOGIC
       Boolean logic is	available:

       o   && (synonym:	and)

       o   || (synonym:	or)

FUNCTIONS
       The following functions are available to	be used	in expressions.	 See
       perldoc perlfunc	for details.

       o   sprintf

       o   substr (2 and 3 arg versions	only)

       o   lc

       o   lcfirst

       o   uc

       o   ucfirst

       o   length

       o   defined

       o   abs

       o   atan2

       o   cos

       o   exp

       o   hex

       o   int

       o   log

       o   oct

       o   rand

       o   sin

       o   sqrt

       o   srand

       All functions must be called using full parenthesis.  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 "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 recieve 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 my teeth hurt.

MOD_PERL TIP
       "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
       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 explicitely.

       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.

       The module is inefficient, both in parsing and evaluation.  I'll	be
       working on this for future versions and patches are always welcome.

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:

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

       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.

       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:

       a) the GNU General Public License as published by the Free Software
       Foundation; either version 1, or	(at your option) any later version, or

       b) 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, I'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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 496:
	   =back doesn't take any parameters, but you said =back 4

       Around line 516:
	   =back doesn't take any parameters, but you said =back 4

       Around line 518:
	   =back doesn't take any parameters, but you said =back 4

       Around line 536:
	   =back doesn't take any parameters, but you said =back 4

       Around line 550:
	   =back doesn't take any parameters, but you said =back 4

       Around line 599:
	   =back doesn't take any parameters, but you said =back 4

perl v5.32.1			  2006-04-18			       Expr(3)

NAME | SYNOPSIS | DESCRIPTION | MOTIVATION | BASIC SYNTAX | COMPARISON | MATHEMATICS | LOGIC | FUNCTIONS | DEFINING NEW FUNCTIONS | MOD_PERL TIP | CAVEATS | BUGS | CREDITS | AUTHOR | LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Template::Expr&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help