NAME

Dpkg::Changelog

DESCRIPTION

to be written

Functions

init

Creates a new object instance. Takes a reference to a hash as optional argument, which is interpreted as configuration options. There are currently no supported general configuration options, but see the other methods for more specific configuration options which can also specified to init.

If infile, inhandle, or instring are specified, parse() is called from init. If a fatal error is encountered during parsing (e.g. the file can't be opened), init will not return a valid object but undef!

reset_parse_errors

Can be used to delete all information about errors ocurred during previous parse runs. Note that parse() also calls this method.

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

1.
the filename of the parsed file or FileHandle or String if the input came from a file handle or a string. If the reportfile configuration option was given, its value will be used instead
2.
the line number where the error occurred
3.
an error description
4.
the original line

NOTE: This format isn't stable yet and may change in later versions of this module.

get_error

Get the last non-parser error (e.g. the file to parse couldn't be opened).

data

data 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.

This method supports the common output options described in section "COMMON OUTPUT OPTIONS".

dpkg

(and dpkg_str)

dpkg returns a hash (in list context) or a hash reference (in scalar context) where the keys are field names and the values are field values. The following fields are given:

Source
package name (in the first entry)
Version
packages' version (from first entry)
Distribution
target distribution (from first entry)
Urgency
urgency (highest of all printed entries)
Maintainer
person that created the (first) entry
Date
date of the (first) entry
Closes
bugs closed by the entry/entries, sorted by bug number
Changes
content of the the entry/entries

dpkg_str returns a stringified version of this hash. The fields are ordered like in the list above.

Both methods support the common output options described in section "COMMON OUTPUT OPTIONS".

dpkg_str

See dpkg.

rfc822

(and rfc822_str)

rfc822 returns an array of hashes (in list context) or a reference to this array (in scalar context) where each hash represents one entry in the changelog. For the format of such a hash see the description of the "dpkg" method (while ignoring the remarks about which values are taken from the first entry).

rfc822_str returns a stringified version of this array.

Both methods support the common output options described in section "COMMON OUTPUT OPTIONS".

rfc822_str

See rfc822.

COMMON OUTPUT OPTIONS

The following options are supported by all output methods, all take a version number as value:

since
Causes changelog information from all versions strictly later than version to be used.
until
Causes changelog information from all versions strictly earlier than version to be used.
from
Similar to since but also includes the information for the specified version itself.
to
Similar to until but also includes the information for the specified version itself.

The following options are also supported by all output methods but don't take version numbers as values:

all
If set to a true value, all entries of the changelog are returned, this overrides all other options.
count
Expects a signed integer as value. Returns value entries from the top of the changelog if set to a positive integer, and abs(value) entries from the tail if set to a negative integer.
offset
Expects a signed integer as value. Changes the starting point for count, either counted from the top (positive integer) or from the tail (negative integer). offset has no effect if count wasn't given as well.

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. 

            Call                               Included entries
 C<E<lt>formatE<gt>({ since =E<gt> '2.0' })>  3.1, 3.0, 2.2
 C<E<lt>formatE<gt>({ until =E<gt> '2.0' })>  1.3, 1.2
 C<E<lt>formatE<gt>({ from =E<gt> '2.0' })>   3.1, 3.0, 2.2, 2.1, 2.0
 C<E<lt>formatE<gt>({ to =E<gt> '2.0' })>     2.0, 1.3, 1.2
 C<E<lt>formatE<gt>({ count =E<gt> 2 }>>      3.1, 3.0
 C<E<lt>formatE<gt>({ count =E<gt> -2 }>>     1.3, 1.2
 C<E<lt>formatE<gt>({ count =E<gt> 3,
		      offset=E<gt> 2 }>>      2.2, 2.1, 2.0
 C<E<lt>formatE<gt>({ count =E<gt> 2,
		      offset=E<gt> -3 }>>     2.0, 1.3
 C<E<lt>formatE<gt>({ count =E<gt> -2,
		      offset=E<gt> 3 }>>      3.0, 2.2
 C<E<lt>formatE<gt>({ count =E<gt> -2,
		      offset=E<gt> -3 }>>     2.2, 2.1

Any combination of one option of since and from and one of until and to returns the intersection of the two results with only one of the options specified.

UTILITY FUNCTIONS

find_closes

Takes one string as argument and finds "Closes: #123456, #654321" statements as supported by the Debian Archive software in it. Returns all closed bug numbers in an array reference.

data2rfc822

Takes a single argument, either a Dpkg::Changelog::Entry object or a reference to an array of such objects.

Returns the data in RFC822 format as string.

get_dpkg_changes

Takes a Dpkg::Changelog::Entry object as first argument.

Returns a string that is suitable for using it in a Changes field in the output format of dpkg-parsechangelog.

my $fields = parse_changelog(%opt)

This function will parse a changelog. In list context, it return as many Dpkg::Fields::Object as the parser did output. In scalar context, it will return only the first one. If the parser didn't return any data, it will return an empty in list context or undef on scalar context. If the parser failed, it will die.

The parsing itself is done by an external program (searched in the following list of directories: $opt{libdir}, /usr/local/lib/dpkg/parsechangelog, /usr/lib/dpkg/parsechangelog) That program is named according to the format that it's able to parse. By default it's either "debian" or the format name lookep up in the 40 last lines of the changelog itself (extracted with this perl regular expression "\schangelog-format:\s+([0-9a-z]+)\W"). But it can be overriden with $opt{changelogformat}. The program expects the content of the changelog file on its standard input.

The changelog file that is parsed is debian/changelog by default but it can be overriden with $opt{file}.

All the other keys in %opt are forwarded as parameter to the external parser. If the key starts with "-", it's passed as is. If not, it's passed as "--<key>". If the value of the corresponding hash entry is defined, then it's passed as the parameter that follows.

NAME

Dpkg::Changelog::Entry - represents one entry in a Debian changelog

SYNOPSIS

DESCRIPTION

AUTHOR

Frank Lichtenheld, <frank@lichtenheld.de>

COPYRIGHT AND LICENSE

Copyright © 2005, 2007 by Frank Lichtenheld

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA