/ 
Dist-Zilla-Role-TextTemplater-v0.8.5_01
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 v0.8.5_01, released on 2016-10-11 20:06 UTC. This is a trial release.

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

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. For sake of example simplicity, it contains only one file, dist.ini. Two files, lib/Assa.pm and lib/Assa.pod, are generated on-the-fly with GenerateFile plugin.

Have a look at dist.ini:

name     = Assa
version  = 0.001
abstract = Example
[GenerateFile/lib/Assa.pm]
    filename = lib/Assa.pm
    content  = package Assa; 1;
[GenerateFile/lib/Assa/Manual.pod]
    filename = lib/Assa/Manual.pod
    content  = =head1 NAME
    content  =
    content  = {{$dst->name} - {{$dist->abstract}}
    content  =
    content  = Version {{$dist->version}}.
    content  =
    content  = {{$dist->license->notice}}
[TemplateFiles]
    filename = lib/Assa.pm
    filename = lib/Assa/Manual.pod
[MetaResources::Template]
    homepage = https://example.org/release/{{$dist->name}}
    license  = {{$dist->license->url}}

(Do you see a typo? How many? Note this is a small example, real files are much larger.) Now let us build the distribution:

$ dzil build
[DZ] beginning to build Assa
[TemplateFiles] Filling in the template returned undef for:
[TemplateFiles] =head1 NAME
[TemplateFiles]
[TemplateFiles] {{$dst->name} - {{$dist->abstract}}
[TemplateFiles]
[TemplateFiles] Version {{$dist->version}}.
[TemplateFiles]
[TemplateFiles] {{$dist->license->notice}}

[TemplateFiles] Filling in the template returned undef for:
[TemplateFiles] =head1 NAME
[TemplateFiles]
[TemplateFiles] {{$dst->name} - {{$dist->abstract}}
[TemplateFiles]
[TemplateFiles] Version {{$dist->version}}.
[TemplateFiles]
[TemplateFiles] {{$dist->license->notice}}
 at /home/vdb/.usr/opt/local-lib/lib/perl5/x86_64-linux-thread-multi/Moose/Meta/Method/Delegation.pm line 110.

Oops. What's happened? Where? Why? All we have is a highly unclear error message

Filling in the template returned undef for:

and file content printed twice. (Yep, if the problem file had 1000 lines, we would have it printed twice too.) We do not ever have a file name and have to guess it by the content. Good bug hunting, dude.

Ok, let us fix the problem (mistyped closing delimiter in the first line of file lib/Assa/Manual.pod) and build the distribution again:

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

Oops. Error message much is better now, but where the problem is? There are many templates in the project: lib/Assa.pm, lib/Assa/Manual.pod, and even resources in META.yml — all are generated from templates. Where is the problem? Good bug hunting for us all.

Such error reporting is simply unacceptable. I am a human, I often make mistakes, and I want the tool clearly warns me what and where the problem is, so I can fix it quickly. For example, in the first case I want to see:

$ dzil build
[DZ] beginning to build Assa
[Templates] Unmatched opening delimiter at lib/Assa/Manual.pod line 3.
[Templates] lib/Assa/Manual.pod:
[Templates]     1: =head1 NAME
[Templates]     2:
[Templates]     3: {{$dst->name} - {{$dist->abstract}}
[Templates]        ^^^ Unmatched opening delimiter at lib/Assa/Manual.pod line 3. ^^^
[Templates]     4:
[Templates]     5: Version {{$dist->version}}.
[Templates]        ... skipped 2 lines ...
Aborting...

In the second case:

$ dzil build
[DZ] beginning to build Assa
[Templates] Can't call method "name" on an undefined value at lib/Assa/Manual.pod line 3.
[Templates] Bad code fragment begins at lib/Assa/Manual.pod line 3.
[Templates] lib/Assa/Manual.pod:
[Templates]     1: =head1 NAME
[Templates]     2:
[Templates]     3: {{$dst->name}} - {{$dist->abstract}}
[Templates]        ^^^ Can't call method "name" on an undefined value at lib/Assa/Manual.pod line 3. ^^^
[Templates]        ^^^ Bad code fragment begins at lib/Assa/Manual.pod line 3. ^^^
[Templates]     4:
[Templates]     5: Version {{$dist->version}}.
[Templates]        ... skipped 2 lines ...
Aborting...

TextTemplater makes it real. All I need is using TextTemplater-based plugins: Templates, MetaResources::Template (starting from v0.002).

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.

In your dist.ini:

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

GLOSSARY

Template

Plain text with embedded Perl code fragments. "Filling in" a template means that each code fragment is 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 and surrounded by delimiters. 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/>.