.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-03-02 "perl v5.38.2" "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 \- Parser for CPAN style change logs
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use CPAN::Changes;
\&  my $changes = CPAN::Changes\->load(\*(AqChanges\*(Aq);
\&  $changes\->release(\*(Aq0.01\*(Aq);
.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 \fBCPAN::Changes\fR object.
.PP
\fR\f(CI%args\fR\fI\fR
.IX Subsection "%args"
.IP preamble 4
.IX Item "preamble"
The preamble section of the changelog.
.IP releases 4
.IX Item "releases"
An arrayref of CPAN::Changes::Release objects.
.ie n .SS "load ( $filename, %args )"
.el .SS "load ( \f(CW$filename\fP, \f(CW%args\fP )"
.IX Subsection "load ( $filename, %args )"
Creates a new \fBCPAN::Changes\fR object by parsing the given file via
CPAN::Changes::Parser.
.ie n .SS "load_string ( $filename, %args )"
.el .SS "load_string ( \f(CW$filename\fP, \f(CW%args\fP )"
.IX Subsection "load_string ( $filename, %args )"
Creates a new \fBCPAN::Changes\fR object by parsing the given string via
CPAN::Changes::Parser.
.ie n .SS "preamble ( [ $preamble ] )"
.el .SS "preamble ( [ \f(CW$preamble\fP ] )"
.IX Subsection "preamble ( [ $preamble ] )"
Gets or sets the preamble section.
.ie n .SS "releases ( [ @releases ] )"
.el .SS "releases ( [ \f(CW@releases\fP ] )"
.IX Subsection "releases ( [ @releases ] )"
Gets or sets the list of releases as CPAN::Changes::Release objects.
.ie n .SS "add_release ( @releases )"
.el .SS "add_release ( \f(CW@releases\fP )"
.IX Subsection "add_release ( @releases )"
Adds the given releases to the change log.  If a release of the same version
exists, it will be overwritten.
.ie n .SS "delete_release ( @versions )"
.el .SS "delete_release ( \f(CW@versions\fP )"
.IX Subsection "delete_release ( @versions )"
Removes the given versions from change log.
.ie n .SS "find_release ( $version )"
.el .SS "find_release ( \f(CW$version\fP )"
.IX Subsection "find_release ( $version )"
Finds a release with the given version.
.SS reversed
.IX Subsection "reversed"
Returns a new \fBCPAN::Changes\fR object with the releases in the opposite order.
.ie n .SS "clone ( %attrs )"
.el .SS "clone ( \f(CW%attrs\fP )"
.IX Subsection "clone ( %attrs )"
Returns a new \f(CW\*(C`CPAN::Changes\*(C'\fR object with the given attributes changed.
.ie n .SS "serialize ( %options )"
.el .SS "serialize ( \f(CW%options\fP )"
.IX Subsection "serialize ( %options )"
Returns the change log as a string suitable for saving as a \fIChanges\fR file.
.IP width 4
.IX Item "width"
The width to wrap lines at.  By default, lines will be wrapped at 75 characters.
.IP styles 4
.IX Item "styles"
An array reference of styles to use when outputting the entries, one for each
level of change. The first entry is used for the release entry itself.
.Sp
The styles can be either a single character to prefix change lines or two
characters to use as a prefix and suffix.
.IP indents 4
.IX Item "indents"
An array reference of indent strings to use when outputting the entries.
.IP "reverse (legacy)" 4
.IX Item "reverse (legacy)"
If true, releases will be output in reversed order.
.IP "group_sort (legacy)" 4
.IX Item "group_sort (legacy)"
A code reference used to sort the groups in the releases.
.SH "LEGACY METHODS"
.IX Header "LEGACY METHODS"
.SS delete_empty_groups
.IX Subsection "delete_empty_groups"
Removes empty groups.
.SS release
.IX Subsection "release"
An alias for find_release.
.SH AUTHOR
.IX Header "AUTHOR"
haarg \- Graham Knop (cpan:HAARG) <haarg@haarg.org>
.SH CONTRIBUTORS
.IX Header "CONTRIBUTORS"
Brian Cassidy <bricas@cpan.org>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2011\-2015 the CPAN::Changes "AUTHOR" and "CONTRIBUTORS"
as listed above.
.SH LICENSE
.IX Header "LICENSE"
This library is free software and may be distributed under the same terms
as perl itself. See <http://dev.perl.org/licenses/>.