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

FreeBSD Manual Pages

  
 
  

home | help
Text::NeatTemplate(3) User Contributed Perl DocumentationText::NeatTemplate(3)

NAME
       Text::NeatTemplate - a fast, middleweight template engine.

VERSION
       version 0.1101

SYNOPSIS
	   use Text::NeatTemplate;

	   my $tobj = Text::NeatTemplate->new();

	   $result = $tobj->fill_in(data_hash=>\%data,
				    show_names=>\%names,
				    template=>$text);

DESCRIPTION
       This module provides a simple, middleweight but fast template engine,
       for when	you need speed rather than complex features, yet need more
       features	than simple variable substitution.

   Markup Format
       The markup format is as follows:

       {$varname}
	   A variable; will display the	value of the variable, or nothing if
	   that	value is empty.

       {$varname:format}
	   A formatted variable; will apply the	formatting directive(s)	to the
	   value before	displaying it.

       {?varname stuff [$varname] more stuff}
	   A conditional.  If the value	of 'varname' is	not empty, this	will
	   display "stuff value-of-variable more stuff"; otherwise it displays
	   nothing.

	       {?var1 stuff [$var1] thing [$var2]}

	   This	would use both the values of var1 and var2 if var1 is not
	   empty.

       {?varname stuff [$varname] more stuff!!other stuff}
	   A conditional with "else".  If the value of 'varname' is not	empty,
	   this	will display "stuff value-of-variable more stuff"; otherwise
	   it displays "other stuff".

	   This	version	can likewise use multiple variables in its display
	   parts.

	       {?var1 stuff [$var1] thing [$var2]!![$var3]}

       {&funcname(arg1,...,argN)}
	   Call	a function with	the given args;	the return value of the
	   function will be what is put	in its place.

	       {&MyPackage::myfunc(stuff,[$var1])}

	   This	would call the function	myfunc in the package MyPackage, with
	   the arguments "stuff", and the value	of var1.

	   Note, of course, that if you	have a more complicated	function and
	   are processing much data, this will slow things down.

   Limitations
       To make the parsing simpler (and	therefore faster) there	are certain
       restrictions in what this module	can do:

       o   One cannot escape '{' '}' '[' or ']'	characters.  However, the
	   substitution	is clever enough so that you may be able to use	them
	   inside conditional constructs, provided the use does	not resemble a
	   variable.

	   For example,	to get a value surrounded by {}, the following will
	   not work:

	   {{$Var1}}

	   However, this will:

	   {?Var1 {[$Var1]}}

       o   One cannot have nested variables.

       o   Conditionals	are limited to testing whether or not the variable has
	   a value.  If	you want more elaborate	tests, or tests	on more	than
	   one value, you'll have to write a function to do it,	and use	the
	   {&function()} construct.

       o   Function arguments (as given	with the {&funcname(arg1,arg2...)}
	   format) cannot have commas in them, since commas are	used to
	   separate the	arguments.

   Justification For Existence
       When I was writing SQLite::Work,	I originally tried using
       Text::Template (my favourite template engine) and also tried
       Text::FillIn.  Both of them had some lovely, powerful features.
       Unfortunately, they were	also relatively	slow.  In testing them with a
       700-row table, using Text::Template took	about 15 seconds to generate
       the report, and using Text::FillIn took 45 seconds!  Rolling my own
       very simple template engine cut the time	down to	about 7	seconds.

       The reasons for this aren't that	surprising.  Because Text::Template is
       basically an embedded Perl engine, it has to run	the interpreter	on
       each substitution.  And Text::FillIn has	a lot to do, what with being
       very generic and	very recursive.

       The trade-off for the speed-gain	of Text::NeatTemplate is that it is
       quite simple.  There is no nesting or recursion,	there are no loops.
       But I do	think I've managed to grab some	of the nicer features of other
       template	engines, such as limited conditionals, and formatting, and,
       the most	powerful of all, calling external functions.

       This is a middleweight engine rather than a lightweight one, because I
       needed more than	just simple variable substitution, such	as one has
       with Template::Trivial.	I consider the trade-off worth it, and others
       might also, so I	made this a separate module.

FORMATTING
       As well as simple substitution, this module can apply formatting	to
       values before they are displayed.

       For example:

       {$Money:dollars}

       will give the value of the Money	variable formatted as a	dollar value.

       Formatting directives are:

       alpha
	   Convert to a	string containing only alphanumeric characters (useful
	   for anchors or filenames)

       alphadash
	   Convert to a	string containing alphanumeric characters, dashes and
	   underscores;	spaces are converted to	underscores.  (useful for
	   anchors or filenames)

       comma_front
	   Put anything	after the last comma at	the front (as with an author
	   name) For example, "Smith,Sarah Jane" becomes "Sarah	Jane Smith".

       dollars
	   Return as a dollar value (float of precision	2)

       email
	   Convert to a	HTML mailto link.

       float
	   Convert to float.

       hmail
	   Convert to a	"humanized" version of the email, with the @ and '.'
	   replaced with "at" and "dot".  This is useful to prevent spambots
	   harvesting email addresses.

       html
	   Convert to simple HTML (simple formatting)

       int Convert to integer

       itemnum
	   Assume that the value is multiple values separated by the "pipe"
	   symbol (|) and select the item with an index	of num (starting at
	   zero)

       items_directive
	   Assume that the value is multiple values separated by the "pipe"
	   symbol (|) and split	the values into	an array, apply	the directive
	   directive to	them, and join them together with a space.

       itemsjslash_directive
	   Like	items_directive, but the results are joined together with a
	   slash between them.

       itemslashnum
	   Assume that the value is multiple values separated by the "slash"
	   symbol (/) and select the item with an index	of num (starting at
	   zero) Good for selecting out	components of pathnames.

       lower
	   Convert to lower case.

       month
	   Convert the number value to an English month	name.

       namedalpha
	   Similar to 'alpha', but prepends the	'name' of the value.  Assumes
	   that	the name is only alphanumeric.

       nth Convert the number value to a N-th value.  Numbers ending with 1
	   have	'st' appended, 2 have 'nd' appended, 3 have 'rd' appended, and
	   everything else has 'th' appended.

       percent
	   Show	as if the value	is a percentage.

       pipetocomma
	   Assume that the value is multiple values separated by the "pipe"
	   symbol (|) and replace those	with a comma and space.

       pipetoslash
	   Assume that the value is multiple values separated by the "pipe"
	   symbol (|) and replace those	with a forward slash (/).

       proper
	   Convert to a	Proper Noun.

       string
	   Return the value with no change.

       title
	   Put any trailing ",The" ",A"	or ",An" at the	front (as this is a
	   title)

       truncatenum
	   Truncate to num length.

       upper
	   Convert to upper case.

       url Convert to a	HTML href link.

       wikilink
	   Format the value as the most	common kind of wikilink, that is
	   [[value]]

       wordsnum
	   Give	the first num words of the value.

CLASS METHODS
   new
       my $tobj	= Text::NeatTemplate->new();

       Make a new template object.

METHODS
   fill_in
       Fill in the given values.

	   $result = $tobj->fill_in(data_hash=>\%data,
				    show_names=>\%names,
				    template=>$text);

       The 'data_hash' is a hash containing names and values.

       The 'show_names'	is a hash saying which of these	"variable names" ought
       to be displayed,	and which suppressed.  This can	be useful if you want
       to use a	more generic template, and then	dynamically suppress certain
       values at runtime.

       The 'template' is the text of the template.

   get_varnames
       Find variable names inside the given template.

	   @varnames = $tobj->get_varnames(template=>$text);

   do_replace
       Replace the given value.

	   $val	= $tobj->do_replace(targ=>$targ,
				    data_hash=>$data_hashref,
				    show_names=>\%show_names);

       Where 'targ' is the target value, which is either a variable target, or
       a conditional target.

       The 'data_hash' is a hash containing names and values.

       The 'show_names'	is a hash saying which of these	"variable names" ought
       to be displayed,	and which suppressed.

       This can	do templating by using the exec	ability	of substitution, for
       example:

	   $out	=~ s/{([^}]+)}/$tobj->do_replace(data_hash=>$data_hash,targ=>$1)/eg;

   get_value
       $val = $tobj->get_value(val_id=>$val_id,
		      data_hash=>$data_hashref,
		      show_names=>\%show_names);

       Get and format the given	value.

   convert_value
	   my $val = $tobj->convert_value(value=>$val,
					  format=>$format,
					  name=>$name);

       Convert a value according to the	given formatting directive.

       See "FORMATTING"	for details of all the formatting directives.

   simple_html
       $val = $tobj->simple_html($val);

       Do a simple HTML	conversion of the value.  bold,	italic,	<br>

Callable Functions
   safe_backtick
       {&safe_backtick(myprog,arg1,arg2...argN)}

       Return the results of a program,	without	risking	evil shell calls.
       This requires that the program and the arguments	to that	program	be
       given separately.

   format_items
       {&format_items(fieldname,value,delim,outdelim,format,prefix,suffix)}

       Format a	field made of multiple items.

REQUIRES
	   Test::More

INSTALLATION
       To install this module, run the following commands:

	   perl	Build.PL
	   ./Build
	   ./Build test
	   ./Build install

       Or, if you're on	a platform (like DOS or	Windows) that doesn't like the
       "./" notation, you can do this:

	  perl Build.PL
	  perl Build
	  perl Build test
	  perl Build install

       In order	to install somewhere other than	the default, such as in	a
       directory under your home directory, like "/home/fred/perl" go

	  perl Build.PL	--install_base /home/fred/perl

       as the first step instead.

       This will install the files underneath /home/fred/perl.

       You will	then need to make sure that you	alter the PERL5LIB variable to
       find the	module.

       Therefore you will need to change the PERL5LIB variable to add
       /home/fred/perl/lib

	       PERL5LIB=/home/fred/perl/lib:${PERL5LIB}

SEE ALSO
       Text::Template Text::FillIn Text::QuickTemplate Template::Trivial
       Template::Toolkit HTML::Template

BUGS
       Please report any bugs or feature requests to the author.

AUTHOR
	   Kathryn Andersen (RUBYKAT)
	   perlkat AT katspace dot com
	   http://www.katspace.org/tools

COPYRIGHT AND LICENCE
       Copyright (c) 2006 by Kathryn Andersen

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2021-08-27		 Text::NeatTemplate(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | FORMATTING | CLASS METHODS | METHODS | Callable Functions | REQUIRES | INSTALLATION | SEE ALSO | BUGS | AUTHOR | COPYRIGHT AND LICENCE

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

home | help