GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CPAN::CHANGES (3)

.ds Aq ’

NAME

CPAN::Changes - Read and write Changes files

CONTENTS

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( CW%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( CW$filename, CW%args )

Parses $filename as per CPAN::Changes::Spec. If present, the optional %args are passed to the underlaying call to new().

load_string( CW$string, CW%args )

Parses $string as per CPAN::Changes::Spec. If present, the optional %args are passed to the underlaying call to new().

preamble( [ CW$preamble ] )

Gets/sets the preamble section.

releases( [ CW@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( CW@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( CW@versions )

Deletes all of the releases specified by the versions supplied to the method.

release( CW$version )

Returns the release object for the specified version. Should there be no matching release object, undef is returned.

serialize( reverse => CW$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

o CPAN::Changes::Spec
o Test::CPAN::Changes

    SIMILAR MODULES

o Module::Metadata::Changes
o 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CPAN::CHANGES (3) 2015-05-23

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.