Artemus - Template Toolkit
use Artemus;
# normal variables
%vars=(
"copyright" => 'Copyright 2002', # normal variable
"number" => 100, # another
"about" => '{-copyright} My Self', # can be nested
"link" => '<a href="$0">$1</a>' # can accept parameters
);
# functions as templates
%funcs=(
"random" => sub { int(rand(100)) }, # normal function
"sqrt" => sub { sqrt($_[0]) } # can accept parameters
);
# create a new Artemus instance $ah=new Artemus( "vars" => \%vars, "funcs" => \%funcs );
# do it
$out=$ah->process('Click on {-link|http://my.page|my page}, {-about}');
$out2=$ah->process('The square root of {-number} is {-sqrt|{-number}}');
Artemus is yet another template toolkit. Though it was designed to preprocess HTML, it can be used for any task that involves text substitution. These templates can be plain text, text with parameters and hooks to real Perl code. This document describes the Artemus markup as well as the API.
You can download the latest version of this package and get more information from its home page at
http://www.triptico.com/software/artemus.html
The simplest Artemus template is just a text substitution. If you set the 'about' template to '(C) 2000/2002 My Self', you can just write in your text
This software is {-about}.
and found it replaced by
This software is (C) 2000/2002 My Self.
Artemus templates can be nestable; so, if you set another template, called 'copyright' and containing '(C) 2000/2002', you can set 'about' to be '{-copyright} My Self', and obtain the same result. Though they can be nested nearly ad-infinitum, making circular references is unwise.
This wouldn't be any cool if templates where just text substitutions. But you can create templates that accept parameters just by including $0, $1, $2... marks inside its content. This marks will be replaced by the parameters used when inserting the call.
So, if you create the 'link' template containing
<a href="$0">$1</a>
you can insert the following call:
{-link|http://www.triptico.com|Angel Ortega's Home Page}
As you can see, you use the | character as a separator among the parameters and the template name itself.
Anything more complicated than this would require the definition of special functions provided by you. To do it, you just add templates to the 'funcs' hash reference when the Artemus object is created which values are references to Perl functions. For example, you can create a function returning a random value by using:
$funcs{'random'}=sub { int(rand(100)) };
And each time the {-random} template is found, it is evaluated and returns a random number between 0 and 99.
Functions also can accept parameters; so, if you define it as
$funcs{'random'}=sub { int(rand($_[0])) };
then calling the template as
{-random|500}
will return each time it's evaluated a random value between 0 and 499.
If the abort-flag argument is set to a scalar reference when creating the Artemus object, template processing can be aborted by setting this scalar to non-zero from inside a template function.
If a template is expensive or time consuming (probably because it calls several template functions that take very much time), it can be marked as cacheable. You must set the 'cache-path' argument for this to work, and include the following special Artemus code inside the template:
{-\CACHE|number}
where number is a number of days (or fraction of day) the cache will remain cached before being re-evaluated. Individual template functions cannot be cached; you must wrap them in a normal template if need it.
Artemus templates can contain documentation in Perl's POD format. This POD documentation is stripped each time the template is evaluated unless you create the Artemus object with the contains-pod argument set.
See http://www.perldoc.com/perl5.8.0/pod/perlpod.html and http://www.perldoc.com/perl5.8.0/pod/perlpodspec.html for information about writing POD documentation.
If a template is not found, it will be replaced by its name (that is, stripped out of the {- and } and left there). Also, the names of the unresolved templates are appended to an array referenced by the unresolved argument, if one was defined when the Artemus object was created.
{-if|condition|text}
If condition is true, this template returns text, or nothing otherwise. A condition is true if is not zero or the empty string (the same as in Perl).
{-ifelse|condition|text_if_true|text_unless_true}
If condition is true, this template returns text_if_true, or text_unless_true otherwise.
{-ifeq|term1|term2|text}
If term1 is equal to term2, this template returns text, or nothing otherwise.
{-ifneq|term1|term2|text}
If term1 is not equal to term2, this template returns text, or nothing otherwise.
{-ifeqelse|term1|term2|text_if_true|text_unless_true}
If term1 is equal to term2, this template returns text_if_true, or text_unless_true otherwise.
{-\CACHE|time}
Marks a template as cacheable and sets its cache time. See above.
{-\VERSION}
Returns current Artemus version.
$ah=new Artemus(
[ "vars" => \%variables, ]
[ "funcs" => \%functions, ]
[ "inv-vars" => \%inverse_variables, ]
[ "include-path" => $dir_with_templates_in_files, ]
[ "cache-path" => $dir_to_store_cached_templates, ]
[ "abort-flag" => \$abort_flag, ]
[ "unresolved" => \@unresolved_templates, ]
[ "use-cr-lf" => $boolean, ]
[ "contains-pod" => $boolean, ]
[ "paragraph-separator" => $separator, ]
[ "strip-html-comments" => $boolean, ]
[ "AUTOLOAD" => \&autoload_func ]
);
Creates a new Artemus object. The following arguments (passed to it as a hash) can be used:
$str=$ah->armor($str);
Translate Artemus markup to HTML entities, to avoid being interpreted by the parser.
$str=$ah->unarmor($str);
Translate back the Artemus markup from HTML entities. This is the reverse operation of armor.
$str=$ah->strip($str);
Strips all Artemus markup from the string.
$str=$ah->params($str,@params);
Interpolates all $0, $1, $2... occurrences in the string into the equivalent element from @params.
$str=$ah->process($str);
Processes the string, translating all Artemus markup. This is the main template processing method. The abort-flag flag and unresolved list are reset on each call to this method.
Angel Ortega angel@triptico.com