#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Plugin/Templates/Manual.pod
#

#pod =encoding UTF-8
#pod
#pod =head1 COPYRIGHT AND LICENSE
#pod
#pod Copyright © 2015 Van de Bugger
#pod
#pod This file is part of perl-Dist-Zilla-Plugin-Templates.
#pod
#pod perl-Dist-Zilla-Plugin-Templates is free software: you can redistribute it and/or modify it
#pod under the terms of the GNU General Public License as published by the Free Software Foundation,
#pod either version 3 of the License, or (at your option) any later version.
#pod
#pod perl-Dist-Zilla-Plugin-Templates is distributed in the hope that it will be useful, but WITHOUT
#pod ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
#pod PURPOSE. See the GNU General Public License for more details.
#pod
#pod You should have received a copy of the GNU General Public License along with
#pod perl-Dist-Zilla-Plugin-Templates. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut

# PODNAME: Dist::Zilla::Plugin::Templates::Manual
# ABSTRACT: C<Templates> plugin user manual

#pod =for :this This is C<Templates> user manual. Read this if you want to convert any text file into template.
#pod
#pod =for :those If you are going to hack or extend C<Dist-Zilla-Plugin-Templates>, read the L<module
#pod documentation|Dist::Zilla::Plugin::Templates>. General topics like getting source, building, installing, bug
#pod reporting and some others are covered in the F<README>.
#pod
#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     name    = Assa
#pod     version = 0.007
#pod     …
#pod     [Templates]
#pod         templates = :InstallModules
#pod             ; ^ Template files,
#pod             ;   all .pm and .pod files in this example.
#pod         package = MY
#pod             ; ^ Evaluate Perl fragments in context
#pod             ;   of this package.
#pod         prepend = use autodie ':all';
#pod         prepend = use Path::Tiny;
#pod             ; ^ Code to execute in the beginning of
#pod             ;   each fragment.
#pod     …
#pod
#pod In F<lib/Assa.pm>:
#pod
#pod     package Assa;
#pod     our $VERSION = '{{ $dist->version }}';
#pod     …
#pod     1;
#pod
#pod     =head1 RATIONALE
#pod
#pod     {{
#pod         # Include content of doc/rationale.pod file
#pod         # (with expanding templates, if any):
#pod         include( "doc/rationale.pod" )->fill_in;
#pod     }}
#pod
#pod     =head1 EXAMPLES
#pod
#pod     =head2 example.pl
#pod
#pod     {{
#pod         # Include content of ex/example.pl file,
#pod         # strip trailing newlines,
#pod         # indent it to make it verbatim:
#pod         include( "ex/example.pl" )->chomp->indent;
#pod     }}
#pod
#pod     =head1 COPYRIGHT AND LICENSE
#pod
#pod     {{ $dist->license->notice }}
#pod
#pod     =cut
#pod
#pod =head1 DESCRIPTION
#pod
#pod TODO
#pod
#pod =head2 Predefined Variables
#pod
#pod =head3 C<$dist>
#pod
#pod Reference to C<Dist::Zilla> object. Primary purpose of the variable is providing access to the
#pod distribution properties, like C<< $dist->version >>, C<< $dist->name >>, C<< $dist->version >>,
#pod etc, but C<$dist> also gives full access to C<Dist::Zilla> object.
#pod
#pod =head3 C<$plugin>
#pod
#pod Reference to the plugin (usually to the C<Dist::Zilla::Plugin::Templates>, or to its descendant, if
#pod someone creates it). There is no much meaning in it, though. The variable is provided for
#pod compatibility with C<GatherDir::Template> plugin. However, the variable can be used for debug or
#pod error reporting, e. g.:
#pod
#pod     $plugin->log_debug( … );
#pod     $plugin->log( … );
#pod
#pod =head2 Predefined Functions
#pod
#pod =head3 C<include>
#pod
#pod     include( $filename )
#pod
#pod The function C<include> returns a reference to C<Dist::Zilla::Template::File> object (which is a
#pod descendant of C<Dist::Zilla::File::OnDisk> class). The object being evaluated in string context
#pod returns the file content, so
#pod
#pod     {{ include( 'ex/example.pl' )->content; }}
#pod
#pod can be shortened to
#pod
#pod     {{ include( 'ex/example.pl' ); }}
#pod
#pod with the same result.
#pod
#pod C<Dist::Zilla::Template::File> defines few methods which can be useful in Perl code and/or POD
#pod templates:
#pod
#pod     {{ include( 'ex/example.pl' )->indent; }}
#pod
#pod     {{
#pod         include( 'doc/caveats.pod' )->fill_in .
#pod         include( 'doc/feedback.pod' )->fill_in;
#pod     }}
#pod
#pod Since many C<Dist::Zilla::Template::File> methods return self-reference, calls may be chained:
#pod
#pod     {{ include( 'ex/example.pl' )->fill_in->chomp->indent; }}
#pod
#pod See C<Dist::Zilla::Template::File> for the list of methods.
#pod
#pod =head1 OPTIONS
#pod
#pod The plugin defines only one option C<templates>. Other options (C<package>, C<prepend>,
#pod C<delimiter>, …) come from C<TextTemplater> role, so see C<Dist::Zilla::Role::TextTemlater> manual
#pod for details.
#pod
#pod =option template
#pod
#pod =option templates
#pod
#pod Name of file finder to provide files to be treated as templates. The default value is C<:NoFiles>.
#pod Use any of standard finders like C<:MainModule>, C<:InstallModules>, C<:AllFiles> (see
#pod L<Dist::Zilla::Role::FileFinderUser/"default_finders">), or create your own finder with
#pod C<FileFinder::ByName> and C<FileFinder::Filter> plugins.
#pod
#pod Option may be specified several times, e. g.:
#pod
#pod     templates = :InstallModules
#pod     templates = :TestFiles
#pod
#pod Each selected file will be processed only once, even if a file "found" by more than one finder:
#pod
#pod     templates = :InstallModules
#pod     templates = :AllFiles
#pod
#pod C<template> is an alias for C<templates>.
#pod
#pod =head1 EXAMPLES
#pod
#pod TODO:
#pod
#pod =head1 SEE ALSO
#pod
#pod =begin :list
#pod
#pod = L<Dist::Zilla>
#pod Distribution builder.
#pod
#pod = L<Dist::Zilla::Role::TextTemplate>
#pod Bridge between C<Dist::Zilla> and C<Text::Template>, provides templating capabilities to
#pod C<Dist::Zilla> plugins. It is a part of C<Dist::Zilla> distribution. It has limited template engine
#pod control and awful error reporting (as of v5.037).
#pod
#pod = L<Dist::Zilla::Role::TextTemplater>
#pod An alternative to standard C<Dist::Zilla::Role::TextTemplate>, it uses the same template engine,
#pod C<Text::Template>, but provides better engine control and error reporting.
#pod
#pod = L<Dist::Zilla::Plugin::TemplateFiles>
#pod Alternative approach. It does not use file finders, so you have to specify every template file
#pod individually. It also uses C<Dist::Zilla> standard C<TextTemplate> role with all the subsequences.
#pod
#pod = L<Dist::Zilla::Plugin::GatherDir::Template>
#pod A combo of file gathering and templating capabilities. It uses standard C<TextTemplate> role.
#pod
#pod = L<Text::Template>
#pod The great templating engine used by both C<TextTemplate> and C<TextTemplater> roles.
#pod
#pod = L<Dist::Zilla::Plugin::Templates>
#pod
#pod =end :list
#pod
#pod =cut

# doc/what.pod #

#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Plugin-Templates> (or just C<Templates>) is a C<Dist-Zilla> plugin allowing developers to insert
#pod fragments of Perl code into arbitrary text files, which become I<templates>. When building a
#pod distribution with C<Dist::Zilla>, C<Templates> plugin evaluates these fragments, and replaces each
#pod fragment with result of its evaluation.
#pod
#pod =cut

# end of file #
# doc/why.pod #

#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod Because I was not satisfied with existing solutions.
#pod
#pod C<GatherDir::Template> (shipped as a part of C<Dist::Zilla>) combines two tasks: it adds files to
#pod distribution B<and> does template processing. Such coupling introduces some limitations: All the
#pod templates must be in a separate directory, you cannot freely mix template and non-template files.
#pod If you use source manifest and adds files to distribution with C<Manifest::Read> or
#pod C<GatherFromManifest> plugins, you cannot manifest your templates — it causes "attempt to add
#pod I<filename> multiple times" error.
#pod
#pod C<TemplateFiles> solves this problem, but has its own limitations. It requires to list all the
#pod templates individually, you cannot use C<Dist::Zilla> file finders to declare all install modules
#pod (or all tests, or all files, etc).
#pod
#pod Both C<GatherDir::Template> and C<TemplateFiles> suffer from disadvantages of C<Dist::Zilla>
#pod C<TextTemplate> role: lack of control over C<Text::Template> engine and awful error reporting.
#pod
#pod Thus, C<Templates> plugin:
#pod
#pod =over
#pod
#pod =item *
#pod
#pod Uses C<TextTemplater> role to provide better control over C<Text::Template> engine and better
#pod error reporting.
#pod
#pod =item *
#pod
#pod Uses C<Dist::Zilla> file finders to select files.
#pod
#pod =back
#pod
#pod =cut

# end of file #


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::Templates::Manual - C<Templates> plugin user manual

=head1 VERSION

Version v0.5.2, released on 2015-09-24 20:14 UTC.

=head1 WHAT?

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

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

If you are going to hack or extend C<Dist-Zilla-Plugin-Templates>, read the L<module
documentation|Dist::Zilla::Plugin::Templates>. General topics like getting source, building, installing, bug
reporting and some others are covered in the F<README>.

=head1 SYNOPSIS

In your F<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 F<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

=head1 DESCRIPTION

TODO

=head2 Predefined Variables

=head3 C<$dist>

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

=head3 C<$plugin>

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

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

=head2 Predefined Functions

=head3 C<include>

    include( $filename )

The function C<include> returns a reference to C<Dist::Zilla::Template::File> object (which is a
descendant of C<Dist::Zilla::File::OnDisk> 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.

C<Dist::Zilla::Template::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 C<Dist::Zilla::Template::File> methods return self-reference, calls may be chained:

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

See C<Dist::Zilla::Template::File> for the list of methods.

=head1 OPTIONS

The plugin defines only one option C<templates>. Other options (C<package>, C<prepend>,
C<delimiter>, …) come from C<TextTemplater> role, so see C<Dist::Zilla::Role::TextTemlater> manual
for details.

=head2 template

=head2 templates

Name of file finder to provide files to be treated as templates. The default value is C<:NoFiles>.
Use any of standard finders like C<:MainModule>, C<:InstallModules>, C<:AllFiles> (see
L<Dist::Zilla::Role::FileFinderUser/"default_finders">), or create your own finder with
C<FileFinder::ByName> and C<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

C<template> is an alias for C<templates>.

=head1 EXAMPLES

TODO:

=head1 WHY?

Because I was not satisfied with existing solutions.

C<GatherDir::Template> (shipped as a part of C<Dist::Zilla>) combines two tasks: it adds files to
distribution B<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 C<Manifest::Read> or
C<GatherFromManifest> plugins, you cannot manifest your templates — it causes "attempt to add
I<filename> multiple times" error.

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

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

Thus, C<Templates> plugin:

=over

=item *

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

=item *

Uses C<Dist::Zilla> file finders to select files.

=back

=head1 SEE ALSO

=over 4

=item L<Dist::Zilla>

Distribution builder.

=item L<Dist::Zilla::Role::TextTemplate>

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

=item L<Dist::Zilla::Role::TextTemplater>

An alternative to standard C<Dist::Zilla::Role::TextTemplate>, it uses the same template engine,
C<Text::Template>, but provides better engine control and error reporting.

=item L<Dist::Zilla::Plugin::TemplateFiles>

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

=item L<Dist::Zilla::Plugin::GatherDir::Template>

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

=item L<Text::Template>

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

=item L<Dist::Zilla::Plugin::Templates>

=back

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-Templates.

perl-Dist-Zilla-Plugin-Templates 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-Plugin-Templates 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-Plugin-Templates. If not, see <http://www.gnu.org/licenses/>.

=cut
