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 - 2011 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.