triptico.com

2010-06-09

Art5 - Template Toolkit

SYNOPSIS

 use Art5;
 
 # creates a new object
 my $art5 = Art5->new(path => \@path_to_templates);
 
 # compiles and executes a string of Art5 code
 my $r = $art5->process($source_code);

DESCRIPTION

Artemus is a template toolkit. It filters text files, parsing, compiling and executing code surrounded by special marks (leaving the rest untouched) and concatenating everything as output. Its main purpose is to filter HTML files, but it can be used for any scripting need related to text filtering and substitution.

The main purpose of the Art5 API is to add your own functions to the Art5 machine to make them part of the programming language. For more information on the Art5 Templating Language, please see the included art5_overview document.

This can be done by adding code to the op component of the Art5 object. For example, this is a way to add a localtime function to Art5:

 $art5->{op}->{localtime} = sub { return localtime(); };

Art5 functions can also accept arguments. They arrive as code streams that must be executed before use. For example, this is a function that accept two numbers and returns the average:

 $art5->{op}->{avg} = sub {
          my $v1 = shift;
          my $v2 = shift;
 
          return ($art5->exec($v1) + $art5->exec($v2)) / 2;
 };

Art5 functions always have to return something. If you have nothing to return, use an empty string. If an array must be returned (for example, to be feed to foreach, return a reference to it (not the array itself).

The external hash can similarly accessed by tweaking the xh component. In this example, the running program process id will be accesible as %pid:

 $art5->{xh}->{pid} = $!;

FUNCTIONS AND METHODS

new

 $art5 = Art5->new(
    [ path        => \@directories, ]
    [ cache       => $directory, ]
    [ loader_func => \&function, ]
 );

Creates a new Art5 object. The object creation accepts the following arguments:

path

A reference to a list of directories where templates are to be found.

cache

A directory path where compiled templates are to be cached. These compiled templates are raw Data::Dumper output of the compiled stream, and are loaded back with simple eval(), so take extreme care.

loader_func

A pointer to a function to be called whenever a new template is queried by the underlying system. This function should return the content of a template or undef if not found. This mechanism is used to have an external storage for templates (as in a SQL Database, for example). Take note that templates retrived this way cannot be cached (this defect will eventually be solved).

This function is called before any search in the path.

process

 my $ret_val = $art->process($art5_code);

Compiles a string of Art5 code, executes it and returns the exit value.

compile

 my $opcode_stream = $art5->compile($art5_code);

Reads a string of Art5 code and returns a compiled stream.

exec

 my $ret_val = $art5->exec($opcode_stream);

Executes a compiled stream (returned by compile()) and returns the exit value.

AUTHOR

Angel Ortega angel@triptico.com

Documents artemus

Add a comment

Print version - Permanent link to this page