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.

perl v5.32.0                                       2020-12-27                                 CPAN::Changes(3pm)