The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dist-Zilla-Plugin-Templates-v0.6.0
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Dist::Zilla::Plugin::Templates::Manual

NAME

Dist::Zilla::Plugin::Templates::Manual - Templates plugin user manual

VERSION

Version v0.6.0, released on 2015-10-31 21:54 UTC.

WHAT?

Dist-Zilla-Plugin-Templates (or just Templates) is a Dist-Zilla plugin allowing developers to insert fragments of Perl code into arbitrary text files, which become templates. When building a distribution with Dist::Zilla, Templates plugin evaluates these fragments, and replaces each fragment with result of its evaluation.

This is Templates user manual. Read this if you want to convert any text file into template.

If you are going to hack or extend Dist-Zilla-Plugin-Templates, 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:

    name    = Assa
    version = 0.007
    …
    [Templates]
        templates = :InstallModules
            ; ^ Template files,
            ;   all .pm and .pod files in this example.
        package = MY
            ; ^ Evaluate Perl fragments in context
            ;   of this package.
        prepend = use autodie ':all';
        prepend = use Path::Tiny;
            ; ^ Code to execute in the beginning of
            ;   each fragment.
    …

In lib/Assa.pm:

    package Assa;
    our $VERSION = '{{ $dist->version }}';
    …
    1;

    =head1 RATIONALE

    {{
        # Include content of doc/rationale.pod file
        # (with expanding templates, if any):
        include( "doc/rationale.pod" )->fill_in;
    }}

    =head1 EXAMPLES

    =head2 example.pl

    {{
        # Include content of ex/example.pl file,
        # strip trailing newlines,
        # indent it to make it verbatim:
        include( "ex/example.pl" )->chomp->indent;
    }}

    =head1 COPYRIGHT AND LICENSE

    {{ $dist->license->notice }}

    =cut

DESCRIPTION

TODO

Predefined Variables

$dist

Reference to Dist::Zilla object. Primary purpose of the variable is providing access to the distribution properties, like $dist->version, $dist->name, $dist->version, etc, but $dist also gives full access to Dist::Zilla object.

$plugin

Reference to the plugin (usually to the Templates, or to its descendant, if someone creates it). There is no much meaning in it, though. The variable is provided for compatibility with GatherDir::Template plugin. However, the variable can be used for debug or error reporting, e. g.:

    $plugin->log_debug( … );
    $plugin->log( … );

Predefined Functions

include

    include( $filename )

The function include returns a reference to Dist::Zilla::Plugin::Templates::File object (which is a descendant of Dist::Zilla::File::InMemory class). The object being evaluated in string context returns the file content, so

    {{ include( 'ex/example.pl' )->content; }}

can be shortened to

    {{ include( 'ex/example.pl' ); }}

with the same result.

Dist::Zilla::Plugin::Templates::File defines few methods which can be useful in Perl code and/or POD templates:

    {{ include( 'ex/example.pl' )->indent; }}

    {{
        include( 'doc/caveats.pod' )->fill_in .
        include( 'doc/feedback.pod' )->fill_in;
    }}

Since many Dist::Zilla::Plugin::Templates::File methods return self-reference, calls may be chained:

    {{ include( 'ex/example.pl' )->fill_in->chomp->indent; }}

See Dist::Zilla::Plugin::Templates::File for the list of methods.

OPTIONS

The plugin defines only one option templates. Other options (package, prepend, delimiter, …) come from TextTemplater role, so see TextTemplater role manual for details.

template

templates

Name of file finder to provide files to be treated as templates. The default value is :NoFiles. Use any of standard finders like :MainModule, :InstallModules, :AllFiles (see "default_finders" in Dist::Zilla::Role::FileFinderUser), or create your own finder with FileFinder::ByName and FileFinder::Filter plugins.

Option may be specified several times, e. g.:

    templates = :InstallModules
    templates = :TestFiles

Each selected file will be processed only once, even if a file "found" by more than one finder:

    templates = :InstallModules
    templates = :AllFiles

template is an alias for templates.

WHY?

Because I was not satisfied with existing solutions.

GatherDir::Template (shipped as a part of Dist::Zilla) combines two tasks: it adds files to distribution and does template processing. Such coupling introduces some limitations: All the templates must be in a separate directory, you cannot freely mix template and non-template files. If you use source manifest and adds files to distribution with Manifest::Read or GatherFromManifest plugins, you cannot manifest your templates — it causes "attempt to add filename multiple times" error.

TemplateFiles solves this problem, but has its own limitations. It requires to list all the templates individually, you cannot use Dist::Zilla file finders to declare all install modules (or all tests, or all files, etc).

Both GatherDir::Template and TemplateFiles suffer from disadvantages of Dist::Zilla TextTemplate role: lack of control over Text::Template engine and awful error reporting.

Thus, Templates plugin:

  • Uses TextTemplater role to provide better control over Text::Template engine and better error reporting.

  • Uses Dist::Zilla file finders to select files.

EXAMPLES

TODO:

SEE ALSO

Dist::Zilla

Distribution builder.

Dist::Zilla::Role::TextTemplate

Bridge between Dist::Zilla and Text::Template, provides templating capabilities to Dist::Zilla plugins. It is a part of Dist::Zilla distribution. It has limited template engine control and awful error reporting (as of v5.037).

Dist::Zilla::Role::TextTemplater

An alternative to standard TextTemplate, it uses the same template engine, Text::Template, but provides better engine control and error reporting.

Dist::Zilla::Plugin::TemplateFiles

Alternative approach. It does not use file finders, so you have to specify every template file individually. It also uses Dist::Zilla standard TextTemplate role with all the subsequences.

Dist::Zilla::Plugin::GatherDir::Template

A combo of file gathering and templating capabilities. It uses standard TextTemplate role.

Text::Template

The great templating engine used by both TextTemplate and TextTemplater roles.

Dist::Zilla::Plugin::Templates

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015 Van de Bugger

License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.