Dpkg::Deps: cleanup API

Rename public functions with deps_ prefix. Export them by default.

Update all scripts using Dpkg::Deps accordingly, including the test-suite.

debian/changelog

@@ -5,6 +5,8 @@ dpkg (1.15.6) UNRELEASED; urgency=low
   * Perl API cleanup:
     - rename Dpkg::Deps dump() methods into output([$fh]), overload string
       representation ("$dep") to provide the result of $dep->output()
+    - prefix public functions in Dpkg::Deps with deps_ and export them
+      by default
 
   [ Guillem Jover ]
   * Handle argument parsing in dpkg-checkbuilddeps and dpkg-scanpackages

scripts/Dpkg/Deps.pm

@@ -29,12 +29,16 @@ Dpkg::Deps - parse and manipulate dependencies of Debian packages
 
 =head1 DESCRIPTION
 
-The Dpkg::Deps module provides one generic Dpkg::Deps::parse() function
-to turn a dependency line in a set of Dpkg::Deps::{Simple,AND,OR,Union}
-objects depending on the case.
+The Dpkg::Deps module provides objects implementing various types of
+dependencies.
+
+The most important function is deps_parse(), it turns a dependency line in
+a set of Dpkg::Deps::{Simple,AND,OR,Union} objects depending on the case.
 
 =head1 FUNCTIONS
 
+All the deps_* functions are exported by default.
+
 =over 4
 
 =cut
@@ -48,29 +52,17 @@ use Dpkg::ErrorHandling;
 use Dpkg::Gettext;
 
 use base qw(Exporter);
-our @EXPORT_OK = qw(%relation_ordering);
-
-# Some generic variables
-our %relation_ordering = (
-	'undef' => 0,
-	'>=' => 1,
-	'>>' => 2,
-	'=' => 3,
-	'<<' => 4,
-	'<=' => 5,
-);
+our @EXPORT = qw(deps_parse deps_eval_implication deps_compare);
 
 # Some factorized function
 
-=item Dpkg::Deps::arch_is_superset(\@p, \@q)
-
-Returns true if the arch list @p is a superset of arch list @q.
-The arguments can also be undef in case there's no explicit architecture
-restriction.
-
-=cut
+# Dpkg::Deps::_arch_is_superset(\@p, \@q)
+#
+# Returns true if the arch list @p is a superset of arch list @q.
+# The arguments can also be undef in case there's no explicit architecture
+# restriction.
 
-sub arch_is_superset {
+sub _arch_is_superset {
     my ($p, $q) = @_;
     my $p_arch_neg = defined($p) && $p->[0] =~ /^!/;
     my $q_arch_neg = defined($q) && $q->[0] =~ /^!/;
@@ -129,11 +121,11 @@ sub arch_is_superset {
     return 1;
 }
 
-=item Dpkg::Deps::version_implies($rel_p, $v_p, $rel_q, $v_q)
+=item deps_eval_implication($rel_p, $v_p, $rel_q, $v_q)
 
 ($rel_p, $v_p) and ($rel_q, $v_q) express two dependencies as (relation,
-version). The relation variable can have the following values: '=', '<<',
-'<=', '>=', '>>'.
+version). The relation variable can have the following values that are
+exported by Dpkg::Version: REL_EQ, REL_LT, REL_LE, REL_GT, REL_GT.
 
 This functions returns 1 if the "p" dependency implies the "q"
 dependency. It returns 0 if the "p" dependency implies that "q" is
@@ -143,25 +135,25 @@ The $v_p and $v_q parameter should be Dpkg::Version objects.
 
 =cut
 
-sub version_implies {
+sub deps_eval_implication {
     my ($rel_p, $v_p, $rel_q, $v_q) = @_;
 
     # If versions are not valid, we can't decide of any implication
-    return undef unless ref($v_p) and $v_p->isa("Dpkg::Version");
-    return undef unless ref($v_q) and $v_q->isa("Dpkg::Version");
+    return undef unless defined($v_p) and $v_p->is_valid();
+    return undef unless defined($v_q) and $v_q->is_valid();
 
     # q wants an exact version, so p must provide that exact version.  p
     # disproves q if q's version is outside the range enforced by p.
-    if ($rel_q eq '=') {
-        if ($rel_p eq '<<') {
+    if ($rel_q eq REL_EQ) {
+        if ($rel_p eq REL_LT) {
             return ($v_p <= $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '<=') {
+        } elsif ($rel_p eq REL_LE) {
             return ($v_p < $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '>>') {
+        } elsif ($rel_p eq REL_GT) {
             return ($v_p >= $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '>=') {
+        } elsif ($rel_p eq REL_GE) {
             return ($v_p > $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '=') {
+        } elsif ($rel_p eq REL_EQ) {
             return ($v_p == $v_q);
         }
     }
@@ -169,12 +161,12 @@ sub version_implies {
     # A greater than clause may disprove a less than clause. An equal
     # cause might as well.  Otherwise, if
     # p's clause is <<, <=, or =, the version must be <= q's to imply q.
-    if ($rel_q eq '<=') {
-        if ($rel_p eq '>>') {
+    if ($rel_q eq REL_LE) {
+        if ($rel_p eq REL_GT) {
             return ($v_p >= $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '>=') {
+        } elsif ($rel_p eq REL_GE) {
             return ($v_p > $v_q) ? 0 : undef;
-	} elsif ($rel_p eq '=') {
+	} elsif ($rel_p eq REL_EQ) {
             return ($v_p <= $v_q) ? 1 : 0;
         } else { # <<, <=
             return ($v_p <= $v_q) ? 1 : undef;
@@ -183,12 +175,12 @@ sub version_implies {
 
     # Similar, but << is stronger than <= so p's version must be << q's
     # version if the p relation is <= or =.
-    if ($rel_q eq '<<') {
-        if ($rel_p eq '>>' or $rel_p eq '>=') {
+    if ($rel_q eq REL_LT) {
+        if ($rel_p eq REL_GT or $rel_p eq REL_GE) {
             return ($v_p >= $v_p) ? 0 : undef;
-        } elsif ($rel_p eq '<<') {
+        } elsif ($rel_p eq REL_LT) {
             return ($v_p <= $v_q) ? 1 : undef;
-	} elsif ($rel_p eq '=') {
+	} elsif ($rel_p eq REL_EQ) {
             return ($v_p < $v_q) ? 1 : 0;
         } else { # <<, <=
             return ($v_p < $v_q) ? 1 : undef;
@@ -196,23 +188,23 @@ sub version_implies {
     }
 
     # Same logic as above, only inverted.
-    if ($rel_q eq '>=') {
-        if ($rel_p eq '<<') {
+    if ($rel_q eq REL_GE) {
+        if ($rel_p eq REL_LT) {
             return ($v_p <= $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '<=') {
+        } elsif ($rel_p eq REL_LE) {
             return ($v_p < $v_q) ? 0 : undef;
-	} elsif ($rel_p eq '=') {
+	} elsif ($rel_p eq REL_EQ) {
             return ($v_p >= $v_q) ? 1 : 0;
         } else { # >>, >=
             return ($v_p >= $v_q) ? 1 : undef;
         }
     }
-    if ($rel_q eq '>>') {
-        if ($rel_p eq '<<' or $rel_p eq '<=') {
+    if ($rel_q eq REL_GT) {
+        if ($rel_p eq REL_LT or $rel_p eq REL_LE) {
             return ($v_p <= $v_q) ? 0 : undef;
-        } elsif ($rel_p eq '>>') {
+        } elsif ($rel_p eq REL_GT) {
             return ($v_p >= $v_q) ? 1 : undef;
-	} elsif ($rel_p eq '=') {
+	} elsif ($rel_p eq REL_EQ) {
             return ($v_p > $v_q) ? 1 : 0;
         } else {
             return ($v_p > $v_q) ? 1 : undef;
@@ -222,7 +214,7 @@ sub version_implies {
     return undef;
 }
 
-=item Dpkg::Deps::parse($line, %options)
+=item my $dep = deps_parse($line, %options)
 
 This function parse the dependency line and returns an object, either a
 Dpkg::Deps::AND or a Dpkg::Deps::Union. Various options can alter the
@@ -257,7 +249,7 @@ this when parsing non-dependency fields like Conflicts.
 
 =cut
 
-sub parse {
+sub deps_parse {
     my $dep_line = shift;
     my %options = (@_);
     $options{use_arch} = 1 if not exists $options{use_arch};
@@ -310,16 +302,25 @@ sub parse {
     return $dep_and;
 }
 
-=item Dpkg::Deps::compare($a, $b)
+=item deps_compare($a, $b)
 
-This functions is used to order AND and Union dependencies prior to
-dumping.
+Implements a comparison operator between two dependency objects.
+This function is mainly used to implement the sort() method.
 
 =back
 
 =cut
 
-sub compare {
+our %relation_ordering = (
+	'undef' => 0,
+	REL_GE => 1,
+	REL_GT => 2,
+	REL_EQ => 3,
+	REL_LT => 4,
+	REL_LE => 5,
+);
+
+sub deps_compare {
     my ($a, $b) = @_;
     return -1 if $a->is_empty();
     return 1 if $b->is_empty();
@@ -555,7 +556,7 @@ sub implies {
 
 	# Our architecture set must be a superset of the architectures for
 	# o, otherwise we can't conclude anything.
-	return undef unless Dpkg::Deps::arch_is_superset($self->{arches}, $o->{arches});
+	return undef unless Dpkg::Deps::_arch_is_superset($self->{arches}, $o->{arches});
 
 	# If o has no version clause, then our dependency is stronger
 	return 1 if not defined $o->{relation};
@@ -563,8 +564,8 @@ sub implies {
 	# can't be an implication
 	return undef if not defined $self->{relation};
 
-	return Dpkg::Deps::version_implies($self->{relation}, $self->{version},
-		$o->{relation}, $o->{version});
+	return Dpkg::Deps::deps_eval_implication($self->{relation},
+		$self->{version}, $o->{relation}, $o->{version});
 
     } elsif ($o->isa('Dpkg::Deps::AND')) {
 	# TRUE: Need to imply all individual elements
@@ -782,7 +783,7 @@ sub get_deps {
 sub sort {
     my $self = shift;
     my @res = ();
-    @res = sort { Dpkg::Deps::compare($a, $b) } @{$self->{list}};
+    @res = sort { Dpkg::Deps::deps_compare($a, $b) } @{$self->{list}};
     $self->{list} = [ @res ];
 }
 

scripts/dpkg-checkbuilddeps.pl

@@ -94,11 +94,11 @@ my (@unmet, @conflicts);
 
 if ($bd_value) {
 	push @unmet, build_depends('Build-Depends/Build-Depends-Indep)',
-		Dpkg::Deps::parse($bd_value, reduce_arch => 1), $facts);
+		deps_parse($bd_value, reduce_arch => 1), $facts);
 }
 if ($bc_value) {
 	push @conflicts, build_conflicts('Build-Conflicts/Build-Conflicts-Indep',
-		Dpkg::Deps::parse($bc_value, reduce_arch => 1, union => 1), $facts);
+		deps_parse($bc_value, reduce_arch => 1, union => 1), $facts);
 }
 
 if (@unmet) {
@@ -126,8 +126,7 @@ sub parse_status {
 		$facts->add_installed_package($package, $version);
 	
 		if (/^Provides: (.*)$/m) {
-			my $provides = Dpkg::Deps::parse($1,
-                            reduce_arch => 1, union => 1);
+			my $provides = deps_parse($1, reduce_arch => 1, union => 1);
 			next if not defined $provides;
 			foreach (grep { $_->isa('Dpkg::Deps::Simple') }
                                  $provides->get_deps())

scripts/dpkg-gencontrol.pl

@@ -220,8 +220,8 @@ $fields->{'Version'} = $forceversion if defined($forceversion);
 my $facts = Dpkg::Deps::KnownFacts->new();
 $facts->add_installed_package($fields->{'Package'}, $fields->{'Version'});
 if (exists $pkg->{"Provides"}) {
-    my $provides = Dpkg::Deps::parse($substvars->substvars($pkg->{"Provides"}),
-                                     reduce_arch => 1, union => 1);
+    my $provides = deps_parse($substvars->substvars($pkg->{"Provides"}),
+                              reduce_arch => 1, union => 1);
     if (defined $provides) {
 	foreach my $subdep ($provides->get_deps()) {
 	    if ($subdep->isa('Dpkg::Deps::Simple')) {
@@ -239,16 +239,15 @@ foreach my $field (field_list_pkg_dep()) {
 	my $dep;
 	my $field_value = $substvars->substvars($pkg->{$field});
 	if (field_get_dep_type($field) eq 'normal') {
-	    $dep = Dpkg::Deps::parse($field_value, use_arch => 1,
-                                     reduce_arch => 1);
+	    $dep = deps_parse($field_value, use_arch => 1, reduce_arch => 1);
 	    error(_g("error occurred while parsing %s field: %s"), $field,
                   $field_value) unless defined $dep;
 	    $dep->simplify_deps($facts, @seen_deps);
 	    # Remember normal deps to simplify even further weaker deps
 	    push @seen_deps, $dep;
 	} else {
-	    $dep = Dpkg::Deps::parse($field_value, use_arch => 1,
-                                     reduce_arch => 1, union => 1);
+	    $dep = deps_parse($field_value, use_arch => 1,
+                              reduce_arch => 1, union => 1);
 	    error(_g("error occurred while parsing %s field: %s"), $field,
                   $field_value) unless defined $dep;
 	    $dep->simplify_deps($facts);

scripts/dpkg-shlibdeps.pl

@@ -134,7 +134,7 @@ my $control = Dpkg::Control::Info->new();
 my $fields = $control->get_source();
 my $build_depends = defined($fields->{"Build-Depends"}) ?
 		    $fields->{"Build-Depends"} : "";
-my $build_deps = Dpkg::Deps::parse($build_depends, reduce_arch => 1);
+my $build_deps = deps_parse($build_depends, reduce_arch => 1);
 
 my %dependencies;
 my %shlibs;
@@ -495,7 +495,7 @@ foreach my $field (reverse @depfields) {
 	    keys %{$dependencies{$field}};
     }
     if ($dep) {
-        my $obj = Dpkg::Deps::parse($dep);
+        my $obj = deps_parse($dep);
         error(_g("invalid dependency got generated: %s"), $dep) unless defined $obj;
         $obj->sort();
 	print $fh "$varnameprefix:$field=$obj\n";
@@ -564,8 +564,8 @@ sub get_min_version_from_deps {
     if ($dep->isa('Dpkg::Deps::Simple')) {
 	if (($dep->{package} eq $pkg) &&
 	    defined($dep->{relation}) &&
-	    (($dep->{relation} eq ">=") ||
-	     ($dep->{relation} eq ">>")))
+	    (($dep->{relation} eq REL_GE) ||
+	     ($dep->{relation} eq REL_GT)))
 	{
 	    return $dep->{version};
 	}

scripts/dpkg-source.pl

@@ -209,7 +209,7 @@ if ($options{'opmode'} =~ /^(-b|--print-format)$/) {
 	} elsif (m/^Build-(Depends|Conflicts)(-Indep)?$/i) {
 	    my $dep;
 	    my $type = field_get_dep_type($_);
-	    $dep = Dpkg::Deps::parse($v, union => $type eq 'union');
+	    $dep = deps_parse($v, union => $type eq 'union');
 	    error(_g("error occurred while parsing %s"), $_) unless defined $dep;
 	    my $facts = Dpkg::Deps::KnownFacts->new();
 	    $dep->simplify_deps($facts);

scripts/t/400_Dpkg_Deps.t

@@ -26,25 +26,25 @@ libfontconfig1 (>= 2.4.0), libglib2.0-0  (  >= 2.12.9), libgnutls13 (>=
 1.6.3-0), libjpeg62, python (<< 2.5) , , ";
 my $field_multiline_sorted = "libatk1.0-0 (>= 1.13.2), libc6 (>= 2.5-5), libcairo2 (>= 1.4.0), libcupsys2 (>= 1.2.7), libfontconfig1 (>= 2.4.0), libglib2.0-0 (>= 2.12.9), libgnutls13 (>= 1.6.3-0), libgtk2.0-common (= 2.10.13-1), libjpeg62, python (<< 2.5)";
 
-my $dep_multiline = Dpkg::Deps::parse($field_multiline);
+my $dep_multiline = deps_parse($field_multiline);
 $dep_multiline->sort();
 is($dep_multiline->output(), $field_multiline_sorted, "Parse, sort and output");
 
-my $dep_subset = Dpkg::Deps::parse("libatk1.0-0 (>> 1.10), libc6, libcairo2");
+my $dep_subset = deps_parse("libatk1.0-0 (>> 1.10), libc6, libcairo2");
 is($dep_multiline->implies($dep_subset), 1, "Dep implies subset of itself");
 is($dep_subset->implies($dep_multiline), undef, "Subset doesn't imply superset");
-my $dep_opposite = Dpkg::Deps::parse("python (>= 2.5)");
+my $dep_opposite = deps_parse("python (>= 2.5)");
 is($dep_opposite->implies($dep_multiline), 0, "Opposite condition implies NOT the depends");
 
-my $dep_or1 = Dpkg::Deps::parse("a|b (>=1.0)|c (>= 2.0)");
-my $dep_or2 = Dpkg::Deps::parse("x|y|a|b|c (<= 0.5)|c (>=1.5)|d|e");
+my $dep_or1 = deps_parse("a|b (>=1.0)|c (>= 2.0)");
+my $dep_or2 = deps_parse("x|y|a|b|c (<= 0.5)|c (>=1.5)|d|e");
 is($dep_or1->implies($dep_or2), 1, "Implication between OR 1/2");
 is($dep_or2->implies($dep_or1), undef, "Implication between OR 2/2");
 
 my $field_arch = "libc6 (>= 2.5) [!alpha !hurd-i386], libc6.1 [alpha], libc0.1 [hurd-i386]";
-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');
+my $dep_i386 = deps_parse($field_arch, reduce_arch => 1, host_arch => 'i386');
+my $dep_alpha = deps_parse($field_arch, reduce_arch => 1, host_arch => 'alpha');
+my $dep_hurd = deps_parse($field_arch, reduce_arch => 1, host_arch => 'hurd-i386');
 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");
@@ -56,29 +56,29 @@ $facts->add_provided_package("myvirtual", undef, undef, "mypackage");
 
 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);
+my $dep_dup = deps_parse($field_duplicate);
 $dep_dup->simplify_deps($facts, $dep_opposite);
 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);
+my $dep_dup_union = deps_parse($field_dup_union, union => 1);
 $dep_dup_union->simplify_deps($facts);
 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");
+my $dep_red = deps_parse("abc | xyz, two, abc");
 $dep_red->simplify_deps($facts, $dep_opposite);
 is($dep_red->output(), "abc, two", "Simplification respect order");
 is("$dep_red", $dep_red->output(), "Stringification == output()");
 
-my $dep_empty1 = Dpkg::Deps::parse("");
+my $dep_empty1 = deps_parse("");
 is($dep_empty1->output(), "", "Empty dependency");
 
-my $dep_empty2 = Dpkg::Deps::parse(" , , ", union => 1);
+my $dep_empty2 = deps_parse(" , , ", union => 1);
 is($dep_empty2->output(), "", "' , , ' is also an empty dependency");
 
 $SIG{'__WARN__'} = sub {};
-my $dep_bad_multiline = Dpkg::Deps::parse("a, foo\nbar, c");
+my $dep_bad_multiline = deps_parse("a, foo\nbar, c");
 ok(!defined($dep_bad_multiline), "invalid dependency split over multiple line");
 delete $SIG{'__WARN__'};