/ 
Dist-Zilla-Role-TextTemplater-0.001
/ Dist::Zilla::Role::TextTemplater

NAME

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

VERSION

Version 0.001, released on 2015-07-14 21:52 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

OBJECT ATTRIBUTES

delimiters

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

ArrayRef[Str], read-only, not an init argument (yet). 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.

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.

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

fill_in_string

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

The primary method of the role.

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/>.