NAME¶
Dist::Zilla::Plugin::TemplateCJM - Process templates, including version numbers
& changes
VERSION¶
This document describes version 4.09 of Dist::Zilla::Plugin::TemplateCJM,
released June 4, 2012 as part of Dist-Zilla-Plugins-CJM version 4.09.
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
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 as it appeared in Changes.
- $dist
- The name of the distribution.
- %meta
- The hash of metadata that will be stored in
META.yml.
- $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).
- $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.
It also peforms a BeforeRelease check to ensure that the release date in the
changelog is not a single uppercase word. (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.
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 "file"s, it defaults to
README. If you do specify
any "file"s, 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.
dependency_link¶
$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 he dependencies, it is listed first. 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 (4.300009 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-Plugins-CJM AT rt.cpan.org>" or
through the web interface at
http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugins-CJM
<
http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugins-CJM>.
You can follow or contribute to Dist-Zilla-Plugins-CJM's development at
http://github.com/madsen/dist-zilla-plugins-cjm
<
http://github.com/madsen/dist-zilla-plugins-cjm>.
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 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.