/ 
Dist-Zilla-Role-TextTemplater-0.002
River stage one • 2 direct dependents • 3 total dependents
/ Dist::Zilla::Role::TextTemplater

NAME

Dist::Zilla::Role::TextTemplater - Have text templating capabilities in your Dist::Zilla plugin

VERSION

Version 0.002, released on 2015-07-18 18:38 UTC.

WHAT?

Dist-Zilla-Role-TextTemplater is a Dist::Zilla role, a replacement for standard role TextTemplate. Both roles have the same great Text::Template engine under the hood, but this one provides better control over the engine and much better error reporting.

This is Dist::Zilla::Role::TextTemplater module documentation. Read this if you want to have text templating capabilities in your Dist::Zilla plugin.

If you are using a TextTemplater-based plugin, read the manual. General topics like getting source, building, installing, bug reporting and some others are covered in the readme.

SYNOPSIS

package Dist::Zilla::Plugin::YourPlugin;
use Moose;
use namespace::autoclean;
with 'Dist::Zilla::Role::Plugin';
with 'Dist::Zilla::Role::TextTemplater';

sub method {
    my $self = shift( @_ );
    …
    $result = $self->fill_in_string( $template );
    …
};

__PACKAGE__->meta->make_immutable;
1;

DESCRIPTION

The role provides consuming plugin with fill_in_string method and bunch of accompanying attributes and dist.ini options.

CLASS METHODS

BUILDARGS

The method splits delimiters option value into list of words to initialize delimiters attribute (which is of ArrayRef[Str] type).

OBJECT ATTRIBUTES

delimiters

Pair of open and closing delimiters the code fragments surrounded by.

Attribute introduces dist.ini option with the same name. Option value will be split (see BUILDARGS) to initialize the attribute.

ArrayRef[Str], read-only. Default value is '{{', '}}'.

See DELIMITERS option of "fill_in" in Text::Template.

Note: Our default delimiters are "alternative delimiters" for Text::Template. It means escaping delimiters with backslash does not work. See "Alternative Delimiters" in Text::Template.

package

Name of package to evaluate code fragments in.

Attribute introduces dist.ini option with the same name.

Str, read-only, optional.

See PACKAGE option of "fill_in" in Text::Template.

prepend

Perl code to prepend to the beginning of every code fragment.

Attribute introduces dist.ini multi-value option with the same name.

ArrayRef[Str], read-only, auto dereferenced. Default value is empty array. Another default value may be specified by defining _build_prepend method.

See PREPEND option of "fill_in" in Text::Template.

broken

Callback to execute if a code fragment dies. Default callback formats detailed error message and log it by calling log_error.

CodeRef, read-only, not an init argument. Default callback may be overridden by defining _build_broken method.

See BROKEN option of "fill_in" in Text::Template.

OBJECT METHODS

mvp_multivalue_args

The method tells Dist::Zilla that prepend is a multi-value option.

fill_in_string

$result = $self->fill_in_string( $template, \%variables, \%extra_args );
$result = $self->fill_in_string( $template );

The primary method of the role.

The interface is compatible with method of TextTemplate role, so this role can be used as a drop-in replacement for TextTemplate. However, methods are implemented slightly differently (this method calls Text::Template::fill_in_string function, that one creates Text::Template object first, then calls fill_in method on the object), it may cause subtle difference in behaviour.

Template variables $plugin and $dist are set by default, if not explicitly defined in \%variables.

The method calls Text::Template::fill_in_string, passing to it the $template, \%variables, attribute values package, prepend, broken, and finally %extra_args. %extra_args is passed in the end intentionally, so caller may override any of parameters specified by the method, for example:

$self->fill_in_string( $template, undef, { package => 'MY' } );
    #   Execute code fragments in package MY regardless of $self->package value.

It also allows to cancel defining $plugin and $dist variables, e. g.:

$self->fill_in_string( $template, undef, { hash => {} } );
    #   Do not define any variables for the template.

NOTES

Text::Template option spelling

Text::Template allows a programmer to use different spelling of options: all-caps, first-caps, all-lowercase, with and without leading dash, e. g.: HASH, Hash, hash, -HASH, -Hash, -hash. This is documented feature.

Text::Template recommends to pick a style and stick with it. (BTW, Text::Template documentation itself uses all-caps spelling.) This role picked all-lowercase style. This choice have subtle consequences. Let us consider an example:

$self->fill_in_string( $template, undef, { PACKAGE => 'MY' } );

Extra option PACKAGE may or may not not have effect, depending on value of package attribute (i. e. presence or absence package option in dist.ini file), because (this is not documented) spellings are not equal: different spellings have different priority. If PACKAGE and package are specified simultaneously, package wins, PACKAGE loses.

This feature gives you a choice. If you want to ignore option specified by the user in dist.ini and provide your value, use all-lowercase option name. If you want to provide default which can be overridden by the user, use all-caps options name.

WHY?

TextTemplate role from Dist::Zilla distribution v5.037 has the same great Text::Template engine under the hood, but lacks of control and has awful error reporting.

Error Reporting

Let us consider an example. Have a look at dist.ini:

name     = Assa
version  = 0.001
[GatherDir]
[PruneCruft]
[GenerateFile/COPYING]
    filename = COPYING
    content  = This is {{$dist->name}}.
    content  =
    content  = {{$dst->license->notice}}
    is_template = 1
[TemplateFiles]
    filename = lib/Assa.pm
    filename = lib/Assa/Manual.pod
[MetaResources::Template]
    license = {{$dist->license->url}}
    …
…

(Do you see a typo? Real dist.ini can be much longer.) Now let us build the distribution:

$ dzil build
[DZ] beginning to build Assa
Can't call method "license" on an undefined value at template line 3.

Oops. Ok, it is clear what was happened, but where?? The only weak clue is word "template". However, there are many templates in the project: lib/Assa.pm, lib/Assa/Manual.pod, generated on-the-fly COPYING, and even resources in META.yml — all this stuff is generated from templates. Where is the problem? Have a happy bug hunting, dude.

If these plugins (namely, GenerateFile, TemplateFiles and MetaResources::Template) were written with TextTemplater role, result would be:

$ dzil build
[DZ] beginning to build Assa
[COPYING] Can't call method "license" on an undefined value at template line 3.
[COPYING] Problem code fragment begins at template line 3.
[COPYING] Template text:
[COPYING]     1: This is {{$dist->name}}.
[COPYING]     2:
[COPYING] >>> 3: {{$dst->license->notice}}
Aborting...

See the difference.

Engine Control

TextTemplater allows the end-user to specify package and prepender engine options from dist.ini file, while TextTemplate allows to specify prepender only programmatically, and does not allow to specify package.

SEE ALSO

Dist::Zilla Dist::Zilla::Role Dist::Zilla::Plugin Dist::Zilla::Role::TextTemplate Text::Template

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Role-TextTemplater.

perl-Dist-Zilla-Role-TextTemplater is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Role-TextTemplater 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Role-TextTemplater. If not, see <http://www.gnu.org/licenses/>.