The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CPAN-Mini-Visit-1.15
River stage one • 3 direct dependents • 3 total dependents
3 ++
/ CPAN::Mini::Visit

NAME

CPAN::Mini::Visit - A generalised API version of David Golden's visitcpan

SYNOPSIS

  CPAN::Mini::Visit->new(
      minicpan => '/minicpan',
      acme     => 0,
      author   => 'ADAMK',
      warnings => 1,
      random   => 1,
      callback => sub {
          print "# counter: $_[0]->{counter}\n";
          print "# archive: $_[0]->{archive}\n";
          print "# tempdir: $_[0]->{tempdir}\n";
          print "# dist:    $_[0]->{dist}\n";
          print "# author:  $_[0]->{author}\n";
      }
  )->run;
  
  # counter: 1234
  # archive: /minicpan/authors/id/A/AD/ADAMK/Config-Tiny-1.00.tar.gz
  # tempdir: /tmp/1a4YRmFAJ3/Config-Tiny-1.00
  # dist:    ADAMK/Config-Tiny-1.00.tar.gz
  # author:  ADAMK

DESCRIPTION

CPAN::Mini::Extract has been relatively successful at allowing processes to run across the contents (or a subset of the contents) of an entire minicpan checkout.

However it has become evident that while it is useful (and theoretically optimal from a processing point of view) to maintain an expanded minicpan checkout the sheer size of an expanded minicpan is such that it becomes an undo burdon to manage, move, copy or even delete a directory tree with hundreds of thousands of file totalling in the high single gigabytes in size.

Annoyed by this, David Golden created visitcpan which takes an alternative approach of sequentially expanding the tarball of each distribution into a temporary directory, do the processing on that distribution, and then delete the temporary directory before moving on to the next directory.

This method results in a longer computation time, but with the benefit of dramatically reduced system overhead, greater adaptability, and allow for easy ad-hoc computations.

This improvement in flexibility turns out to be worth the extra computation time in almost all cases.

CPAN::Mini::Visit is a simplified and generalised API-based version of David Golden's visitcpan script.

It implements only the process of discovering, iterating and expanding archives, before handing off control to an arbitrary callback function provided to the constructor.

new

Takes a variety of parameters and creates a new visitor object.

The minicpan param should be the root directory of a CPAN::Mini download.

The callback param should be a CODE reference that will be called for each visit. The first parameter passed to the callback will be a HASH reference containing the tarball location in the archive key, the location of the temporary directory in the tempdir key, the canonical CPAN distribution name in the dist key, and the author id in the author key.

The acme param (true by default) can be set to false to exclude any distributions that contain the string "Acme", allowing the visit to ignore any of the joke modules.

The author param can be provided to limit the visit to only the modules owned by a specific author.

The random param will cause the archives to be processed in random order if enabled. If not, the archives will be processed in alphabetical order.

The warnings param will turn on Archive::Extract warnings if enabled, or disable warnings otherwise.

The prefer_bin param will tell Archive::Extract to use binary extract instead of CPAN module extract wherever possible. By default, it will use module-based extract.

Returns a CPAN::Mini::Visit object, or throws an exception on error.

run

The run method executes the visit process, taking no parameters and returning true.

Because the object contains no state information, you may call the run method multiple times for a single visit object with no ill effects.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN-Mini-Visit

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2009 - 2012 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.