.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Changes 3pm" .TH CPAN::Changes 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Changes \- Read and write Changes files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Load from file \& my $changes = CPAN::Changes\->load( \*(AqChanges\*(Aq ); \& \& # Create a new Changes file \& $changes = CPAN::Changes\->new( \& preamble => \*(AqRevision history for perl module Foo::Bar\*(Aq \& ); \& \& $changes\->add_release( { \& version => \*(Aq0.01\*(Aq, \& date => \*(Aq2009\-07\-06\*(Aq, \& } ); \& \& $changes\->serialize; .Ve .SH "DESCRIPTION" .IX Header "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. .PP 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. .PP This module will help users programmatically read and write Changes files that conform to the specification. .SH "METHODS" .IX Header "METHODS" .ie n .SS "new( %args )" .el .SS "new( \f(CW%args\fP )" .IX Subsection "new( %args )" Creates a new object using \f(CW%args\fR as the initial data. .ie n .IP """next_token""" 4 .el .IP "\f(CWnext_token\fR" 4 .IX Item "next_token" Used to passes a regular expression for a \*(L"next version\*(R" placeholder token. See \*(L"\s-1DEALING WITH \*(R"NEXT VERSION\*(L" PLACEHOLDERS\*(R"\s0 for an example of its usage. .ie n .SS "load( $filename, %args )" .el .SS "load( \f(CW$filename\fP, \f(CW%args\fP )" .IX Subsection "load( $filename, %args )" Parses \f(CW$filename\fR as per CPAN::Changes::Spec. If present, the optional \f(CW%args\fR are passed to the underlaying call to \&\f(CW\*(C`new()\*(C'\fR. .ie n .SS "load_string( $string, %args )" .el .SS "load_string( \f(CW$string\fP, \f(CW%args\fP )" .IX Subsection "load_string( $string, %args )" Parses \f(CW$string\fR as per CPAN::Changes::Spec. If present, the optional \f(CW%args\fR are passed to the underlaying call to \&\f(CW\*(C`new()\*(C'\fR. .ie n .SS "preamble( [ $preamble ] )" .el .SS "preamble( [ \f(CW$preamble\fP ] )" .IX Subsection "preamble( [ $preamble ] )" Gets/sets the preamble section. .ie n .SS "releases( [ @releases ] )" .el .SS "releases( [ \f(CW@releases\fP ] )" .IX Subsection "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. .PP .Vb 2 \& # Hashref argument \& $changes\->releases( { version => \*(Aq0.01\*(Aq, date => \*(Aq2009\-07\-06\*(Aq } ); \& \& # Release object argument \& my $rel = CPAN::Changes::Release\->new( \& version => \*(Aq0.01\*(Aq, date => \*(Aq2009\-07\-06\*(Aq \& ); \& $changes\->releases( $rel ); .Ve .ie n .SS "add_release( @releases )" .el .SS "add_release( \f(CW@releases\fP )" .IX Subsection "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. .ie n .SS "delete_release( @versions )" .el .SS "delete_release( \f(CW@versions\fP )" .IX Subsection "delete_release( @versions )" Deletes all of the releases specified by the versions supplied to the method. .ie n .SS "release( $version )" .el .SS "release( \f(CW$version\fP )" .IX Subsection "release( $version )" Returns the release object for the specified version. Should there be no matching release object, undef is returned. .ie n .SS "serialize( reverse => $boolean, group_sort => \e&sorting_function )" .el .SS "serialize( reverse => \f(CW$boolean\fP, group_sort => \e&sorting_function )" .IX Subsection "serialize( reverse => $boolean, group_sort => &sorting_function )" Returns all of the data as a string, suitable for saving as a Changes file. .PP If \fIreverse\fR is provided and true, the releases are printed in the reverse order (oldest to latest). .PP If \fIgroup_sort\fR is provided, change groups are sorted according to the given function. If not, groups are sorted alphabetically. .SS "delete_empty_groups( )" .IX Subsection "delete_empty_groups( )" Deletes change groups without changes in all releases. .ie n .SH "DEALING WITH ""NEXT VERSION"" PLACEHOLDERS" .el .SH "DEALING WITH ``NEXT VERSION'' PLACEHOLDERS" .IX Header "DEALING WITH NEXT VERSION PLACEHOLDERS" In the working copy of a distribution, it's not uncommon to have a \*(L"next release\*(R" placeholder section as the first entry of the \f(CW\*(C`Changes\*(C'\fR file. .PP For example, the \f(CW\*(C`Changes\*(C'\fR file of a distribution using Dist::Zilla and Dist::Zilla::Plugin::NextRelease would look like: .PP .Vb 1 \& Revision history for Foo\-Bar \& \& {{$NEXT}} \& \- Add the \*(Aqfrobuscate\*(Aq 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 .Ve .PP To have \f(CW\*(C`CPAN::Changes\*(C'\fR recognizes the \f(CW\*(C`{{$NEXT}}\*(C'\fR token as a valid version, you can use the \f(CW\*(C`next_token\*(C'\fR argument with any of the class' constructors. Note that the resulting release object will also be considered the latest release, regardless of its timestamp. .PP To continue with our example: .PP .Vb 5 \& # recognizes {{$NEXT}} as a version \& my $changes = CPAN::Changes\->load( \& \*(AqChanges\*(Aq, \& next_token => qr/{{\e$NEXT}}/, \& ); \& \& my @releases = $changes\->releases; \& print $releases[\-1]\->version; # prints \*(Aq{{$NEXT}}\*(Aq .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 CPAN::Changes::Spec .IP "\(bu" 4 Test::CPAN::Changes .SS "\s-1SIMILAR MODULES\s0" .IX Subsection "SIMILAR MODULES" .IP "\(bu" 4 Module::Metadata::Changes .IP "\(bu" 4 Module::Changes .SH "AUTHOR" .IX Header "AUTHOR" Brian Cassidy .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2011\-2013 by Brian Cassidy .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.