/ 
Dist-Zilla-Plugin-Templates-v0.6.3
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::Templates::Manual

NAME

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

VERSION

Version v0.6.3, released on 2016-12-26 21:02 UTC.

WHAT?

Dist-Zilla-Plugin-Templates (or just Templates for brevity) is a Dist-Zilla plugin allowing developers to insert Perl code fragments into arbitrary source text files, which become templates. When Dist::Zilla builds the distribution each code fragment is evaluated and replaced with result of evaluation.

This is Templates user manual. Read this if you want to treat source files as templates.

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
        ; ^ Treat these files as templates.
    package = MY
        ; ^ Evaluate Perl fragments in context of this package.
    prepend = use strict;
        ; ^ Prepend this to 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 eg/example.pl file,
    # strip trailing newlines,
    # indent entire text to make it verbatim:
    include( "eg/example.pl" )->chomp->indent;
}}

=head1 COPYRIGHT AND LICENSE

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

=cut

DESCRIPTION

Templates is a Dist::Zilla plugin. More precisely it a file munger. It munges source files found by the file finder(s) enlisted in the templates option, e. g.:

[Templates]
    templates = :InstallModules
    templates = :PerlExecFiles

BTW, the term source files means "arbitrary text files in the source tree", not just "Perl sources".

Templates treats files specified by the file finders as templates. See the TextTemplater manual for explanation what template is.

Predefined Variables

There are few variables defined by TextTemplater, see Predefined Variables in the TextTemplater manual. Templates does not introduce any more variables.

Predefined Functions

Templates define only one (but frequently used) function for file inclusion, include.

Do not forget that full Perl power is in your hands: code fragments can use any Perl built-in function or any third-party module.

See also: "Including files into templates" in Text::Template.

include

include( $filename )

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

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

can be shortened to

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

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

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

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

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

{{ include( 'eg/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, …) are provided by the Dist::Zilla::Role::TextTemplater role, so see TextTemplater manual for description.

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:

[FileFinder::ByName/Examples]
    dir = eg
[Templates]
    templates = Examples

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.

KNOWN BUGS

Unicode characters

include(…)->pod2text may munge Unicode characters due to a bug in Pod::Simple. Templates test suite includes Unicode characters test. The test fails with Pod:Simple 3.20 (and earlier versions) and passes with Pod::Simple 3.28 (and later versions).

WHY?

Because I was not satisfied with the 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

Including Examples

Including an example into documentation is trivial:

=head1 EXAMPLES

=head2 Example Assa

{{ include( "eg/Assa.pl" )->chomp->indent; }}

But let's include several examples:

=head1 EXAMPLES

{{
    for my $file ( qw{ Assa.pl Shooba.pm Dooba.sh } ) {
        $OUT .= "=head2 $file\n\n";
        $OUT .= include( "eg/$file" )->chomp->indent . "\n\n";
    };
}}

Or all the examples:

{{
    use Path::Tiny;
    for my $file ( sort( path( "eg" )->children ) ) {
        # the same as above
    };
}}

Documenting Default Values

Let's assume your module has an option with some default value:

$option = 72;

When you writing documentation, you have to write down its default value once again:

=head2 option

... by default 72 ...

Now you have the same value scattered in the source. When you decide to change default, you have to remember to update documentation too. However, you can avoid duplication:

$option = {{$option = 72}};

=head2 option

... by default {{$option}} ...

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 5.037).

Dist::Zilla::Role::TextTemplater

An alternative to standard Dist::Zilla::Role::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 Dist::Zilla::Role::TextTemplate role with all the subsequences.

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

A combo of file gathering and templating capabilities. It uses standard Dist::Zilla::Role::TextTemplate role.

Text::Template

The great templating engine used by both Dist::Zilla::Role::TextTemplate and Dist::Zilla::Role::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.