The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dist-Zilla-Plugin-TemplateCJM-5.001
River stage zero No dependents
++
/ Dist::Zilla::Plugin::TemplateCJM

NAME

Dist::Zilla::Plugin::TemplateCJM - Process templates, including version numbers & changes

VERSION

This document describes version 5.001 of Dist::Zilla::Plugin::TemplateCJM, released December 12, 2015.

SYNOPSIS

In your dist.ini:

  [TemplateCJM]
  changelog = Changes      ; this is the default
  changes   = 1            ; this is the default
  file      = README       ; this is the default
  report_versions = 1      ; this is the default
  date_format     =        ; this is the default

DESCRIPTION

This plugin is the successor to Module::Build::DistVersion. It performs the following actions:

  1. It opens the Changes file, and finds the first version listed. The line must begin with the version number, and everything after the version number is considered to be the release date. The version number from Changes must match Dist::Zilla's idea of the distribution version, or the process stops here with an error.

  2. It processes each template file with Text::Template. Template files are specified with the file attribute. Any number of templates may be present.

    Each template may use the following variables:

    $changes

    The changes in the current release. This is a string containing all lines in Changes following the version/release date line up to (but not including) the next line that begins with a non-whitespace character (or end-of-file). The string does not end with a newline (since version 0.08).

    You can include the changes from more than one release by setting the "changes" in changes attribute. This is useful when you make a major release immediately followed by a bugfix release.

    $date

    The release date taken from Changes and reformatted using "date_format". If date_format is the empty string, or if the release date cannot be parsed as a date, this is the date exactly as it appears in Changes.

    $datetime

    The release date taken from Changes as a DateTime object, or undef if the release date could not be parsed as a date.

    $dist

    The name of the distribution.

    $filename

    The filename of the file being processed, with any directory names omitted. See also $pathname.

    %meta

    The hash of metadata that will be stored in META.yml.

    $pathname

    The pathname of the file being processed, relative to the distribution root in Unix format (forward slashes). See also $filename.

    $t

    The TemplateCJM object that is processing the template.

    $version

    The distribution's version number. (Also available as $dist_version.)

    $zilla

    The Dist::Zilla object that is creating the distribution.

  3. For each module to be installed, it processes each POD section and each comment that starts at the beginning of a line through Text::Template.

    Each section may use the same variables as step 2, plus the following:

    $module

    The name of the module being processed (i.e., its package). In the case of a pure-POD file without a package declaration, this is derived from its filename (which must match the regex ^lib/(.+)\.pod$).

    $pm_info

    A Module::Metadata object containing information about the module. (Note that the filename in $pm_info will not be correct.)

    $version

    The module's version number. This may be different than the distribution's version, which is available as $dist_version. In the case of a pure-POD file without a $VERSION declaration, this will be the same as $dist_version.

It also peforms a BeforeRelease check to ensure that the release date in the changelog is a valid date. (I set the date to NOT until I'm ready to release.)

ATTRIBUTES

changelog

This is the name of the Changes file. It defaults to Changes.

changelog_re

This is the regex used to extract the version and release date from the Changes file. It defaults to (\d[\d._]*)\s+(.+) (i.e. version number at beginning of the line, followed by whitespace, and everything after that is the release date). It it automatically anchored at the beginning of the line. Note: your version lines must not begin with whitespace. All other lines must begin with whitespace.

changes

This is the number of releases to include in the $changes variable passed to templates. It defaults to 1 (meaning only changes in the current release). This is useful when you make a major release immediately followed by a bugfix release.

date_format

This is the DateTime CLDR format to use for the $date variable in templates. The default value is the empty string, which means to use the date exactly as it appeared in the Changes file.

file

This is the name of a file to process with Text::Template in step 2. The file attribute may be listed any number of times. If you don't list any files, it defaults to README. If you do specify any files, then README is not processed unless explicitly specified.

finder

This FileFinder provides the list of files that are processed in step 3. The default is :InstallModules. The finder attribute may be listed any number of times.

report_versions

If true (the default), report the version of each module processed.

METHODS

build_instructions

  $t->build_instructions( [$prefix] )

A template can use this method to add build instructions for the distribution (normally used in README). $prefix is prepended to each line, and defaults to a single TAB.

It returns either

        perl Build.PL
        ./Build
        ./Build test
        ./Build install

or

        perl Makefile.PL
        make
        make test
        make install

depending on whether your distribution includes a Build.PL. The string will NOT end with a newline.

It throws an error if neither Build.PL nor Makefile.PL is found.

  $t->dependency_link('Foo::Bar')

A template can use this method to add a link to the documentation of a required module. It returns either

  L<Foo::Bar> (VERSION or later)

or

  L<Foo::Bar>

depending on whether VERSION is non-zero. (It determines VERSION by checking requires and recommends in your prerequisites.)

dependency_list

  $t->dependency_list

A template can use this method to add a list of required modules. It returns a string like:

  Package                Minimum Version
  ---------------------- ---------------
  perl                    5.8.0
  List::Util
  Moose                   0.90

If perl is one of the dependencies, it is listed first. Also, its version (if >= 5.6.0) will be normalized into double-decimal form, even if the prerequisites list it as floating point.

All other dependencies are listed in ASCIIbetical order. The string will NOT end with a newline.

If there are no dependencies, the string None. will be returned.

DEPENDENCIES

TemplateCJM requires Dist::Zilla (5 or later) and Text::Template. I also recommend applying Template_strict.patch to Text::Template. This will add support for the STRICT option, which will help catch errors in your templates.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-Dist-Zilla-Plugin-TemplateCJM AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugin-TemplateCJM.

You can follow or contribute to Dist-Zilla-Plugin-TemplateCJM's development at https://github.com/madsen/dist-zilla-plugin-templatecjm.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.