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( reverse => $boolean, group_sort => \&sorting_function )
85       Returns all of the data as a string, suitable for saving as a Changes
86       file.
87
88       If reverse is provided and true, the releases are printed in the
89       reverse order (oldest to latest).
90
91       If group_sort is provided, change groups are sorted according to the
92       given function. If not, groups are sorted alphabetically.
93
94   delete_empty_groups( )
95       Deletes change groups without changes in all releases.
96

DEALING WITH "NEXT VERSION" PLACEHOLDERS

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

SEE ALSO

133       ·   CPAN::Changes::Spec
134
135       ·   Test::CPAN::Changes
136
137   SIMILAR MODULES
138       ·   Module::Metadata::Changes
139
140       ·   Module::Changes
141

AUTHOR

143       Brian Cassidy <bricas@cpan.org>
144

146       Copyright 2011-2013 by Brian Cassidy
147
148       This library is free software; you can redistribute it and/or modify it
149       under the same terms as Perl itself.
150
151
152
153perl v5.28.0                      2015-06-21                  CPAN::Changes(3)
Impressum