The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Positron-v0.1.3
River stage zero No dependents
1 ++
/ Positron::DataTemplate

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 Positron

You can also look for information at:

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.