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.