Dpkg::Deps: replace dump() method with output([$fh])

Update test suite accordingly as well as all scripts using Dpkg::Deps.
Also use overload to provide a string representation corresponding to
what's returned by output().

debian/changelog

@@ -2,6 +2,9 @@ dpkg (1.15.6) UNRELEASED; urgency=low
 
   [ Raphaël Hertzog ]
   * debian/control: Add the accent on my first name.
+  * Perl API cleanup:
+    - rename Dpkg::Deps dump() methods into output([$fh]), overload string
+      representation ("$dep") to provide the result of $dep->output()
 
   [ Guillem Jover ]
   * Handle argument parsing in dpkg-checkbuilddeps and dpkg-scanpackages

scripts/Dpkg/Deps.pm

@@ -378,9 +378,12 @@ an empty list of dependencies.
 Return a list of sub-dependencies. For Dpkg::Deps::Simple it returns
 itself.
 
-=item $dep->dump()
+=item $dep->output([$fh])
 
-Return a string representing the dependency.
+=item "$dep"
+
+Return a string representing the dependency. If $fh is set, it prints
+the string to the filehandle.
 
 =item $dep->implies($other_dep)
 
@@ -482,6 +485,8 @@ use Dpkg::Version;
 use Dpkg::ErrorHandling;
 use Dpkg::Gettext;
 
+use overload '""' => sub { $_[0]->output() };
+
 sub new {
     my ($this, $arg) = @_;
     my $class = ref($this) || $this;
@@ -524,8 +529,8 @@ sub parse {
     }
 }
 
-sub dump {
-    my $self = shift;
+sub output {
+    my ($self, $fh) = @_;
     my $res = $self->{package};
     if (defined($self->{relation})) {
 	$res .= " (" . $self->{relation} . " " . $self->{version} .  ")";
@@ -533,6 +538,9 @@ sub dump {
     if (defined($self->{'arches'})) {
 	$res .= " [" . join(" ", @{$self->{arches}}) . "]";
     }
+    if (defined($fh)) {
+	print $fh $res;
+    }
     return $res;
 }
 
@@ -751,6 +759,8 @@ use warnings;
 
 use Dpkg::ErrorHandling;
 
+use overload '""' => sub { $_[0]->output() };
+
 sub new {
     my $this = shift;
     my $class = ref($this) || $this;
@@ -813,9 +823,9 @@ time.
 
 =over 4
 
-=item $and->dump()
+=item $and->output([$fh])
 
-The dump method uses ", " to join the list of sub-dependencies.
+The output method uses ", " to join the list of sub-dependencies.
 
 =back
 
@@ -826,9 +836,13 @@ use warnings;
 
 our @ISA = qw(Dpkg::Deps::Multiple);
 
-sub dump {
-    my $self = shift;
-    return join(", ", map { $_->dump() } grep { not $_->is_empty() } $self->get_deps());
+sub output {
+    my ($self, $fh) = @_;
+    my $res = join(", ", map { $_->output() } grep { not $_->is_empty() } $self->get_deps());
+    if (defined($fh)) {
+	print $fh $res;
+    }
+    return $res;
 }
 
 sub implies {
@@ -914,9 +928,9 @@ for the dependency to be true.
 
 =over 4
 
-=item $or->dump()
+=item $or->output([$fh])
 
-The dump method uses " | " to join the list of sub-dependencies.
+The output method uses " | " to join the list of sub-dependencies.
 
 =back
 
@@ -927,9 +941,13 @@ use warnings;
 
 our @ISA = qw(Dpkg::Deps::Multiple);
 
-sub dump {
-    my $self = shift;
-    return join(" | ", map { $_->dump() } grep { not $_->is_empty() } $self->get_deps());
+sub output {
+    my ($self, $fh) = @_;
+    my $res = join(" | ", map { $_->output() } grep { not $_->is_empty() } $self->get_deps());
+    if (defined($fh)) {
+	print $fh $res;
+    }
+    return $res;
 }
 
 sub implies {
@@ -1007,9 +1025,9 @@ This object represents a list of relationships.
 
 =over 4
 
-=item $union->dump()
+=item $union->output([$fh])
 
-The dump method uses ", " to join the list of relationships.
+The output method uses ", " to join the list of relationships.
 
 =item $union->implies($other_dep)
 =item $union->get_evaluation($other_dep)
@@ -1030,9 +1048,13 @@ use warnings;
 
 our @ISA = qw(Dpkg::Deps::Multiple);
 
-sub dump {
-    my $self = shift;
-    return join(", ", map { $_->dump() } grep { not $_->is_empty() } $self->get_deps());
+sub output {
+    my ($self, $fh) = @_;
+    my $res = join(", ", map { $_->output() } grep { not $_->is_empty() } $self->get_deps());
+    if (defined($fh)) {
+	print $fh $res;
+    }
+    return $res;
 }
 
 sub implies {

scripts/dpkg-checkbuilddeps.pl

@@ -103,11 +103,11 @@ if ($bc_value) {
 
 if (@unmet) {
 	printf STDERR _g("%s: Unmet build dependencies: "), $progname;
-	print STDERR join(" ", map { $_->dump() } @unmet), "\n";
+	print STDERR join(" ", map { $_->output() } @unmet), "\n";
 }
 if (@conflicts) {
 	printf STDERR _g("%s: Build conflicts: "), $progname;
-	print STDERR join(" ", map { $_->dump() } @conflicts), "\n";
+	print STDERR join(" ", map { $_->output() } @conflicts), "\n";
 }
 exit 1 if @unmet || @conflicts;
 

scripts/dpkg-gencontrol.pl

@@ -254,7 +254,7 @@ foreach my $field (field_list_pkg_dep()) {
 	    $dep->simplify_deps($facts);
             $dep->sort();
 	}
-	$fields->{$field} = $dep->dump();
+	$fields->{$field} = $dep->output();
 	delete $fields->{$field} unless $fields->{$field}; # Delete empty field
     }
 }

scripts/dpkg-shlibdeps.pl

@@ -498,7 +498,7 @@ foreach my $field (reverse @depfields) {
         my $obj = Dpkg::Deps::parse($dep);
         error(_g("invalid dependency got generated: %s"), $dep) unless defined $obj;
         $obj->sort();
-	print $fh "$varnameprefix:$field=" . $obj->dump() . "\n";
+	print $fh "$varnameprefix:$field=$obj\n";
     }
 }
 

scripts/dpkg-source.pl

@@ -214,7 +214,7 @@ if ($options{'opmode'} =~ /^(-b|--print-format)$/) {
 	    my $facts = Dpkg::Deps::KnownFacts->new();
 	    $dep->simplify_deps($facts);
 	    $dep->sort() if $type eq 'union';
-	    $fields->{$_} = $dep->dump();
+	    $fields->{$_} = $dep->output();
 	} else {
             field_transfer_single($src_fields, $fields);
 	}

scripts/t/400_Dpkg_Deps.t

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-use Test::More tests => 16;
+use Test::More tests => 17;
 
 use strict;
 use warnings;
@@ -28,7 +28,7 @@ my $field_multiline_sorted = "libatk1.0-0 (>= 1.13.2), libc6 (>= 2.5-5), libcair
 
 my $dep_multiline = Dpkg::Deps::parse($field_multiline);
 $dep_multiline->sort();
-is($dep_multiline->dump(), $field_multiline_sorted, "Parse, sort and dump");
+is($dep_multiline->output(), $field_multiline_sorted, "Parse, sort and output");
 
 my $dep_subset = Dpkg::Deps::parse("libatk1.0-0 (>> 1.10), libc6, libcairo2");
 is($dep_multiline->implies($dep_subset), 1, "Dep implies subset of itself");
@@ -45,9 +45,9 @@ my $field_arch = "libc6 (>= 2.5) [!alpha !hurd-i386], libc6.1 [alpha], libc0.1 [
 my $dep_i386 = Dpkg::Deps::parse($field_arch, reduce_arch => 1, host_arch => 'i386');
 my $dep_alpha = Dpkg::Deps::parse($field_arch, reduce_arch => 1, host_arch => 'alpha');
 my $dep_hurd = Dpkg::Deps::parse($field_arch, reduce_arch => 1, host_arch => 'hurd-i386');
-is($dep_i386->dump(), "libc6 (>= 2.5)", "Arch reduce 1/3");
-is($dep_alpha->dump(), "libc6.1", "Arch reduce 2/3");
-is($dep_hurd->dump(), "libc0.1", "Arch reduce 3/3");
+is($dep_i386->output(), "libc6 (>= 2.5)", "Arch reduce 1/3");
+is($dep_alpha->output(), "libc6.1", "Arch reduce 2/3");
+is($dep_hurd->output(), "libc0.1", "Arch reduce 3/3");
 
 
 my $facts = Dpkg::Deps::KnownFacts->new();
@@ -58,23 +58,24 @@ my $field_duplicate = "libc6 (>= 2.3), libc6 (>= 2.6-1), mypackage (>=
 1.3), myvirtual | something, python (>= 2.5)";
 my $dep_dup = Dpkg::Deps::parse($field_duplicate);
 $dep_dup->simplify_deps($facts, $dep_opposite);
-is($dep_dup->dump(), "libc6 (>= 2.6-1)", "Simplify deps");
+is($dep_dup->output(), "libc6 (>= 2.6-1)", "Simplify deps");
 
 my $field_dup_union = "libc6 (>> 2.3), libc6 (>= 2.6-1), fake (<< 2.0),
 fake(>> 3.0), fake (= 2.5), python (<< 2.5), python (= 2.4)";
 my $dep_dup_union = Dpkg::Deps::parse($field_dup_union, union => 1);
 $dep_dup_union->simplify_deps($facts);
-is($dep_dup_union->dump(), "libc6 (>> 2.3), fake (<< 2.0), fake (>> 3.0), fake (= 2.5), python (<< 2.5)", "Simplify union deps");
+is($dep_dup_union->output(), "libc6 (>> 2.3), fake (<< 2.0), fake (>> 3.0), fake (= 2.5), python (<< 2.5)", "Simplify union deps");
 
 my $dep_red = Dpkg::Deps::parse("abc | xyz, two, abc");
 $dep_red->simplify_deps($facts, $dep_opposite);
-is($dep_red->dump(), "abc, two", "Simplification respect order");
+is($dep_red->output(), "abc, two", "Simplification respect order");
+is("$dep_red", $dep_red->output(), "Stringification == output()");
 
 my $dep_empty1 = Dpkg::Deps::parse("");
-is($dep_empty1->dump(), "", "Empty dependency");
+is($dep_empty1->output(), "", "Empty dependency");
 
 my $dep_empty2 = Dpkg::Deps::parse(" , , ", union => 1);
-is($dep_empty2->dump(), "", "' , , ' is also an empty dependency");
+is($dep_empty2->output(), "", "' , , ' is also an empty dependency");
 
 $SIG{'__WARN__'} = sub {};
 my $dep_bad_multiline = Dpkg::Deps::parse("a, foo\nbar, c");