—

              
#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Role/TextTemplater/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-Role-TextTemplater.
#pod
#pod perl-Dist-Zilla-Role-TextTemplater is free software: you can redistribute it and/or modify
#pod it under the terms of the GNU General Public License as published by the Free Software
#pod Foundation, either version 3 of the License, or (at your option) any later version.
#pod
#pod perl-Dist-Zilla-Role-TextTemplater is distributed in the hope that it will be useful, but
#pod WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
#pod PARTICULAR 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-Role-TextTemplater. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut
#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# PODNAME: Dist::Zilla::Role::TextTemplater::Manual
# ABSTRACT: C<TextTemplater> role user manual
#pod =for :this This is C<TextTemplater> role user manual. Read this if you are using a
#pod C<TextTemplater>-based plugin.
#pod
#pod =for :those If you want to have text templating capabilities in your Dist::Zilla plugin, read the L<module documentation|Dist::Zilla::Role::TextTemplater>.
#pod General topics like getting source, building, installing, bug reporting and some others are covered
#pod in the F<README>.
#pod
#pod =for test_synopsis BEGIN { die "SKIP: Not Perl code.\n" };
#pod
#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     [ATextTemplaterBasedPlugin]
#pod         package    = MY
#pod         prepend    = use strict;
#pod         prepend    = use warnings;
#pod         delimiters = (* *)
#pod         …
#pod
#pod =head1 DESCRIPTION
#pod
#pod C<TextTemplater> is a C<Dist::Zilla> role. It cannot be directly used by the end user. However, the
#pod role provides F<dist.ini> options which have the same meaning for all C<TextTemplater>-based
#pod plugins. Describing options this manual makes documenting  C<TextTemplater>-based plugins simpler.
#pod
#pod The role provides three options: C<delimiters>, C<package> and C<prepend>.
#pod
#pod =option delimiters
#pod
#pod Delimiters
#pod
#pod The value should consist of two space-separated delimiters: opening delimiter and closing
#pod delimiter. Opening delimiter denotes the beginning of code fragment, closing delimiter signals the
#pod end of code fragment.
#pod
#pod Default value is C<{{ }}>.
#pod
#pod See C<DELIMITERS> option of L<Text::Template/"fill_in">.
#pod
#pod Note: Our default delimiters are "alternative delimiters" for C<Text::Template>. It means escaping
#pod delimiters with backslash does not work. See L<Text::Template/"Alternative Delimiters">.
#pod
#pod =option package
#pod
#pod Name of package to evaluate code fragments in.
#pod
#pod     package = MY
#pod
#pod See C<PACKAGE> option of L<Text::Template/"fill_in">.
#pod
#pod =option prepend
#pod
#pod Perl code to prepend to the beginning of every code fragment. Option may be specified several
#pod times. All the values will be joined with newlines.
#pod
#pod     prepend = use strict;
#pod     prepend = use warnings;
#pod
#pod See C<PREPEND> option of L<Text::Template/"fill_in">.
#pod
#pod =head1 GLOSSARY
#pod
#pod =begin :list
#pod
#pod = Template
#pod
#pod Plain text with embedded Perl code fragments. "Filling in" a template means that each code fragment
#pod is extracted, executed, and replaced with the result of execution.
#pod
#pod = Delimiters
#pod
#pod Character sequences which denote beginning and end of a code fragment. By default C<TextTemplater>
#pod uses C<{{> as open delimiter, and
#pod C<}}> as closing delimiter.
#pod
#pod = Code fragment
#pod
#pod A Perl program, embedded into template and surrounded by delimiters. It is usually small, just a
#pod variable or simple expression, but can be arbitrary big and complex.
#pod
#pod =end :list
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L<Dist::Zilla>
#pod = L<Dist::Zilla::Role::TextTemplater>
#pod = L<Text::Template>
#pod
#pod =cut
# doc/what.pod #
#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Role-TextTemplater> is a C<Dist::Zilla> role, a replacement for standard role C<TextTemplate>. Both
#pod roles have the same great C<Text::Template> engine under the hood, but this one provides better
#pod control over the engine and much better error reporting.
#pod
#pod =cut
# end of file #
# doc/why.pod #
#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod C<TextTemplate> role from C<Dist::Zilla> distribution v5.037 has the same great C<Text::Template>
#pod engine under the hood, but lacks of control and has I<awful> error reporting.
#pod
#pod =head2 Error Reporting
#pod
#pod Let us consider an example. For sake of example simplicity, it contains only one file, F<dist.ini>.
#pod Two files, F<lib/Assa.pm> and F<lib/Assa.pod>, are generated on-the-fly with C<GenerateFile>
#pod plugin.
#pod
#pod Have a look at F<dist.ini>:
#pod
#pod     name     = Assa
#pod     version  = 0.001
#pod     abstract = Example
#pod     [GenerateFile/lib/Assa.pm]
#pod         filename = lib/Assa.pm
#pod         content  = package Assa; 1;
#pod     [GenerateFile/lib/Assa/Manual.pod]
#pod         filename = lib/Assa/Manual.pod
#pod         content  = =head1 NAME
#pod         content  =
#pod         content  = {{$dst->name} - {{$dist->abstract}}
#pod         content  =
#pod         content  = Version {{$dist->version}}.
#pod         content  =
#pod         content  = {{$dist->license->notice}}
#pod     [TemplateFiles]
#pod         filename = lib/Assa.pm
#pod         filename = lib/Assa/Manual.pod
#pod     [MetaResources::Template]
#pod         homepage = https://example.org/release/{{$dist->name}}
#pod         license  = {{$dist->license->url}}
#pod
#pod
#pod (Do you see a typo? How many? Note this is a small example, real files are much larger.) Now let us
#pod build the distribution:
#pod
#pod     $ dzil build
#pod     [DZ] beginning to build Assa
#pod     [TemplateFiles] Filling in the template returned undef for:
#pod     [TemplateFiles] =head1 NAME
#pod     [TemplateFiles]
#pod     [TemplateFiles] {{$dst->name} - {{$dist->abstract}}
#pod     [TemplateFiles]
#pod     [TemplateFiles] Version {{$dist->version}}.
#pod     [TemplateFiles]
#pod     [TemplateFiles] {{$dist->license->notice}}
#pod
#pod     [TemplateFiles] Filling in the template returned undef for:
#pod     [TemplateFiles] =head1 NAME
#pod     [TemplateFiles]
#pod     [TemplateFiles] {{$dst->name} - {{$dist->abstract}}
#pod     [TemplateFiles]
#pod     [TemplateFiles] Version {{$dist->version}}.
#pod     [TemplateFiles]
#pod     [TemplateFiles] {{$dist->license->notice}}
#pod      at /home/vdb/.usr/opt/local-lib/lib/perl5/x86_64-linux-thread-multi/Moose/Meta/Method/Delegation.pm line 110.
#pod
#pod
#pod Oops. What's happened? Where? Why? All we have is a highly unclear error message
#pod
#pod     Filling in the template returned undef for:
#pod
#pod and file content printed twice. (Yep, if the problem file had 1000 lines, we would have it printed
#pod twice too.) We do not ever have a file name and have to guess it by the content. Good bug hunting,
#pod dude.
#pod
#pod Ok, let us fix the problem (mistyped closing delimiter in the first line of file
#pod F<lib/Assa/Manual.pod>) and build the distribution again:
#pod
#pod     $ dzil build
#pod     [DZ] beginning to build Assa
#pod     Can't call method "name" on an undefined value at template line 3.
#pod
#pod
#pod Oops. Error message much is better now, but where the problem is? There are many templates in the
#pod project: F<lib/Assa.pm>, F<lib/Assa/Manual.pod>, and even resources in F<META.yml> — all are
#pod generated from templates. Where is the problem? Good bug hunting for us all.
#pod
#pod Such error reporting is simply unacceptable. I am a human, I often make mistakes, and I want the
#pod tool clearly warns me I<what> and I<where> the problem is, so I can fix it quickly. For example,
#pod in the first case I want to see:
#pod
#pod     $ dzil build
#pod     [DZ] beginning to build Assa
#pod     [Templates] Unmatched opening delimiter at lib/Assa/Manual.pod line 3.
#pod     [Templates] lib/Assa/Manual.pod:
#pod     [Templates]     1: =head1 NAME
#pod     [Templates]     2:
#pod     [Templates]     3: {{$dst->name} - {{$dist->abstract}}
#pod     [Templates]        ^^^ Unmatched opening delimiter at lib/Assa/Manual.pod line 3. ^^^
#pod     [Templates]     4:
#pod     [Templates]     5: Version {{$dist->version}}.
#pod     [Templates]        ... skipped 2 lines ...
#pod     Aborting...
#pod
#pod
#pod In the second case:
#pod
#pod     $ dzil build
#pod     [DZ] beginning to build Assa
#pod     [Templates] Can't call method "name" on an undefined value at lib/Assa/Manual.pod line 3.
#pod     [Templates] Bad code fragment begins at lib/Assa/Manual.pod line 3.
#pod     [Templates] lib/Assa/Manual.pod:
#pod     [Templates]     1: =head1 NAME
#pod     [Templates]     2:
#pod     [Templates]     3: {{$dst->name}} - {{$dist->abstract}}
#pod     [Templates]        ^^^ Can't call method "name" on an undefined value at lib/Assa/Manual.pod line 3. ^^^
#pod     [Templates]        ^^^ Bad code fragment begins at lib/Assa/Manual.pod line 3. ^^^
#pod     [Templates]     4:
#pod     [Templates]     5: Version {{$dist->version}}.
#pod     [Templates]        ... skipped 2 lines ...
#pod     Aborting...
#pod
#pod
#pod C<TextTemplater> makes it real. All I need is using C<TextTemplater>-based plugins: C<Templates>,
#pod C<MetaResources::Template> (starting from v0.002).
#pod
#pod =head2 Engine Control
#pod
#pod C<TextTemplater> allows the end-user to specify C<delimiters>, C<package> and C<prepend> engine
#pod options in F<dist.ini> file, while C<TextTemplate> allows to specify C<prepend> only
#pod programmatically, and does I<not> allow to specify C<delimiters> and C<package>.
#pod
#pod =cut
# end of file #
# end of file #
__END__
HideShow 259 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
Dist::Zilla::Role::TextTemplater::Manual - C<TextTemplater> role user manual
=head1 VERSION
Version v0.8.5, released on 2015-10-31 23:02 UTC.
=head1 WHAT?
C<Dist-Zilla-Role-TextTemplater> is a C<Dist::Zilla> role, a replacement for standard role C<TextTemplate>. Both
roles have the same great C<Text::Template> engine under the hood, but this one provides better
control over the engine and much better error reporting.
This is C<TextTemplater> role user manual. Read this if you are using a
C<TextTemplater>-based plugin.
If you want to have text templating capabilities in your Dist::Zilla plugin, read the L<module documentation|Dist::Zilla::Role::TextTemplater>.
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>:
    [ATextTemplaterBasedPlugin]
        package    = MY
        prepend    = use strict;
        prepend    = use warnings;
        delimiters = (* *)
        …
=head1 DESCRIPTION
C<TextTemplater> is a C<Dist::Zilla> role. It cannot be directly used by the end user. However, the
role provides F<dist.ini> options which have the same meaning for all C<TextTemplater>-based
plugins. Describing options this manual makes documenting  C<TextTemplater>-based plugins simpler.
The role provides three options: C<delimiters>, C<package> and C<prepend>.
=head1 OPTIONS
=head2 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 C<{{ }}>.
See C<DELIMITERS> option of L<Text::Template/"fill_in">.
Note: Our default delimiters are "alternative delimiters" for C<Text::Template>. It means escaping
delimiters with backslash does not work. See L<Text::Template/"Alternative Delimiters">.
=head2 package
Name of package to evaluate code fragments in.
    package = MY
See C<PACKAGE> option of L<Text::Template/"fill_in">.
=head2 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 C<PREPEND> option of L<Text::Template/"fill_in">.
=head1 WHY?
C<TextTemplate> role from C<Dist::Zilla> distribution v5.037 has the same great C<Text::Template>
engine under the hood, but lacks of control and has I<awful> error reporting.
=head2 Error Reporting
Let us consider an example. For sake of example simplicity, it contains only one file, F<dist.ini>.
Two files, F<lib/Assa.pm> and F<lib/Assa.pod>, are generated on-the-fly with C<GenerateFile>
plugin.
Have a look at F<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
F<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: F<lib/Assa.pm>, F<lib/Assa/Manual.pod>, and even resources in F<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 I<what> and I<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...
C<TextTemplater> makes it real. All I need is using C<TextTemplater>-based plugins: C<Templates>,
C<MetaResources::Template> (starting from v0.002).
=head2 Engine Control
C<TextTemplater> allows the end-user to specify C<delimiters>, C<package> and C<prepend> engine
options in F<dist.ini> file, while C<TextTemplate> allows to specify C<prepend> only
programmatically, and does I<not> allow to specify C<delimiters> and C<package>.
=for test_synopsis BEGIN { die "SKIP: Not Perl code.\n" };
=head1 GLOSSARY
=over 4
=item 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.
=item Delimiters
Character sequences which denote beginning and end of a code fragment. By default C<TextTemplater>
uses C<{{> as open delimiter, and
C<}}> as closing delimiter.
=item 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.
=back
=head1 SEE ALSO
=over 4
=item L<Dist::Zilla>
=item L<Dist::Zilla::Role::TextTemplater>
=item L<Text::Template>
=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-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/>.
=cut