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, 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.
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 or instring are specified (see parse), 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!
Can be used to delete all information about errors ocurred during
previous parse runs. Note that parse() also calls this method.
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
String if a string was
parsed directly
NOTE: This format isn't stable yet and may change in later versions of this module.
Get the last non-parser error (e.g. the file to parse couldn't be opened).
Parses either the file named in configuration item infile or the string
saved in configuration item instring.
Accepts a hash ref as optional argument which can contain configuration
items.
Returns undef in case of error (e.g. "file not found", not parse
errors) and the object if successful. If undef was returned, you
can get the reason for the failure by calling the get_error method.
data 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".
(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:
dpkg_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".
See dpkg.
(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 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".
See rfc822.
(and xml_str)
xml converts the changelog to some free-form (i.e. there is neither
a DTD or a schema for it) XML.
The method xml_str is an alias for xml.
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):
See xml.
(and html_str)
html 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 html_str is an alias for html.
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):
style about default values)
See html.
not yet documented
not yet documented
not yet documented
The following options are supported by all output methods, all take a version number as value:
Causes changelog information from all versions strictly later than version to be used.
(works exactly like the -v option of dpkg-parsechangelog).
since but also includes the information for the
specified version itself.
until 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:
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.
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.
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