refactor, docs

Changes

@@ -1,5 +1,10 @@
 Revision history for CPAN-Faker
 
+0.004     2008-05-07
+          add more public interface and documentation (HDP, RJBS)
+          most of this work is to allow construction of the indices without
+          using a source dir or the make_cpan method
+
 0.003     2008-04-28
           promote (by renaming) write_modlist_index and write_package index
 

lib/CPAN/Faker.pm

@@ -82,44 +82,17 @@ current maintainer (see below).
 This create the new CPAN::Faker.  All arguments may be accessed later by
 methods of the same name.  Valid arguments are:
 
-  source - the directory in which to find source files
-  dest   - the directory in which to construct the CPAN instance
+  source - the directory in which to find source files; optional, required by
+           make_cpan
+  dest   - the directory in which to construct the CPAN instance; required
   url    - the base URL for the CPAN; a file:// URL is generated by default
 
   dist_class - the class used to fake dists; default: Module::Faker::Dist
 
 =cut
 
-has _pkg_index => (
-  is  => 'ro',
-  isa => 'HashRef',
-  default  => sub { {} },
-  init_arg => undef,
-);
-
-has _author_index => (
-  is  => 'ro',
-  isa => 'HashRef',
-  default  => sub { {} },
-  init_arg => undef,
-);
-
-has _author_dir => (
-  is  => 'ro',
-  isa => 'HashRef',
-  default  => sub { {} },
-  init_arg => undef,
-);
-
-has source => (is => 'ro', isa => 'Str', required => 1);
 has dest   => (is => 'ro', isa => 'Str', required => 1);
-
-has dist_dest => (
-  is   => 'ro',
-  lazy => 1,
-  init_arg => undef,
-  default  => sub { File::Spec->catdir($_[0]->dest, qw(authors id)) },
-);
+has source => (is => 'ro', isa => 'Str', required => 0);
 
 has dist_class => (
   is  => 'ro',
@@ -139,15 +112,40 @@ has url => (
   },
 );
 
+has dist_dest => (
+  is   => 'ro',
+  lazy => 1,
+  init_arg => undef,
+  default  => sub { File::Spec->catdir($_[0]->dest, qw(authors id)) },
+);
+
+BEGIN {
+  # These attributes are used to keep track of the indexes we'll write when we
+  # finish adding content to the CPAN::Faker. -- rjbs, 2008-05-07
+  for (qw(pkg_index author_index author_dir)) {
+    has "_$_" => (
+      is  => 'ro',
+      isa => 'HashRef',
+      default  => sub { {} },
+      init_arg => undef,
+    );
+  }
+}
+
+sub _validate_dir {
+  my ($self, $type) = @_;
+
+  my $dir = $self->$type;
+  Carp::croak "$type directory not supplied"       unless $dir;
+  Carp::croak "$type directory does not exist"     unless -e $dir;
+  Carp::croak "$type directory is not a directory" unless -d $dir;
+  Carp::croak "$type directory is not writeable"   unless -w $dir;
+}
+
 sub BUILD {
   my ($self) = @_;
 
-  for (qw(source dest)) {
-    my $dir = $self->$_;
-    Carp::croak "$_ directory does not exist"     unless -e $dir;
-    Carp::croak "$_ directory is not a directory" unless -d $dir;
-    Carp::croak "$_ directory is not writeable"   unless -w $dir;
-  }
+  $self->_validate_dir('dest');
 }
 
 sub __dor { defined $_[0] ? $_[0] : $_[1] }
@@ -162,23 +160,13 @@ archives are written out into the author's directory, distribution contents are
 (potentially) added to the index, CHECKSUMS files are created, and the indices
 are then written out.
 
-=head2 write_author_index
-
-=head2 write_package_index
-
-=head2 write_modlist_index
-
-All these are automatically called by C<make_cpan>; you probably do not need to
-call them yourself.
-
-Write C<01mailrc.txt.gz>, C<02packages.details.txt.gz>, and
-C<03modlist.data.gz>, respectively.
-
 =cut
 
 sub make_cpan {
   my ($self, $arg) = @_;
 
+  $self->_validate_dir('source');
+
   my $iter = File::Next::files($self->source);
 
   while (my $file = $iter->()) {
@@ -193,6 +181,15 @@ sub make_cpan {
   $self->write_modlist_index;
 }
 
+=head2 add_dist
+
+  $faker->add_dist($dist);
+
+This method expects a L<Module::Faker::Dist> object, for which it will
+construct an archive, index the author and (maybe) the contents.
+
+=cut
+
 sub add_dist {
   my ($self, $dist) = @_;
 
@@ -326,6 +323,20 @@ sub _maybe_index {
   }
 }
 
+=head2 write_author_index
+
+=head2 write_package_index
+
+=head2 write_modlist_index
+
+All these are automatically called by C<make_cpan>; you probably do not need to
+call them yourself.
+
+Write C<01mailrc.txt.gz>, C<02packages.details.txt.gz>, and
+C<03modlist.data.gz>, respectively.
+
+=cut
+
 sub write_author_index {
   my ($self) = @_;