Data::Tubes::Plugin::Renderer
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;
input
structured
one field in the hash (according to factory argument output, set to rendered by default) is set to the output of the reading operation.
output
rendered
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.
render_
tube
pipeline
Alias for "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.
template
%args
Allowed arguments are:
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;
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;
[%
template_perlish
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 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;
variables
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).
open
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;
undef
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;
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.
Report bugs either through RT or GitHub (patches welcome).
Flavio Poletti <polettix@cpan.org>
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.
To install Data::Tubes, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Tubes
CPAN shell
perl -MCPAN -e shell install Data::Tubes
For more information on module installation, please visit the detailed CPAN module installation guide.