X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=lib%2FCPANPLUS%2FDist%2FGentoo%2FAtom.pm;h=e285b0ce32a28b8220f4a4a36739e9bcbe1461c9;hb=93eb049958520c8b4980d76e5654e5cdd3774d2f;hp=002b349be48a31dc5ff532f80760a49bf5456df6;hpb=e8b4c54d60a1bab156b8bc270df2d95327ddd4e1;p=perl%2Fmodules%2FCPANPLUS-Dist-Gentoo.git

diff --git a/lib/CPANPLUS/Dist/Gentoo/Atom.pm b/lib/CPANPLUS/Dist/Gentoo/Atom.pm
index 002b349..e285b0c 100644
--- a/lib/CPANPLUS/Dist/Gentoo/Atom.pm
+++ b/lib/CPANPLUS/Dist/Gentoo/Atom.pm
@@ -3,8 +3,24 @@ package CPANPLUS::Dist::Gentoo::Atom;
 use strict;
 use warnings;
 
+=head1 NAME
+
+CPANPLUS::Dist::Gentoo::Version - Gentoo atom object.
+
+=head1 VERSION
+
+Version 0.08
+
+=cut
+
 our $VERSION = '0.08';
 
+=head1 DESCRIPTION
+
+This class models Gentoo atoms.
+
+=cut
+
 use Carp         ();
 use Scalar::Util ();
 
@@ -18,6 +34,14 @@ use CPANPLUS::Dist::Gentoo::Version;
 
 my $version_rx = $CPANPLUS::Dist::Gentoo::Version::version_rx;
 
+=head1 METHODS
+
+=head2 C<< new category => $category, name => $name [, version => $version, range => $range, ebuild => $ebuild ] >>
+
+Creates a new L<CPANPLUS::Dist::Gentoo::Atom> object from the supplied C<$category>, C<$name>, C<$version>, C<$range> and C<$ebuild>.
+
+=cut
+
 sub new {
  my $class = shift;
  $class = ref($class) || $class;
@@ -34,11 +58,6 @@ sub new {
   $atom =~ m{^([\w-]+)/([\w-]+)-v?($version_rx)$}
                                                or Carp::confess('Invalid atom');
   ($category, $name, $version) = ($1, $2, $3);
- } elsif (defined $args{ebuild}) {
-  my $ebuild = $args{ebuild};
-  $ebuild =~ m{/([\w-]+)/([\w-]+)/\2-v?($version_rx)\.ebuild$}
-                                             or Carp::confess('Invalid ebuild');
-  ($category, $name, $version) = ($1, $2, $3);
  } else {
   Carp::confess('Not enough information for building an atom object');
  }
@@ -72,10 +91,61 @@ sub new {
  }, $class;
 }
 
+=head2 C<new_from_ebuild $ebuild>
+
+Creates a new L<CPANPLUS::Dist::Gentoo::Atom> object by inferring the category, name and version from the given C<$ebuild>
+
+=cut
+
+sub new_from_ebuild {
+ my $class = shift;
+ $class = ref($class) || $class;
+
+ my $ebuild = shift;
+ $ebuild = '' unless defined $ebuild;
+
+ $ebuild =~ m{/([\w-]+)/([\w-]+)/\2-v?($version_rx)\.ebuild$}
+                                             or Carp::confess('Invalid ebuild');
+ my ($category, $name, $version) = ($1, $2, $3);
+
+ return $class->new(
+  category => $category,
+  name     => $name,
+  version  => $version,
+  ebuild   => $ebuild,
+ );
+}
+
 BEGIN {
  eval "sub $_ { \$_[0]->{$_} }" for qw/category name version range ebuild/;
 }
 
+=head2 C<category>
+
+Read-only accessor to the atom category.
+
+=head2 C<name>
+
+Read-only accessor to the atom name.
+
+=head2 C<version>
+
+Read-only accessor to the L<CPANPLUS::Dist::Gentoo::Version> object associated with the atom.
+
+=head2 C<range>
+
+Read-only accessor to the atom range.
+
+=head2 C<ebuild>
+
+Read-only accessor to the path of an optional ebuild associated with the atom.
+
+=head2 C<qualified_name>
+
+Returns the qualified name for the atom, i.e. C<$category/$name>.
+
+=cut
+
 sub qualified_name { join '/', $_[0]->category, $_[0]->name }
 
 sub _spaceship {
@@ -135,6 +205,12 @@ my %order = (
  '>'  =>  2,
 );
 
+=head2 C<and @atoms>
+
+Compute the ranged atom representing the logical AND between C<@atoms> with the same category and name.
+
+=cut
+
 sub and {
  shift unless length ref $_[0];
 
@@ -177,6 +253,12 @@ sub and {
  }
 }
 
+=head2 C<fold @atoms>
+
+Returns a list built from C<@atoms> but where there's only one atom for a given category and name.
+
+=cut
+
 sub fold {
  shift unless length ref $_[0];
 
@@ -191,4 +273,36 @@ sub fold {
  return values %seen;
 }
 
-1;
+=pod
+
+This class provides overloaded methods for numerical comparison, string comparison and strigification.
+
+=head1 SEE ALSO
+
+L<CPANPLUS::Dist::Gentoo>, L<CPANPLUS::Dist::Gentoo::Version>.
+
+=head1 AUTHOR
+
+Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
+
+You can contact me by mail or on C<irc.perl.org> (vincent).
+
+=head1 BUGS
+
+Please report any bugs or feature requests to C<bug-cpanplus-dist-gentoo at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPANPLUS-Dist-Gentoo>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
+
+=head1 SUPPORT
+
+You can find documentation for this module with the perldoc command.
+
+    perldoc CPANPLUS::Dist::Gentoo
+
+=head1 COPYRIGHT & LICENSE
+
+Copyright 2009 Vincent Pit, all rights reserved.
+
+This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
+
+=cut
+
+1; # End of CPANPLUS::Dist::Gentoo::Atom