CPAN::Changes
Section: User Contributed Perl Documentation (3pm)
Updated: 2015-06-21
Index
Return to Main Contents
NAME
CPAN::Changes - Read and write Changes files
SYNOPSIS
# Load from file
my $changes = CPAN::Changes->load( 'Changes' );
# Create a new Changes file
$changes = CPAN::Changes->new(
preamble => 'Revision history for perl module Foo::Bar'
);
$changes->add_release( {
version => '0.01',
date => '2009-07-06',
} );
$changes->serialize;
DESCRIPTION
It is standard practice to include a Changes file in your distribution. The
purpose the Changes file is to help a user figure out what has changed since
the last release.
People have devised many ways to write the Changes file. A preliminary
specification has been created (CPAN::Changes::Spec) to encourage module
authors to write clear and concise Changes.
This module will help users programmatically read and write Changes files that
conform to the specification.
METHODS
new( %args )
Creates a new object using %args as the initial data.
- "next_token"
-
Used to passes a regular expression for a ``next version'' placeholder token.
See ``DEALING WITH ''NEXT VERSION`` PLACEHOLDERS'' for an example of its usage.
load( $filename, %args )
Parses $filename as per CPAN::Changes::Spec.
If present,
the optional %args are passed to the underlaying call to
"new()".
load_string( $string, %args )
Parses $string as per CPAN::Changes::Spec.
If present,
the optional %args are passed to the underlaying call to
"new()".
preamble( [ $preamble ] )
Gets/sets the preamble section.
releases( [ @releases ] )
Without any arguments, a list of current release objects is returned sorted
by ascending release date. When arguments are specified, all existing
releases are removed and replaced with the supplied information. Each release
may be either a regular hashref, or a CPAN::Changes::Release object.
# Hashref argument
$changes->releases( { version => '0.01', date => '2009-07-06' } );
# Release object argument
my $rel = CPAN::Changes::Release->new(
version => '0.01', date => '2009-07-06'
);
$changes->releases( $rel );
add_release( @releases )
Adds the release to the changes file. If a release at the same version exists,
it will be overwritten with the supplied data.
delete_release( @versions )
Deletes all of the releases specified by the versions supplied to the method.
release( $version )
Returns the release object for the specified version. Should there be no
matching release object, undef is returned.
serialize( reverse => $boolean, group_sort => \&sorting_function )
Returns all of the data as a string, suitable for saving as a Changes
file.
If reverse is provided and true, the releases are
printed in the reverse order (oldest to latest).
If group_sort is provided, change groups are
sorted according to the given function. If not,
groups are sorted alphabetically.
delete_empty_groups( )
Deletes change groups without changes in all releases.
DEALING WITH NEXT VERSION PLACEHOLDERS
In the working copy of a distribution, it's not uncommon
to have a ``next release'' placeholder section as the first entry
of the "Changes" file.
For example, the "Changes" file of a distribution using
Dist::Zilla and Dist::Zilla::Plugin::NextRelease
would look like:
Revision history for Foo-Bar
{{$NEXT}}
- Add the 'frobuscate' method.
1.0.0 2010-11-30
- Convert all comments to Esperanto.
0.0.1 2010-09-29
- Original version unleashed on an unsuspecting world
To have "CPAN::Changes" recognizes the "{{$NEXT}}" token as a valid
version, you can use the "next_token" argument with any of the class'
constructors. Note that the resulting release object will also
be considered the latest release, regardless of its timestamp.
To continue with our example:
# recognizes {{$NEXT}} as a version
my $changes = CPAN::Changes->load(
'Changes',
next_token => qr/{{\$NEXT}}/,
);
my @releases = $changes->releases;
print $releases[-1]->version; # prints '{{$NEXT}}'
SEE ALSO
- •
-
CPAN::Changes::Spec
- •
-
Test::CPAN::Changes
SIMILAR MODULES
- •
-
Module::Metadata::Changes
- •
-
Module::Changes
AUTHOR
Brian Cassidy <bricas@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2011-2013 by Brian Cassidy
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- METHODS
-
- new( %args )
-
- load( $filename, %args )
-
- load_string( $string, %args )
-
- preamble( [ $preamble ] )
-
- releases( [ @releases ] )
-
- add_release( @releases )
-
- delete_release( @versions )
-
- release( $version )
-
- serialize( reverse => $boolean, group_sort => \&sorting_function )
-
- delete_empty_groups( )
-
- DEALING WITH NEXT VERSION PLACEHOLDERS
-
- SEE ALSO
-
- SIMILAR MODULES
-
- AUTHOR
-
- COPYRIGHT AND LICENSE
-