Squirrel::Template - simple templating system


  use Squirrel::Template;
  my $templater = Squirrel::Template->new(template_dir => $some_dir);
  my $result = $templater->show_page($base, $filename, \%acts, undef, $alt);
  my $result = $templater->replace_template($text, \%acts, undef, $display_name);
  my @errors = $templater->errors;
  my @args = $templater->get_parms($args, \%acts, $keep_unknown)


BSE's template engine.


  $templater = Squirrel::Template->new(%opts);

Create a new templating object.

Possible options are:


If a tag isn't found in the actions then it is replaced with an error message rather than being left in place.


Used to find wrapper and include templates. This can be either a scalar, or a reference to an array of locations to search for the wrapper.


If this is true then the template engine works in unicode internally. Template files are read into memory using the charecter set specified by charset.


Ignored unless utf8 is true. Specifies the character encoding used by template files. Defaults to "utf-8".


A BSE::Cache object to use for caching compiled templates. Note that templates are currently only cached by filename.

  $text = $templ->show_page($base, $template, \%acts, $iter)

Performs template replacement on the text from the file $template in directory $base.

  $text = $templ->replace_template($intext, \%acts, $iter, $name)

Performs template replacement on $intext using the tags in %acts. $iter is accepted only for backward compatibility and it no longer used. Errors are reported as if $intext had been read from a file called $name.


Return errors from the last show_page() or replace_template().

This can include:

Returns a list of error tokens, each of which is an array reference with:

  my @args = get_parms($args, $acts, $keep_unknown)

Does simple and stupid processing of $args parsing it for a list of arguments.

Possible arguments that are parsed are:

Returns a list of parsed arguments.

If tagname in $args isn't defined, dies with an ENOIMPL\n message.


This syntax provides mechanisms similar to those provided by Template Toolkit or Mason, while retaining the older syntax below.

See the Squirrel::Template::Expr manpage for information on expression syntax.

The loop variable

Each .for loop defines a loop variable. If you have nested loops, you can define an alias to the variable, eg:

  <:.for i in outer:>
    <:.set outerloop = loop:>
    <:.for j in inner:>
      <:= outerloop.count :>

The following values are set in loop


This is the older template syntax that is retained for compatibility.

In general, if the tag has no definition the original tag directive is left in place. If the tag has sub-components (like if or iterate) tag replacement is done on the sub-components.

Template directives start with <:, if a - is found immediately after the : any whitespace before the tag is also replaced.

Template directives end with :>, if a - if found immediately before the : any whitespace after the tag is also replaced.


  <: tag foo -:>  sample  <:-  tag bar :>

is treated the same as:

  <: tag foo :>sample<: tag bar :>

Directives available in templates:


Simple tag evaluation

Tag definitions in %acts can be in any of five forms:

A warning is produced if the tag returns an undef value.

Conditional tag evaluation

Given a ifSomeName, does Simple tag evaluation on the first tag of ifSomeName or someName found.

Unlike simple tag evaluation this does not warn if the result is undef.

Iterator tag evaluation

This uses two members of %acts:

Either can be any of:


So far there's just one:


If the _format action is defined in your $acts then if a function tag has |text at the end of it then the function is evaluated, and the resulting text and the text after the | is passed to the format function.


Squirrel::Row(3p), Squirel::Table(3p)


Started as a quick hack from seeing the hacky template replacement done by an employer.

It grew.

Largely rewritten in 2012 to avoid processing the same string a few hundred times.