NAME

Data::Tubes::Plugin::Renderer

DESCRIPTION

This module contains factory functions to generate tubes that ease rendering records as text (or data).

Each of the generated tubes has the following contract:

• the input record MUST be a hash reference;

• one field in the input record (according to factory argument input, set to structured by default) indicates which input field contains variables for expansion;

• one field in the hash (according to factory argument output, set to rendered by default) is set to the output of the reading operation.

The factory functions below have two names, one starting with render_ and the other without this prefix. They are perfectly equivalent to each other, whereas the short version can be handier e.g. when using tube or pipeline from Data::Tubes.

FUNCTIONS

render_with_template_perlish

Alias for "with_template_perlish".

with_template_perlish

   my $tube = with_template_perlish($template, %args); # OR
   my $tube = with_template_perlish(%args); # OR
   my $tube = with_template_perlish(\%args);

render input variables using a Template::Perlish template. The template is the main parameter, and can be passed as unnamed first argument or with key template inside the %args hash.

Allowed arguments are:

input

the name of the input field in the record, where record-specific variables can be found;

name

the name of the tube, useful when debugging;

output

the name of the output field in the output record;

start

parameter for Template::Perlish, defaults to [%. It will be ignored if template_perlish is present in the arguments. It will also be ignored if template is already compiled or gets compiled not using the Template::Perlish instance generated with this setting;

stop

parameter for Template::Perlish, defaults to %]. It will be ignored if template_perlish is present in the arguments. It will also be ignored if template is already compiled or gets compiled not using the Template::Perlish instance generated with this setting;

template

template that will be expanded. It can be either of the following:

• a plain string. In this case, it MUST be compliant with the rules explained in Template::Perlish and the settings for start and stop, or whatever set in template_perlish;

• a hash reference. In this case, the template is assumed to be a pre-compiled template that is immediately useable with "evaluate" in Template::Perlish. Depending on whether it has been compiled with checks or not (see "compile" in Template::Perlish), it might actually ignore variables or template_perlish's variables or not. If you go this route, it is usually a good idea to pass the Template::Perlish instance that compiled this template via argument template_perlish;

• an array reference. This will be expanded into an argument list for "read_file" in Data::Tubes::Plugin::Util, that allows reading the template from a file (or whatever can be opened, like a scalar reference).

• a code reference. This is provided for maximum flexibility. It will be invoked to get the template, getting the full arguments hash as input (the arguments has will always have template_perlish populated, either with the provided value or with a newly created one). It can return either of the above, and the return value will be treated accordingly (it cannot return another code reference though, please do all the indirections in the sub yourself!).

This is the main parameter, so it can be provided un-named as the first stand-alone argument.

template_input

optional identifier of a field in the input record that has the template to be expanded. When this argument is defined, and the corresponding field in the input record is defined too, this field in the input record will be used as template instead of argument template. Defaults to undef, i.e. use whatever set as template;

template_perlish

an instance of Template::Perlish that has to be used for all compilations and evaluation of templates. If this is present, options start, stop and variables will be ignored; otherwise, a Template::Perlish instance will be created with these three parameters;

template_perlish_input

optional identifier of a field in the input record that has the Template::Perlish instance to use for expansions. If this argument is missing/undefined, or if the corresponding field in the input record is missing/undefined, the default Template::Perlish instance will be used (i.e. either the one passed with template_perlish, or the auto-generated one). Defauts to undef, i.e. use whatever set as template_perlish or the auto-generated instance;

variables

hash reference with variables that will always be available when expanding the template. Defaults to the empty hash. Will be ignored if template_perlish is present in the arguments.

BUGS AND LIMITATIONS

Report bugs either through RT or GitHub (patches welcome).

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.