NAME

OurNet::Template - Template Toolkit extraction and generation

SYNOPSIS

    use OurNet::Template;
    use Data::Dumper;

    my $obj = OurNet::Template->new();
    my $template = << '.';
    <ul>[% FOREACH record %]
    <li><A HREF="[% url %]">[% title %]</A>: [% rate %] - [% comment %].
    [% _ %]
    [% END %]</ul>
    .

    my $document = << '.';
    <html><head><title>Great links</title></head><body>
    <ul><li><A HREF="http://slashdot.org">News for nerds.</A>: A+ - nice.
    this text is ignored.</li>
    <li><A HREF="http://microsoft.com">Where do you want...</A>: Z! - yeah.
    this text is ignored, too.</li></ul>
    .

    print Data::Dumper::Dumper(
	$obj->extract($template, $document)
    );

    # $obj->generate($document, $params); # not yet

DESCRIPTION

This module is a subclass of the standard Template toolkit, with added template extraction functionality, which means you can take a process()ed document and the original template together, and get the original data structure back.

The extract method takes three arguments: the template file itself (leave it undefined if already initialized), a scalar to match against it, and an optional external hash reference to store the extracted values.

Extraction is done by transforming the result from Template::Parser to a highly esoteric regular expression, which utilizes the (?{...}) construct to insert matched parameters into the hash reference. The special [% _ %] directive is understood as (?:[\x00-\xff]*?) in regex terms, i.e. "ignore everything between this identifier and the next".

This module is used primarily in the OurNet distributed storage platform by OurNet::Site and OurNet::WebBuilder components; any use outside it should be considered experimental.

CAVEATS

Currently, the extract function only understands [% GET %], [% SET %] and [% FOREACH %] directives, since [% WHILE %], [% CALL %] and [% SWITCH %] blocks are next to impossible to extract correctly.

The generate method is not working at all; it's supposed to take a data structure and the preferred rendering, and automagically generate a template to do the transformation. If you're into related research, please mail any ideas to me.

BUGS

Nested capturing will sometimes suffer from off-by-one errors with perl v5.7.1 or earlier; later versions supports the <$^N> variable and is exempt from such errors.

There is no support for different PRE_CHOMP and POST_CHOMP settings internally, so extraction could fail silently on wrong places.

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

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

See http://www.perl.com/perl/misc/Artistic.html