Use pkg for the Debbugs::Package and package for the name

 - Add documentation to Debbugs::Version
 - Debbugs::Version objects should not be created directly

diff --git a/Debbugs/Package.pm b/Debbugs/Package.pm
index 3ba411adfbabc41f8f3099851be429cb74b06e9b..70f0e35832d828bc290816d039c663746cc4692f 100644 (file)
--- a/Debbugs/Package.pm
+++ b/Debbugs/Package.pm
@@ -655,7 +655,7 @@ sub _create_version {
            push @versions,
                $v,
                Debbugs::Version::Source->
-                   new(package => $self,
+                   new(pkg => $self,
                        version => $v,
                        package_collection => $self->package_collection,
                         $self->schema_argument,
@@ -666,7 +666,7 @@ sub _create_version {
            push @versions,
                $v,
                Debbugs::Version::Binary->
-                   new(package => $self,
+                   new(pkg => $self,
                        version => $v,
                        package_collection => $self->package_collection,
                         $self->schema_argument,

diff --git a/Debbugs/Version.pm b/Debbugs/Version.pm
index 34fdd0e2e9f6e28a7447909b7cdebcdbc948b67f..71dc0085894d7f79bf382c42631c0271c7d7bf4b 100644 (file)
--- a/Debbugs/Version.pm
+++ b/Debbugs/Version.pm
@@ -12,8 +12,11 @@ Debbugs::Version -- OO interface to Version
 
 =head1 SYNOPSIS
 
+This package provides a convenient interface to refer to package versions and
+potentially make calculations based upon them
+
    use Debbugs::Version;
-   Debbugs::Version->new(schema => $s,binaries => [qw(foo)],sources => [qw(bar)]);
+   my $v = Debbugs::Version->new(schema => $s,binaries => [qw(foo)],sources => [qw(bar)]);
 
 =head1 DESCRIPTION
 
@@ -33,65 +36,167 @@ use Carp;
 
 extends 'Debbugs::OOBase';
 
-state $strong_severities =
-   {map {($_,1)} @{$config{strong_severities}}};
+=head1 Object Creation
 
-has version => (is => 'ro', isa => 'Str',
-               required => 1,
-               builder => '_build_version',
-               predicate => '_has_version',
-              );
+=head2 my $version = Debbugs::Version::Source->new(%params|$param)
 
-sub type {
-    confess("Subclass must define type");
-}
+or C<Debbugs::Version::Binary->new(%params|$param)> for a binary version
 
-has package => (is => 'bare',
-                isa => 'Debbugs::Package',
-                lazy => 1,
-                builder => '_build_package',
-               );
+=over
+
+=item schema
+
+L<Debbugs::DB> schema which can be used to look up versions
+
+=item package
+
+String representation of the package
+
+=item pkg
+
+L<Debbugs::Package> which refers to the package given.
+
+Only one of C<package> or C<pkg> should be given
+
+=item package_collection
+
+L<Debbugs::Collection::Package> which is used to generate a L<Debbugs::Package>
+object from the package name
+
+=back
+
+=cut
 
 around BUILDARGS => sub {
     my $orig = shift;
     my $class = shift;
+    if ($class eq __PACKAGE__) {
+        confess("You should not be instantiating Debbugs::Version. ".
+                "Use Debbugs::Version::Source or ::Binary");
+    }
     my %args;
     if (@_==1 and ref($_[0]) eq 'HASH') {
        %args = %{$_[0]};
     } else {
         %args = @_;
     }
-    carp("No schema") unless exists $args{schema};
-    if (exists $args{package} and
-        not blessed($args{package})) {
-        # OK, need a package Collection
-        my $pkgc = $args{package_collection} //
-            Debbugs::Collection::Package->
-                new(exists $args{schema}?(schema => $args{schema}):());
-        $args{package} =
-            $pkgc->universe->get_or_add_by_key($args{package});
-    }
     return $class->$orig(%args);
 };
 
 
+
+state $strong_severities =
+   {map {($_,1)} @{$config{strong_severities}}};
+
+=head1 Methods
+
+=head2 version
+
+     $version->version
+
+Returns the source or binary package version
+
+=cut
+
+has version => (is => 'ro', isa => 'Str',
+               required => 1,
+               builder => '_build_version',
+               predicate => '_has_version',
+              );
+
+=head2 type
+
+Returns 'source' if this is a source version, or 'binary' if this is a binary
+version.
+
+=cut
+
+=head2 source_version
+
+Returns the source version for this version; if this is a source version,
+returns itself.
+
+=cut
+
+=head2 src_pkg_ver
+
+Returns the fully qualified source_package/version string for this version.
+
+=cut
+
+=head2 package
+
+Returns the name of the package that this version is in
+
+=cut
+
+has package => (is => 'ro',
+                isa => 'Str',
+                builder => '_build_package',
+                predicate => '_has_package',
+                lazy => 1,
+               );
+
 sub _build_package {
     my $self = shift;
-    return Debbugs::Package->new(package => '(unknown)',
+    if ($self->_has_pkg) {
+        return $self->pkg->name;
+    }
+    return '(unknown)';
+}
+
+=head2 pkg
+
+Returns a L<Debbugs::Package> object corresponding to C<package>.
+
+=cut
+
+
+has pkg => (is => 'ro',
+            isa => 'Debbugs::Package',
+            lazy => 1,
+            builder => '_build_pkg',
+            reader => 'pkg',
+            predicate => '_has_pkg',
+           );
+
+sub _build_pkg {
+    my $self = shift;
+    return Debbugs::Package->new(package => $self->package,
                                  type => $self->type,
                                  valid => 0,
                                  package_collection => $self->package_collection,
-                                 $self->has_schema?(schema => $self->schema):(),
+                                 $self->schema_argument,
                                 );
 }
 
 
+=head2 valid
+
+Returns 1 if this package is valid, 0 otherwise.
+
+=cut
+
 has valid => (is => 'ro',
              isa => 'Bool',
-             default => 0,
              reader => 'is_valid',
+              lazy => 1,
+              builder => '_build_valid',
             );
 
+sub _build_valid {
+    my $self = shift;
+    return 0;
+}
+
+
+=head2 package_collection
+
+Returns the L<Debugs::Collection::Package> which is in use by this version
+object.
+
+=cut
+
 has 'package_collection' => (is => 'ro',
                             isa => 'Debbugs::Collection::Package',
                             builder => '_build_package_collection',

diff --git a/Debbugs/Version/Binary.pm b/Debbugs/Version/Binary.pm
index d787fc780de2aefe11e398cf5b7d71feb86808f8..25d7020005e0689e5df66294a001888276e58dc1 100644 (file)
--- a/Debbugs/Version/Binary.pm
+++ b/Debbugs/Version/Binary.pm
@@ -45,7 +45,7 @@ has source_version => (is => 'ro',
 sub _build_source_version {
     my $self = shift;
     my $source_version =
-       $self->package->
+       $self->pkg->
        get_source_version(version => $self->version,
                           $self->_count_archs?(archs => [$self->_archs]):(),
                          );
@@ -59,6 +59,11 @@ sub _build_source_version {
                                        );
 }
 
+sub src_pkg_ver {
+    my $self = shift;
+    return $self->source->src_pkg_ver;
+}
+
 has archs => (is => 'bare',
              isa => 'ArrayRef[Str]',
              builder => '_build_archs',
@@ -76,7 +81,7 @@ sub _build_archs {
 
 sub arch {
     my $self = shift;
-    return $self->_count_archs > 0?join('',$self->_archs):'any';
+    return $self->_count_archs > 0?join(',',$self->_archs):'any';
 }
 
 

diff --git a/Debbugs/Version/Source.pm b/Debbugs/Version/Source.pm
index 98b88491addf2cb95ba25fa9307c7370c65bfec3..a23959c27fa9dd3e86888b0f1c398ce95702e9a1 100644 (file)
--- a/Debbugs/Version/Source.pm
+++ b/Debbugs/Version/Source.pm
@@ -42,7 +42,7 @@ sub source_version {
 
 sub src_pkg_ver {
     my $self = shift;
-    return $self->source->name.'/'.$self->version;
+    return $self->package.'/'.$self->version;
 }
 
 has maintainer => (is => 'ro',
@@ -51,7 +51,7 @@ has maintainer => (is => 'ro',
 
 sub source {
     my $self = shift;
-    return $self->package;
+    return $self->pkg;
 }
 
 sub arch {