.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Dpkg::Changelog 3"
.TH Dpkg::Changelog 3 "2016-03-26" "1.16.18" "libdpkg-perl"
.\" 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"
Dpkg::Changelog \- base class to implement a changelog parser
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Dpkg::Changelog is a class representing a changelog file
as an array of changelog entries (Dpkg::Changelog::Entry).
By deriving this object and implementing its parse method, you
add the ability to fill this object with changelog entries.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
.ie n .IP "my $c = Dpkg::Changelog\->new(%options)" 4
.el .IP "my \f(CW$c\fR = Dpkg::Changelog\->new(%options)" 4
.IX Item "my $c = Dpkg::Changelog->new(%options)"
Creates a new changelog object.
.ie n .IP "$c\->load($filename)" 4
.el .IP "\f(CW$c\fR\->load($filename)" 4
.IX Item "$c->load($filename)"
Parse \f(CW$filename\fR as a changelog.
.ie n .IP "$c\->set_options(%opts)" 4
.el .IP "\f(CW$c\fR\->set_options(%opts)" 4
.IX Item "$c->set_options(%opts)"
Change the value of some options. \*(L"verbose\*(R" (defaults to 1) defines
whether parse errors are displayed as warnings by default. \*(L"reportfile\*(R"
is a string to use instead of the name of the file parsed, in particular
in error messages. \*(L"range\*(R" defines the range of entries that we want to
parse, the parser will stop as soon as it has parsed enough data to
satisfy \f(CW$c\fR\->get_range($opts{'range'}).
.ie n .IP "$c\->\fIreset_parse_errors()\fR" 4
.el .IP "\f(CW$c\fR\->\fIreset_parse_errors()\fR" 4
.IX Item "$c->reset_parse_errors()"
Can be used to delete all information about errors occurred during
previous parse runs.
.ie n .IP "$c\->parse_error($line_nr, $error, [$line])" 4
.el .IP "\f(CW$c\fR\->parse_error($line_nr, \f(CW$error\fR, [$line])" 4
.IX Item "$c->parse_error($line_nr, $error, [$line])"
Record a new parse error at line \f(CW$line_nr\fR. The error message is specified
with \f(CW$error\fR and a copy of the line can be recorded in \f(CW$line\fR.
.ie n .IP "$c\->\fIget_parse_errors()\fR" 4
.el .IP "\f(CW$c\fR\->\fIget_parse_errors()\fR" 4
.IX Item "$c->get_parse_errors()"
Returns all error messages from the last parse run.
If called in scalar context returns a human readable
string representation. If called in list context returns
an array of arrays. Each of these arrays contains
.RS 4
.IP "1." 4
a string describing the origin of the data (a filename usually). If the
reportfile configuration option was given, its value will be used instead.
.IP "2." 4
the line number where the error occurred
.IP "3." 4
an error description
.IP "4." 4
the original line
.RE
.RS 4
.RE
.ie n .IP "$c\->set_unparsed_tail($tail)" 4
.el .IP "\f(CW$c\fR\->set_unparsed_tail($tail)" 4
.IX Item "$c->set_unparsed_tail($tail)"
Add a string representing unparsed lines after the changelog entries.
Use undef as \f(CW$tail\fR to remove the unparsed lines currently set.
.ie n .IP "$c\->\fIget_unparsed_tail()\fR" 4
.el .IP "\f(CW$c\fR\->\fIget_unparsed_tail()\fR" 4
.IX Item "$c->get_unparsed_tail()"
Return a string representing the unparsed lines after the changelog
entries. Returns undef if there's no such thing.
.IP "@{$c}" 4
.IX Item "@{$c}"
Returns all the Dpkg::Changelog::Entry objects contained in this changelog
in the order in which they have been parsed.
.ie n .IP "$c\->get_range($range)" 4
.el .IP "\f(CW$c\fR\->get_range($range)" 4
.IX Item "$c->get_range($range)"
Returns an array (if called in list context) or a reference to an array of
Dpkg::Changelog::Entry objects which each represent one entry of the
changelog. \f(CW$range\fR is a hash reference describing the range of entries
to return. See section \*(L"\s-1RANGE\s0 \s-1SELECTION\s0\*(R".
.ie n .IP "$c\->\fIabort_early()\fR" 4
.el .IP "\f(CW$c\fR\->\fIabort_early()\fR" 4
.IX Item "$c->abort_early()"
Returns true if enough data have been parsed to be able to return all
entries selected by the range set at creation (or with set_options).
.ie n .IP "$c\->save($filename)" 4
.el .IP "\f(CW$c\fR\->save($filename)" 4
.IX Item "$c->save($filename)"
Save the changelog in the given file.
.ie n .IP "$c\->\fIoutput()\fR" 4
.el .IP "\f(CW$c\fR\->\fIoutput()\fR" 4
.IX Item "$c->output()"
.PD 0
.ie n .IP """$c""" 4
.el .IP "``$c''" 4
.IX Item "$c"
.PD
Returns a string representation of the changelog (it's a concatenation of
the string representation of the individual changelog entries).
.ie n .IP "$c\->output($fh)" 4
.el .IP "\f(CW$c\fR\->output($fh)" 4
.IX Item "$c->output($fh)"
Output the changelog to the given filehandle.
.ie n .IP "my $control = $c\->dpkg($range)" 4
.el .IP "my \f(CW$control\fR = \f(CW$c\fR\->dpkg($range)" 4
.IX Item "my $control = $c->dpkg($range)"
Returns a Dpkg::Control::Changelog object representing the entries selected
by the optional range specifier (see \*(L"\s-1RANGE\s0 \s-1SELECTION\s0\*(R" for details).
Returns undef in no entries are matched.
.Sp
The following fields are contained in the object:
.RS 4
.IP "Source" 4
.IX Item "Source"
package name (in the first entry)
.IP "Version" 4
.IX Item "Version"
packages' version (from first entry)
.IP "Distribution" 4
.IX Item "Distribution"
target distribution (from first entry)
.IP "Urgency" 4
.IX Item "Urgency"
urgency (highest of all printed entries)
.IP "Maintainer" 4
.IX Item "Maintainer"
person that created the (first) entry
.IP "Date" 4
.IX Item "Date"
date of the (first) entry
.IP "Closes" 4
.IX Item "Closes"
bugs closed by the entry/entries, sorted by bug number
.IP "Changes" 4
.IX Item "Changes"
content of the the entry/entries
.RE
.RS 4
.RE
.ie n .IP "my @controls = $c\->rfc822($range)" 4
.el .IP "my \f(CW@controls\fR = \f(CW$c\fR\->rfc822($range)" 4
.IX Item "my @controls = $c->rfc822($range)"
Returns a Dpkg::Index containing Dpkg::Control::Changelog objects where
each object represents one entry in the changelog that is part of the
range requested (see \*(L"\s-1RANGE\s0 \s-1SELECTION\s0\*(R" for details). For the format of
such an object see the description of the \*(L"dpkg\*(R" method (while ignoring
the remarks about which values are taken from the first entry).
.SH "RANGE SELECTION"
.IX Header "RANGE SELECTION"
A range selection is described by a hash reference where
the allowed keys and values are described below.
.PP
The following options take a version number as value.
.IP "since" 4
.IX Item "since"
Causes changelog information from all versions strictly
later than \fBversion\fR to be used.
.IP "until" 4
.IX Item "until"
Causes changelog information from all versions strictly
earlier than \fBversion\fR to be used.
.IP "from" 4
.IX Item "from"
Similar to \f(CW\*(C`since\*(C'\fR but also includes the information for the
specified \fBversion\fR itself.
.IP "to" 4
.IX Item "to"
Similar to \f(CW\*(C`until\*(C'\fR but also includes the information for the
specified \fBversion\fR itself.
.PP
The following options don't take version numbers as values:
.IP "all" 4
.IX Item "all"
If set to a true value, all entries of the changelog are returned,
this overrides all other options.
.IP "count" 4
.IX Item "count"
Expects a signed integer as value. Returns \f(CW\*(C`value\*(C'\fR entries from the
top of the changelog if set to a positive integer, and \f(CW\*(C`abs(value)\*(C'\fR
entries from the tail if set to a negative integer.
.IP "offset" 4
.IX Item "offset"
Expects a signed integer as value. Changes the starting point for
\&\f(CW\*(C`count\*(C'\fR, either counted from the top (positive integer) or from
the tail (negative integer). \f(CW\*(C`offset\*(C'\fR has no effect if \f(CW\*(C`count\*(C'\fR
wasn't given as well.
.PP
Some examples for the above options. Imagine an example changelog with
entries for the versions 1.2, 1.3, 2.0, 2.1, 2.2, 3.0 and 3.1.
.PP
.Vb 11
\&            Range                           Included entries
\& C<{ since =E<gt> \*(Aq2.0\*(Aq }>                  3.1, 3.0, 2.2
\& C<{ until =E<gt> \*(Aq2.0\*(Aq }>                  1.3, 1.2
\& C<{ from =E<gt> \*(Aq2.0\*(Aq }>                   3.1, 3.0, 2.2, 2.1, 2.0
\& C<{ to =E<gt> \*(Aq2.0\*(Aq }>                     2.0, 1.3, 1.2
\& C<{ count =E<gt> 2 }>                      3.1, 3.0
\& C<{ count =E<gt> \-2 }>                     1.3, 1.2
\& C<{ count =E<gt> 3, offset=E<gt> 2 }>      2.2, 2.1, 2.0
\& C<{ count =E<gt> 2, offset=E<gt> \-3 }>     2.0, 1.3
\& C<{ count =E<gt> \-2, offset=E<gt> 3 }>     3.0, 2.2
\& C<{ count =E<gt> \-2, offset=E<gt> \-3 }>    2.2, 2.1
.Ve
.PP
Any combination of one option of \f(CW\*(C`since\*(C'\fR and \f(CW\*(C`from\*(C'\fR and one of
\&\f(CW\*(C`until\*(C'\fR and \f(CW\*(C`to\*(C'\fR returns the intersection of the two results
with only one of the options specified.
.SH "AUTHOR"
.IX Header "AUTHOR"
Frank Lichtenheld, <frank@lichtenheld.de>
Raphaël Hertzog, <hertzog@debian.org>