Parse::DebianChangelog - parse Debian changelogs and output them in other formats

    use Parse::DebianChangelog;

    my $chglog = Parse::DebianChangelog->init( { infile => 'debian/changelog',
                                                 HTML => { outfile => 'changelog.html' } );
    $chglog->html;

    # the following is semantically equivalent
    my $chglog = Parse::DebianChangelog->init();
    $chglog->parse( { infile => 'debian/changelog' } );
    $chglog->html( { outfile => 'changelog.html' } );

    my $changes = $chglog->dpkg_str( { since => '1.0-1' } );
    print $changes;

Parse::DebianChangelog parses Debian changelogs as described in the Debian policy (version 3.6.2.1 at the time of this writing). See section SEE ALSO for locations where to find this definition.

The parser tries to ignore most cruft like # or /* */ style comments, CVS comments, vim variables, emacs local variables and stuff from older changelogs with other formats at the end of the file. NOTE: most of these are ignored silently currently, there is no parser error issued for them. This should become configurable in the future.

Beside giving access to the details of the parsed file via the data method, Parse::DebianChangelog also supports converting these changelogs to various other formats. These are currently:

dpkg

Format as known from dpkg-parsechangelog(1). All requested entries (see METHODS for an explanation what this means) are returned in the usual Debian control format, merged in one stanza, ready to be used in a .changes file.

rfc822

Similar to the CWdpkg format, but the requested entries are returned as one stanza each, i.e. they are not merged. This is probably the format to use if you want a machine-usable representation of the changelog.

xml

Just a simple XML dump of the changelog data. Without any schema or DTD currently, just some made up XML. The actual format might still change. Comments and Improvements welcome.

html

The changelog is converted to a somewhat nice looking HTML file with some nice features as a quick-link bar with direct links to every entry. NOTE: This is not very configurable yet and was specifically designed to be used on <http://packages.debian.org/>. This is planned to be changed until version 1.0.

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

If CWinfile or CWinstring are specified (see parse), CWparse() is called from CWinit. If a fatal error is encountered during parsing (e.g. the file can't be opened), CWinit will not return a valid object but CWundef!

reset_parse_errors

Can be used to delete all information about errors ocurred during previous parse runs. Note that CWparse() 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 CWString if a string was parsed directly

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

parse

Parses either the file named in configuration item CWinfile or the string saved in configuration item CWinstring. Accepts a hash ref as optional argument which can contain configuration items.

Returns CWundef in case of error (e.g. file not found, not parse errors) and the object if successful. If CWundef was returned, you can get the reason for the failure by calling the get_error method.

data

CWdata returns an array (if called in list context) or a reference to an array of Parse::DebianChangelog::Entry objects which each represent one entry of the changelog.

This is currently merely a placeholder to enable users to get to the raw data, expect changes to this API in the near future.

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

dpkg

(and dpkg_str)

CWdpkg 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

CWdpkg_str returns a stringified version of this hash which should look exactly like the output of dpkg-parsechangelog(1). The fields are ordered like in the list above.

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

dpkg_str

See dpkg.

rfc822

(and rfc822_str)

CWrfc822 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).

CWrfc822_str returns a stringified version of this hash which looks similar to the output of dpkg-parsechangelog but instead of one stanza the output contains one stanza for each entry.

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

rfc822_str

See rfc822.

xml

(and xml_str)

CWxml converts the changelog to some free-form (i.e. there is neither a DTD or a schema for it) XML.

The method CWxml_str is an alias for CWxml.

Both methods support the common output options described in section COMMON OUTPUT OPTIONS and additionally the following configuration options (as usual to give in a hash reference as parameter to the method call):

outfile

directly write the output to the file specified

xml_str

See xml.

html

(and html_str)

CWhtml converts the changelog to a HTML file with some nice features such as a quick-link bar with direct links to every entry. The HTML is generated with the help of HTML::Template. If you want to change the output you should use the default template provided with this module as a base and read the documentation of HTML::Template to understand how to edit it.

The method CWhtml_str is an alias for CWhtml.

Both methods support the common output options described in section COMMON OUTPUT OPTIONS and additionally the following configuration options (as usual to give in a hash reference as parameter to the method call):

outfile

directly write the output to the file specified

template

template file to use, defaults to /usr/share/libparse-debianchangelog-perl/default.tmpl. NOTE: The plan is to provide a configuration file for the module later to be able to use sane defaults here.

style

path to the CSS stylesheet to use (a default might be specified in the template and will be honoured, see the default template for an example)

print_style

path to the CSS stylesheet to use for printing (see the notes for CWstyle about default values)

html_str

See html.

init_filters

not yet documented

apply_filters

not yet documented

add_filter, delete_filter, replace_filter

not yet documented

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. (works exactly like the CW-v option of dpkg-parsechangelog).

until

Causes changelog information from all versions strictly earlier than version to be used.

from

Similar to CWsince but also includes the information for the specified version itself.

to

Similar to CWuntil but also includes the information for the specified version itself.

The following options 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. While the XML and HTML formats default to all == true, this does of course not overwrite other options unless it is set explicitly with the call.

count

Expects a signed integer as value. Returns CWvalue entries from the top of the changelog if set to a positive integer, and CWabs(value) entries from the tail if set to a negative integer.

offset

Expects a signed integer as value. Changes the starting point for CWcount, either counted from the top (positive integer) or from the tail (negative integer). CWoffset has no effect if CWcount 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 CWsince and CWfrom and one of CWuntil and CWto returns the intersection of the two results with only one of the options specified.

Parse::DebianChangelog::Entry, Parse::DebianChangelog::ChangesFilters

Description of the Debian changelog format in the Debian policy: <http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog>.

Frank Lichtenheld, <frank@lichtenheld.de>

Copyright (C) 2005 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