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

NAME

Dist::Zilla::Role::TextTemplater::Manual - TextTemplater role user manual

VERSION

Version 0.004, released on 2015-08-06 16:14 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 TextTemplater role user manual. Read this if you are using a TextTemplater-based plugin.

If you want to have text templating capabilities in your Dist::Zilla plugin, read the module documentation. General topics like getting source, building, installing, bug reporting and some others are covered in the readme.

SYNOPSIS

In your dist.ini:

[ATextTemplaterBasedPlugin]
    package    = MY
    prepend    = use strict;
    prepend    = use warnings;
    delimiters = (* *)
    …

DESCRIPTION

TextTemplater is a Dist::Zilla role. It cannot be directly used by the end user. However, the role provides dist.ini options which have the same meaning for all TextTemplater-based plugins. Describing options this manual makes documenting TextTemplater-based plugins simpler.

The role provides three options: delimiters, package and prepend.

OPTIONS

delimiters

Delimiters

The value should consist of two space-separated delimiters: opening delimiter and closing delimiter. Opening delimiter denotes the beginning of code fragment, closing delimiter signals the end of code fragment.

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.

package = MY

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

prepend

Perl code to prepend to the beginning of every code fragment. Option may be specified several times. All the values will be joined with newlines.

prepend = use strict;
prepend = use warnings;

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

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 COPYING line 3.
[COPYING] Problem code fragment begins at COPYING line 3.
[COPYING] COPYING:
[COPYING]     1: This is {{$dist->name}}.
[COPYING]     2:
[COPYING]     3: {{$dst->license->notice}}
[COPYING]        ^^^ Code fragment begins in line above ^^^
[COPYING]        ^^^ Code fragment died in line above ^^^
Aborting...

See the difference.

Engine Control

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

GLOSSARY

Template

Plain text with embedded Perl code fragments. "Filling in" a template means that each code fragment should be extracted, executed, and replaced with the result of execution.

Delimiters

Character sequences which denote beginning and end of a code fragment. By default TextTemplater uses {{ as open delimiter, and }} as closing delimiter.

Code fragment

A Perl program, embedded into template. It is usually small, just a variable or simple expression, but can be arbitrary big and complex.

SEE ALSO

Dist::Zilla
Dist::Zilla::Role::TextTemplater
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/>.