Artemus4(3)

NAME
Artemus4 - Template Toolkit

SYNOPSIS
 use Artemus4;

 # 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 = (
        "rnd" => sub { int(rand(100)) },    # normal function
        "sqrt" => sub { sqrt($_[0]) }       # can accept parameters
        );

 # create a new Artemus4 instance
 $ah = new Artemus4( "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}}');

DESCRIPTION
Artemus4 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 Artemus4 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://triptico.com/software/artemus.html

THE ARTEMUS MARKUP

  Simple templates
The simplest Artemus4 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.

Artemus4 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.

  Templates with parameters
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://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.

  Perl functions as templates
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 Artemus4 object is created which values are references to Perl functions. For example, you can create a function returning a random value by using:

 $funcs{'rnd'} = 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{'rnd'} = sub { int(rand($_[0])) };

then calling the template as

 {-rnd|500}

will return each time it's evaluated a random value between 0 and 499.

  Aborting further execution from a function
If the abort-flag argument is set to a scalar reference when creating the Artemus4 object, template processing can be aborted by setting this scalar to non-zero from inside a template function.

  Caching templates
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 Artemus4 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.

  Documenting templates
Artemus4 templates can contain documentation in Perl's POD format. This POD documentation is stripped each time the template is evaluated unless you create the Artemus4 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.

  Unresolved templates
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 Artemus4 object was created.

  Predefined templates

if

 {-if|condition|text}
 {-if|condition|text_if_true|text_unless_true}

If condition is true, this template returns text, or nothing otherwise; in the 3 argument version, returns text_if_true or text_unless_true. A condition is true if is not zero or the empty string (the same as in Perl).

ifelse

This is an alias for the if template provided for backwards-compatibility. Don't use it.

ifeq

 {-ifeq|term1|term2|text}
 {-ifeq|term1|term2|text_if_true|text_unless_true}

If term1 is equal to term2, this template returns text, or nothing otherwise. in the 4 argument version, returns text_if_true or text_unless_true.

ifneq

 {-ifneq|term1|term2|text}

If term1 is not equal to term2, this template returns text, or nothing otherwise.

ifeqelse

This is an alias for the ifeq template provided for backwards-compatibility. Don't use it.

add, sub

 {-add|num1|num2}
 {-sub|num1|num2}

This functions add or substract the values and returns the result.

gt, lt, eq

 {-gt|value1|value2}
 {-lt|value1|value2}
 {-eq|value1|value2}

This functions compare if value1 is greater-than, lesser-than or equal to value2. Meant primarily to use with the if template.

random

 {-random|value1|value2|...}

This function returns randomly one of the values sent as arguments. There can any number of arguments.

and

 {-and|value_or_condition_1|value_or_condition_2}

If both values are true or defined, returns value_or_condition_2; otherwise, returns the empty string.

or

 {-or|value_or_condition_1|value_or_condition_2}

If value_or_condition_1 is true or defined, returns it; otherwise, if value_or_condition_2 is true or defined, returns it; otherwise, returns the empty string.

not

 {-not|condition}

Returns the negation of condition.

set

 {-set|template_name|value}

Assigns a value to a template. Same as setting a value from the 'vars' argument to new, but from Artemus4 code.

If you must change a variable from inside an if directive, don't forget to escape the set directive, as in

 {-ifeq|{-user}|admin|\{-set\|powers\|EVERYTHING\}}

IF you don't escape it, the powers variable will be inevitably set to EVERYTHING.

foreach

 {-foreach|list:of:colon:separated:values|output_text|separator}

Iterates the list of colon separated values and returns output_text for each one of the values, separating each of them with separator (if one is defined). Each element itself can be a list of comma separated values that will be split and assigned to the $0, $1... etc parameters set to output_text. For example, to create a select HTML tag:

 <select name = 'work_days'>
 {-foreach|Monday,1:Tuesday,2:Wednesday,3:Thursday,4:Friday,5|
 <option value = '\$1'>\$0</option>
 }
 </select>

Remember to escape the dollar signs to avoid being expanded too early, and if the output_text include calls to other Artemus4 templates, to escape them as well.

case

 {-case|string|value_1|return_1|value_2|return_2|...}
 {-case|string|value_1|return_1|value_2|return_2|...|default_value}

Compares string against the list of value_1, value_2... and returns the appropriate return_1, return_2... value. If default_value is set (that is, case has an odd number of arguments) it's returned if string does not match any value.

env

 {-env|environment_variable}
 {-env}

If environment_variable has a value set in the environment, it's returned, or the empty string otherwise. If no environment variable is set, returns a colon-separated list of environment variable names.

size

 {-size|colon_separated_list}

Returns the number of elements in colon_separated_list.

seq

 {-seq|from_number|to_number}

Generates a colon-separated list of the numbers from from_number to to_number. Useful in a foreach loop.

sort

 {-sort|list}
 {-sort|list|field}

Sorts the colon-separated list. The optional field is the field to sort on (assuming the elements of the list are comma-separated lists themselves).

reverse

 {-reverse|list}

Reverses a colon-separated list.

\CACHE

 {-\CACHE|time}

Marks a template as cacheable and sets its cache time. See above.

\VERSION

 {-\VERSION}

Returns current Artemus4 version.

\BEGIN

\END

If you set these templates, they will be appended (\BEGIN) and prepended (\END) to the text being processed.

  Escaping
Escaping has been briefly mentioned above; this is a way to avoid prematurely expanding and executing Artemus4 templates, and a direct derivative of the simple text substitution approach of the Artemus4 engine.

To escape an Artemus4 template call you must escape ALL characters that has special meaning to the uber-simple Artemus4 parser (that is, the opening and closing braces, the pipe argument separator and the optional dollar prefixes for arguments). If you nest some directives (for example, two foreach calls), you must double-escape everything. Yes, this can get really cumbersome.

FUNCTIONS AND METHODS

  new
 $ah = new Artemus4(
        [ "vars" => \%variables, ]
        [ "funcs" => \%functions, ]
        [ "inv-vars" => \%inverse_variables, ]
        [ "include-path" => \@dir_with_templates_in_files, ]
        [ "loader_func" => \&template_loader_function, ]
        [ "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 Artemus4 object. The following arguments (passed to it as a hash) can be used:

vars

This argument must be a reference to a hash containing template - content pairs.

funcs

This argument must be a reference to a hash containing template name - code reference pairs. Each time one of these templates is evaluated, the function will be called with the template parameters passed as the function's arguments.

inv-vars

This argument must be a reference to a hash containing text - content pairs. Any occurrence of text will be replaced by content. They are called 'inverse variables' because they use to store variables that expand to Artemus4 markup, but can contain anything. This is really a plain text substitution, so use it with care (NOTE: this option is disabled by now until it works correctly).

include-path

This arrayref should contain directories where templates are to be found.

loader_func

If this reference to code exists, it's called with the template name as argument as a method to load templates from external sources. The function should return the template content or "undef" if the template is not found. It's called after testing for variables or functions and before trying to load from the "include-path".

cache-path

If this string is set, it must contain the path to a readable and writable directory where the cacheable templates are cached. See "Caching templates" for further information.

abort-flag

This argument must be a reference to a scalar. When the template processing is started, this scalar is set to 0. Template functions can set it to any other non-zero value to stop template processing.

unresolved

If this argument points to an array reference, it will be filled with the name of any unresolved templates. Each time a template processing is started, the array is emptied.

use-cr-lf

If this flag is set, all lines are separated using CR/LF instead of just LF (useful to generate MSDOS/Windows compatible text files).

contains-pod

If this flag is set, the (possible) POD documentation inside the templates are not stripped-out. Understand this flag as saying 'this template has pod as part of its content, so do not strip it'. See "Documenting templates".

paragraph-separator

If this argument is set to some string, all empty lines will be substituted by it (can be another Artemus4 template).

strip-html-comments

If this flag is set, HTML comments are stripped before any processing.

AUTOLOAD

If this argument points to a sub reference, the subrutine will be executed when a template is unresolved and its return value used as the final substitution value. Similar to the AUTOLOAD function in Perl standard modules. The unresolved template name will be sent as the first argument.

  armor
 $str = $ah->armor($str);

Translate Artemus4 markup to HTML entities, to avoid being interpreted by the parser.

  unarmor
 $str = $ah->unarmor($str);

Translate back the Artemus4 markup from HTML entities. This is the reverse operation of armor.

  strip
 $str = $ah->strip($str);

Strips all Artemus4 markup from the string.

  params
 $str = $ah->params($str, @params);

Interpolates all $0, $1, $2... occurrences in the string into the equivalent element from @params.

  process
 $str = $ah->process($str);

Processes the string, translating all Artemus4 markup. This is the main template processing method. The abort-flag flag and unresolved list are reset on each call to this method.

AUTHOR
Angel Ortega angel@triptico.com

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

Around line 588:
    You forgot a '=back' before '=head3'

Around line 770:
    =back without =over

Around line 813:
    You forgot a '=back' before '=head3'

Around line 897:
    =back without =over