Markup Format

{$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

• 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]}}

• One cannot have nested variables.
• 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.
• 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

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.

new

Make a new template object.

fill_in

    $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

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

do_replace

    $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

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

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

safe_backtick

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 a field made of multiple items.