Ben Deutsch > Positron-v0.0.3 > Positron::DataTemplate

Download:
Positron-v0.0.3.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: v0.0.3   Source   Latest Release: Positron-v0.1.3

NAME ^

Positron::DataTemplate - templating plain data to plain data

VERSION ^

version v0.0.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]

Funtions on data

  [1, '^len', "abcde", 2] + { len => \&CORE::length }
  -> [1, 5, 2]

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.

syntax highlighting: