1CPAN::Changes(3)      User Contributed Perl Documentation     CPAN::Changes(3)
2
3
4

NAME

6       CPAN::Changes - Read and write Changes files
7

SYNOPSIS

9           # Load from file
10           my $changes = CPAN::Changes->load( 'Changes' );
11
12           # Create a new Changes file
13           $changes = CPAN::Changes->new(
14               preamble => 'Revision history for perl module Foo::Bar'
15           );
16
17           $changes->add_release( {
18               version => '0.01',
19               date    => '2009-07-06',
20           } );
21
22           $changes->serialize;
23

DESCRIPTION

25       It is standard practice to include a Changes file in your distribution.
26       The purpose the Changes file is to help a user figure out what has
27       changed since the last release.
28
29       People have devised many ways to write the Changes file. A preliminary
30       specification has been created (CPAN::Changes::Spec) to encourage
31       module authors to write clear and concise Changes.
32
33       This module will help users programmatically read and write Changes
34       files that conform to the specification.
35

METHODS

37   new( %args )
38       Creates a new object using %args as the initial data.
39
40       "next_token"
41           Used to passes a regular expression for a "next version"
42           placeholder token.  See "DEALING WITH "NEXT VERSION" PLACEHOLDERS"
43           for an example of its usage.
44
45   load( $filename, %args )
46       Parses $filename as per CPAN::Changes::Spec.  If present, the optional
47       %args are passed to the underlaying call to "new()".
48
49   load_string( $string, %args )
50       Parses $string as per CPAN::Changes::Spec.  If present, the optional
51       %args are passed to the underlaying call to "new()".
52
53   preamble( [ $preamble ] )
54       Gets/sets the preamble section.
55
56   releases( [ @releases ] )
57       Without any arguments, a list of current release objects is returned
58       sorted by ascending release date. When arguments are specified, all
59       existing releases are removed and replaced with the supplied
60       information. Each release may be either a regular hashref, or a
61       CPAN::Changes::Release object.
62
63           # Hashref argument
64           $changes->releases( { version => '0.01', date => '2009-07-06' } );
65
66           # Release object argument
67           my $rel = CPAN::Changes::Release->new(
68               version => '0.01', date => '2009-07-06
69           );
70           $changes->releases( $rel );
71
72   add_release( @releases )
73       Adds the release to the changes file. If a release at the same version
74       exists, it will be overwritten with the supplied data.
75
76   delete_release( @versions )
77       Deletes all of the releases specified by the versions supplied to the
78       method.
79
80   release( $version )
81       Returns the release object for the specified version. Should there be
82       no matching release object, undef is returned.
83
84   serialize( group_sort => \&sorting_function )
85       Returns all of the data as a string, suitable for saving as a Changes
86       file.
87
88       If group_sort is provided, change groups are sorted according to the
89       given function. If not, groups are sorted alphabetically.
90
91   delete_empty_groups( )
92       Deletes change groups without changes in all releases.
93

DEALING WITH "NEXT VERSION" PLACEHOLDERS

95       In the working copy of a distribution, it's not uncommon to have a
96       "next release" placeholder section as the first entry of the "Changes"
97       file.
98
99       For example, the "Changes" file of a distribution using Dist::Zilla and
100       Dist::Zilla::Plugin::NextRelease would look like:
101
102           Revision history for Foo-Bar
103
104           {{$NEXT}}
105               - Add the 'frobuscate' method.
106
107           1.0.0     2010-11-30
108               - Convert all comments to Esperanto.
109
110           0.0.1     2010-09-29
111               - Original version unleashed on an unsuspecting world
112
113       To have "CPAN::Changes" recognizes the "{{$NEXT}}" token as a valid
114       version, you can use the "next_token" argument with any of the class'
115       constructors. Note that the resulting release object will also be
116       considered the latest release, regardless of its timestamp.
117
118       To continue with our example:
119
120           # recognizes {{$NEXT}} as a version
121           my $changes = CPAN::Changes->load(
122               'Changes',
123               next_token => qr/{{\$NEXT}}/,
124           );
125
126           my @releases = $changes->releases;
127           print $releases[-1]->version;       # prints '{{$NEXT}}'
128

SEE ALSO

130       ·   CPAN::Changes::Spec
131
132       ·   Test::CPAN::Changes
133

AUTHOR

135       Brian Cassidy <bricas@cpan.org>
136

138       Copyright 2011 by Brian Cassidy
139
140       This library is free software; you can redistribute it and/or modify it
141       under the same terms as Perl itself.
142
143
144
145perl v5.12.3                      2011-04-20                  CPAN::Changes(3)
Impressum