NAME
Positron::DataTemplate - templating plain data to plain data
VERSION
version v0.1.3
SYNOPSIS
my $engine = Positron::DataTemplate->new();
my $template = { contents => ['@list', '$title'] };
my $data = { list => [
{ title => 'first title', url => '/first-title.html' },
{ title => 'second title', url => '/second-title.html' },
] };
my $result = $engine->process($template, $data);
# { contents => [ 'first title', 'second title' ] }DESCRIPTION
Positron::DataTemplate is a templating engine. Unlike most templating engines, though, it does not work on text, but on raw data: the template is (typically) a hash or array reference, and the result is one, too.
This module rose from a script that regularly produced HTML snippets on disk, using regular, text-based templates. Each use case used the same data, but a different template. For one use case, however, the output was needed in JSON format, not HTML. One solution would have been to use the text-based templating system to produce a valid JSON document (quite risky). The other solution, which was taken at that time, was to transform the input data into the desired output structure in code, and use a JSON serializer on that, bypassing the template output.
The third solution would have been to provide a template that did not directly produce the serialised JSON text, but described the data structure transformation in an on-disc format. By working only with structured data, and never with text, the serialized output must always be valid JSON.
This (minus the serialization) is the domain of Positron::DataTemplate.
EXAMPLES
This code is still being worked on. This includes the documentation. In the meanwhile, please use the following examples (and some trial & error) to gain a first look. Alternatively, if you have access to the tests of this distribution, these also give some examples.
Text replacement
[ '$one', '{$two}', 'and {$three}' ] + { one => 1, two => 2, three => 3 }
-> [ '1', '2', 'and 3' ]Direct inclusion
[ '&this', '&that' ] + { this => [1, 2], that => { 3 => 4 } }
-> [ [1, 2], { 3 => 4} ]Loops
{ titles => ['@list', '{$id}: {$title}'] }
+ { list => [ { id => 1, title => 'one' }, { id => 2, title => 'two' } ] }
-> { titles => [ '1: one', '2: two' ] }Conditions
{ checked => ['?active', 'yes', 'no] } + { active => 1 }
-> { checked => 'yes' }Interpolation (works with a lot of constructs)
[1, '&list', 4] + { list => [2, 3] }
-> [1, [2, 3], 4]
[1, '&-list', 4] + { list => [2, 3] }
-> [1, 2, 3, 4]
[1, '<', '&list', 4] + { list => [2, 3] }
-> [1, 2, 3, 4]
{ '< 1' => { a => 'b' }, '< 2' => { c => 'd', e => 'f' }
-> { a => 'b', c => 'd', e => 'f' }
{ '< 1' => '&hash', two => 2 } + { hash => { one => 1 } }
-> { one => 1, two => 2 }Comments
'this is {#not} a comment' -> 'this is a comment'
[1, '#comment', 2, 3] -> [1, 2, 3]
[1, '/comment', 2, 3] -> [1, 3]
[1, '//comment', 2, 3] -> [1]
{ 1 => 2, '#3' => 4 } -> { 1 => 2, '' => 4 }
{ 1 => 2, '/3' => 4 } -> { 1 => 2 }File inclusion (requires JSON and File::Slurp)
[1, '. "/tmp/data.json"', 3] + '{ key: "value"}'
-> [1, { key => 'value' }, 3]File wrapping (also requires JSON and File::Slurp)
[1, ': "/tmp/wrap.json"', { animal => 'dog' }, 3]
+ '{ key: "value", contents: ":"}'
-> [1, { key => 'value', contents => { animal => 'dog' }, 3]Funtions on data
[1, '^len', "abcde", 2] + { len => \&CORE::length }
-> [1, 5, 2]Assignment
[1, '= title object.name', 'My {$title} and {$count}' ]
+ { object => { name => 'Name', count => 10 } }
-> [1, 'My Name and']Escaping other constructs
[ '~?cond', 'Talking about {{~}$templates}', '~.htaccess' ]
-> [ '?cond', 'Talking about {$templates}', '.htaccess' ]AUTHOR
Ben Deutsch, <ben at bendeutsch.de>
BUGS
None known so far, though keep in mind that this is alpha software.
Please report any bugs or feature requests to bug-positron at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Positron. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
This module is part of the Positron distribution.
You can find documentation for this distribution with the perldoc command.
perldoc PositronYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
Copyright 2013 Ben Deutsch. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/ for more information.