NAME
    Module::Collection - Examine a group of Perl distributions

DESCRIPTION
    WARNING: THIS IS AN EARLY RELEASE FOR INFORMATIONAL PURPOSES ONLY. PARTS
    OF THIS MODULE ARE SUBJECT TO CHANGE WITHOUT NOTICE.

    The canonical source of all CPAN and Perl installation functionality is
    a simple group of release tarballs, contained within some directory.

    After all, at the very core CPAN is just a simple FTP server containing
    a number of files uploaded by authors.

    Module::Collection is a a simple object which takes an arbitrary
    directory, scans it for tarballs (which are assumed to be distribution
    tarballs) and allows you to load up the tarballs as Module::Inspector
    objects.

    While this is a fairly simple and straight forward implementation, and
    is certainly not scalable enough to handle all of CPAN, it should be
    quite sufficient for loading and examining a typical group of
    distribution tarballs generated as part of a private project.

  new
      my $collection = Module::Collection->new( root => $directory );

    The "new" constructor creates a new collection. It takes the named
    "root" param (the only param now, but with more to come) and scans
    recursively inside it for any tarballs, which should be Perl
    distribution release tarballs.

    Returns a new Module::Collection object, or dies on error.

  root
    The "root" accessor returns the path to the collection root, as provided
    originally to the constructor.

  dists
    The "dists" method returns a list of the file names for the
    distributions that the collection is currently aware of.

    In scalar context, returns the number of dists instead.

  dist_path
      my $file_path = $collection->dist_path('dists/Config-Tiny-2.09.tar.gz');

    The c<dist_path> method takes the name of a dist in the collection in
    relative unix-style format, and returns a localised absolute path to the
    distribution tarball.

  dist
      my $inspector = $collection->dist('dists/Config-Tiny-2.09.tar.gz');

    The "dist" methods creates and returns a Module::Inspector object for
    the distribution.

  ignore_dist
    Most of the time when working with a collection of release tarballs your
    code is only going to want to have to work with a subset.

    The "ignore_dist" method takes the name of a dist in the collection and
    removes it from the collection.

    Note the method is called "ignore" for a reason. This does NOT in any
    way delete or remove the dist itself, it just removes it from the
    collection's view.

    Returns true or dies on error.

  ignore_old_dists
    The "ignore_old_dists" method scans through all of the dists in the
    collection, and removes (ignores) any distribution that has a never
    version of the same distribution.

    This has the result of taking a whole mishmash of distributions and
    leaving you with only the newest version or each unique distribution.

    Returns true or dies on error.

TO DO
    - Implement most of the functionality

SUPPORT
    This module is stored in an Open Repository at the following address.

    <http://svn.phase-n.com/svn/cpan/trunk/Module-Collection>

    Write access to the repository is made available automatically to any
    published CPAN author, and to most other volunteers on request.

    If you are able to submit your bug report in the form of new (failing)
    unit tests, or can apply your fix directly instead of submitting a
    patch, you are strongly encouraged to do so as the author currently
    maintains over 100 modules and it can take some time to deal with
    non-Critcal bug reports or patches.

    This will guarentee that your issue will be addressed in the next
    release of the module.

    If you cannot provide a direct test or fix, or don't have time to do so,
    then regular bug reports are still accepted and appreciated via the CPAN
    bug tracker.

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Collection>

    For other issues, for commercial enhancement or support, or to have your
    write access enabled for the repository, contact the author at the email
    address above.

ACKNOWLEDGEMENTS
    The biggest acknowledgement must go to Chris Nandor, who wielded his
    legendary Mac-fu and turned my initial fairly ordinary Darwin
    implementation into something that actually worked properly everywhere,
    and then donated a Mac OS X license to allow it to be maintained
    properly.

AUTHORS
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    Module::Inspector

COPYRIGHT
    Copyright 2006 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.

