Dpkg::Changelog: Add new format_range() method

Deprecate dpkg() and rfc822() methods by this new method, which has a
more clear name and generic interface.

debian/changelog

@@ -5,6 +5,8 @@ dpkg (1.18.8) UNRELEASED; urgency=medium
     Thanks to Steven Chamberlain <steven@pyro.eu.org>.
   * Perl modules:
     - Use warnings::warnif() instead of carp() for deprecated warnings.
+    - Add new format_range() method and deprecate dpkg() and rfc822() methods
+      in Dpkg::Changelog.
   * Test suite:
     - Bump perlcritic ValuesAndExpressions::RequireNumberSeparators minimum
       to 99999.

scripts/Dpkg/Changelog.pm

@@ -34,7 +34,9 @@ package Dpkg::Changelog;
 use strict;
 use warnings;
 
-our $VERSION = '1.00';
+our $VERSION = '1.01';
+
+use Carp;
 
 use Dpkg::Gettext;
 use Dpkg::ErrorHandling qw(:DEFAULT report REPORT_WARN);
@@ -473,52 +475,6 @@ sub output {
     return $str;
 }
 
-=item $control = $c->dpkg($range)
-
-Returns a Dpkg::Control::Changelog object representing the entries selected
-by the optional range specifier (see L<"RANGE SELECTION"> for details).
-Returns undef in no entries are matched.
-
-The following fields are contained in the object:
-
-=over 4
-
-=item Source
-
-package name (in the first entry)
-
-=item Version
-
-packages' version (from first entry)
-
-=item Distribution
-
-target distribution (from first entry)
-
-=item Urgency
-
-urgency (highest of all printed entries)
-
-=item Maintainer
-
-person that created the (first) entry
-
-=item Date
-
-date of the (first) entry
-
-=item Closes
-
-bugs closed by the entry/entries, sorted by bug number
-
-=item Changes
-
-content of the the entry/entries
-
-=back
-
-=cut
-
 our ( @URGENCIES, %URGENCIES );
 BEGIN {
     @URGENCIES = qw(low medium high critical emergency);
@@ -526,7 +482,7 @@ BEGIN {
     %URGENCIES = map { $_ => $i++ } @URGENCIES;
 }
 
-sub dpkg {
+sub _format_dpkg {
     my ($self, $range) = @_;
 
     my @data = $self->get_range($range) or return;
@@ -580,21 +536,11 @@ sub dpkg {
     return $f;
 }
 
-=item @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<"RANGE SELECTION"> for details). For the format of
-such an object see the description of the L<"dpkg"> method (while ignoring
-the remarks about which values are taken from the first entry).
-
-=cut
-
-sub rfc822 {
+sub _format_rfc822 {
     my ($self, $range) = @_;
 
     my @data = $self->get_range($range) or return;
-    my $index = Dpkg::Index->new(type => CTRL_CHANGELOG);
+    my @ctrl;
 
     foreach my $entry (@data) {
 	my $f = Dpkg::Control::Changelog->new();
@@ -614,9 +560,125 @@ sub rfc822 {
 
         run_vendor_hook('post-process-changelog-entry', $f);
 
-	$index->add($f);
+        push @ctrl, $f;
+    }
+
+    return @ctrl;
+}
+
+=item $control = $c->format_range($format, $range)
+
+Formats the changelog into Dpkg::Control::Changelog objects representing the
+entries selected by the optional range specifier (see L<"RANGE SELECTION">
+for details). In scalar context returns a Dpkg::Index object containing the
+selected entries, in list context returns an array of Dpkg::Control::Changelog
+objects.
+
+With format B<dpkg> the returned Dpkg::Control::Changelog object is coalesced
+from the entries in the changelog that are part of the range requested,
+with the fields described below, but considering that "selected entry"
+means the first entry of the selected range.
+
+With format B<rfc822> each returned Dpkg::Control::Changelog objects
+represents one entry in the changelog that is part of the range requested,
+with the fields described below, but considering that "selected entry"
+means for each entry.
+
+The different formats return undef if no entries are matched. The following
+fields are contained in the object(s) returned:
+
+=over 4
+
+=item Source
+
+package name (selected entry)
+
+=item Version
+
+packages' version (selected entry)
+
+=item Distribution
+
+target distribution (selected entry)
+
+=item Urgency
+
+urgency (highest of all entries in range)
+
+=item Maintainer
+
+person that created the (selected) entry
+
+=item Date
+
+date of the (selected) entry
+
+=item Closes
+
+bugs closed by the (selected) entry/entries, sorted by bug number
+
+=item Changes
+
+content of the the (selected) entry/entries
+
+=back
+
+=cut
+
+sub format_range {
+    my ($self, $format, $range) = @_;
+
+    my @ctrl;
+
+    if ($format eq 'dpkg') {
+        @ctrl = $self->_format_dpkg($range);
+    } elsif ($format eq 'rfc822') {
+        @ctrl = $self->_format_rfc822($range);
+    } else {
+        croak "unknown changelog output format $format";
+    }
+
+    if (wantarray) {
+        return @ctrl;
+    } else {
+        my $index = Dpkg::Index->new(type => CTRL_CHANGELOG);
+
+        foreach my $f (@ctrl) {
+            $index->add($f);
+        }
+
+        return $index;
     }
-    return $index;
+}
+
+=item $control = $c->dpkg($range)
+
+This is a deprecated alias for $c->format_range('dpkg', $range).
+
+=cut
+
+sub dpkg {
+    my ($self, $range) = @_;
+
+    warnings::warnif('deprecated',
+                     'deprecated method, please use format_range("dpkg", $range) instead');
+
+    return $self->format_range('dpkg', $range);
+}
+
+=item @controls = $c->rfc822($range)
+
+This is a deprecated alias for C<scalar c->format_range('rfc822', $range)>.
+
+=cut
+
+sub rfc822 {
+    my ($self, $range) = @_;
+
+    warnings::warnif('deprecated',
+                     'deprecated method, please use format_range("rfc822", $range) instead');
+
+    return scalar $self->format_range('rfc822', $range);
 }
 
 =back
@@ -698,6 +760,12 @@ with only one of the options specified.
 
 =head1 CHANGES
 
+=head2 Version 1.01 (dpkg 1.18.8)
+
+New method: $c->format_range().
+
+Deprecated methods: $c->dpkg(), $c->rfc822().
+
 =head2 Version 1.00 (dpkg 1.15.6)
 
 Mark the module as public.

scripts/Dpkg/Changelog/Parse.pm

@@ -95,9 +95,9 @@ sub changelog_parse_debian {
     # Get the output into several Dpkg::Control objects.
     my @res;
     if ($options{format} eq 'dpkg') {
-        push @res, $changes->dpkg($range);
+        push @res, $changes->format_range('dpkg', $range);
     } elsif ($options{format} eq 'rfc822') {
-        push @res, $changes->rfc822($range)->get();
+        push @res, $changes->format_range('rfc822', $range);
     } else {
         error(g_('unknown output format %s'), $options{format});
     }

scripts/changelog/debian.pl

@@ -134,10 +134,5 @@ my $changes = Dpkg::Changelog::Debian->new(reportfile => $label, range => $range
 $changes->load($file)
     or error(g_('fatal error occurred while parsing %s'), $file);
 
-eval qq{
-    my \$output = \$changes->$format(\$range);
-    print \$output if defined \$output;
-};
-if ($@) {
-    error('%s', $@);
-}
+my $entries = $changes->format_range($format, $range);
+print $entries if defined $entries;

scripts/t/Dpkg_Changelog.t

@@ -166,7 +166,7 @@ foreach my $file ("$datadir/countme", "$datadir/shadow", "$datadir/fields",
 	#TODO: test combinations
     }
     if ($file eq "$datadir/fields") {
-	my $str = $changes->dpkg({ all => 1 });
+	my $str = $changes->format_range('dpkg', { all => 1 });
 	my $expected = 'Source: fields
 Version: 2.0-0etch1
 Distribution: stable
@@ -201,13 +201,14 @@ Changes:
    * First upload (Closes: #1000000)
 Xb-Userfield2: foobar
 Xc-Userfield: foobar
+
 ';
 	if ($vendor eq 'Ubuntu') {
 	    $expected =~ s/^(Closes:.*)/$1\nLaunchpad-Bugs-Fixed: 12345 54321 424242 2424242/m;
 	}
 	cmp_ok($str, 'eq', $expected, 'fields handling');
 
-	$str = $changes->dpkg({ offset => 1, count => 2 });
+	$str = $changes->format_range('dpkg', { offset => 1, count => 2 });
 	$expected = 'Source: fields
 Version: 2.0-1
 Distribution: unstable frozen
@@ -232,13 +233,14 @@ Changes:
  .
    * Beta
 Xc-Userfield: foobar
+
 ';
 	if ($vendor eq 'Ubuntu') {
 	    $expected =~ s/^(Closes:.*)/$1\nLaunchpad-Bugs-Fixed: 12345 424242/m;
 	}
 	cmp_ok($str, 'eq', $expected, 'fields handling 2');
 
-	$str = $changes->rfc822({ offset => 2, count => 2 });
+	$str = $changes->format_range('rfc822', { offset => 2, count => 2 });
 	$expected = 'Source: fields
 Version: 2.0~b1-1
 Distribution: unstable
@@ -297,7 +299,7 @@ Xb-Userfield2: foobar
            'get date w/ DoW, and zero timezone offset');
     }
     if ($file eq "$datadir/regressions") {
-	my $f = $changes->dpkg();
+	my $f = ($changes->format_range('dpkg'))[0];
 	is("$f->{Version}", '0', 'version 0 correctly parsed');
     }
 
@@ -306,13 +308,13 @@ Xb-Userfield2: foobar
 	    if @data == 1;
 
 	my $oldest_version = $data[-1]->{Version};
-	$str = $changes->dpkg({ since => $oldest_version });
+	$str = $changes->format_range('dpkg', { since => $oldest_version });
 
-	$str = $changes->rfc822();
+	$str = $changes->format_range('rfc822');
 
 	ok(1, 'TODO check rfc822 output');
 
-	$str = $changes->rfc822({ since => $oldest_version });
+	$str = $changes->format_range('rfc822', { since => $oldest_version });
 
 	ok(1, 'TODO check rfc822 output with ranges');
     }