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 tostructured
by default) indicates which input field contains variables for expansion;one field in the hash (according to factory argument
output
, set torendered
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
- with_template_perlish
- render_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 iftemplate_perlish
is present in the arguments. It will also be ignored iftemplate
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 iftemplate_perlish
is present in the arguments. It will also be ignored iftemplate
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
andstop
, or whatever set intemplate_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
ortemplate_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 argumenttemplate_perlish
;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 a plain string or a hash reference, see above for the rules;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
open
ed, like a scalar reference).
This is the main parameter, so it can be provided un-named as the first stand-alone argument.
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
andvariables
will be ignored; otherwise, a Template::Perlish instance will be created with these three parameters; 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.