/ 
Text-SimpleTemplate-0.30
River stage zero No dependents
/ Text::SimpleTemplate

NAME

Text::SimpleTemplate - Yet another library for template processing.

SYNOPSIS

use Text::SimpleTemplate;

$tmpl = new Text::SimpleTemplate;
...

DESCRIPTION

This is yet another library for template-based data generation. It was first written to support dynamic generation of HTML pages, but should be able to handle any kinds of dynamic text generation. Major goal of this library is to separate code and data, so non-programmer can control final result (like HTML output) as desired without tweaking the source.

The idea is simple. Whenever the library finds text surrounded by '<%' and '%>' (or any pair of strings you specify), it will evaluate the part as a Perl expression, and will replace it by the evaluated result.

For people who know Text::Template (which offers similar functionality) already, you can consider this library almost same but with more strict syntax for exporting and evaluating expression. This library seems to run nearly twice as faster, also.

TEMPLATE SYNTAX AND USAGE

Suppose you have a following template named "sample.tmpl":

Hello, <% $to %>!
Welcome, you are user with ID #<% $id->{$to} %>.

With the follwing code...

use Safe;
use Text::SimpleTemplate;

$tmpl = new Text::SimpleTemplate;
$tmpl->setq(to => 'tai', id => { tai => 10 });
$tmpl->load("sample.tmpl");
$tmpl->fill(OHANDLE => \*STDOUT, PACKAGE => new Safe);

...you will get following result:

Hello, tai!
Welcome, you are user with ID #10.

As you might have noticed, _any_ scalar variable can be exported, even hash reference or code reference.

By the way, although the above example used Safe module, this is not a requirement. I just wanted to show that you can use it if you want to.

COMPATIBILITY

I first designed this module to require explicit exportation of data to template namespace. But I have also added support for Text::Template compatible style of exporting.

Just do it as you had done with Text::Template:

$FOO::text = 'hello, world';
@FOO::list = qw(foo bar baz);

$tmpl = new Text::SimpleTemplate;
...
$tmpl->fill(PACKAGE => 'FOO');

METHODS

Following methods are currently available.

$tmpl = new Text::SimpleTemplate;

Constructor. This will create (and return) object reference to Text::SimpleTemplate object.

$tmpl->setq($name => $data, $name => $data, ...);

Exports scalar data $data with name $name to template namespace (which is dynamically set on later evaluation stage). You can repeat the pair to export multiple variable pairs in one operation.

$tmpl->load($file, %opts);

Loads template file $file for later evaluation. $file can either be a filename or a reference to filehandle.

As a option, this method accepts LR_CHAR option, which can be used to specify delimiter to use on parsing. It takes a reference to array of delimiter pair, just like below:

$tmpl->load($file, LR_CHAR => [qw({ })]);

Returns object reference to itself.

$tmpl->pack($data, %opts);

Instead of file, loads in-memory data $data as a template. Except for this difference, works just like $tmpl->load.

$text = $tmpl->fill(%opts);

Returns evaluated result of template. Note template must be preloaded by either $tmpl->pack or $tmpl->load method beforehand.

This method accepts two options: PACKAGE and OHANDLE.

PACKAGE option will let you specify the namespace where template evaluation takes place. You can pass either the name of the namespace, or the package object itself. So either of

$tmpl->fill(PACKAGE => new Safe);
$tmpl->fill(PACKAGE => new Some::Module);
$tmpl->fill(PACKAGE => 'Some::Package');

works. If Safe module was passed, its reval method will be used instead of built-in eval.

OHANDLE option is for output selection. By default, this method returns the result of evaluation, but with OHANDLE option set, you can instead make it print to given handle. Either style of

$tmpl->fill(OHANDLE => \*STDOUT);
$tmpl->fill(OHANDLE => new FileHandle(...));

is supported.

SEE ALSO

Safe and Text::Template

BUGS / COMMENTS

Please send any bug reports/comments/suggestions to Taisuke Yamada <tai@imasy.or.jp>.

AUTHORS / CONTRIBUTORS

- Taisuke Yamada <tai@imasy.or.jp>
- Lin Tianshan <lts@www.qz.fj.cn>

COPYRIGHT

All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.