NAME

       Package::Locator::Index - The package index of a repository

VERSION

       version 0.010

SYNOPSIS

         use Package::Locator::Index;

         my $index = Package::Locator::Index->new( repository_url => 'http://somewhere' );
         my $dist  = $index->distributions->{'A/AU/AUTHOR/Foo-Bar-1.0.tar.gz'};
         my $pkg   = $index->packages->{'Foo::Bar'};

DESCRIPTION

       This is a private module and there are no user-serviceable parts here.  The API
       documentation is for my own reference only.

       Package::Locator::Index is yet-another module for parsing the contents of the
       02packages.details.txt file from a CPAN-like repository.

CONSTRUCTOR

   new( %attributes )
       All the attributes listed below can be passed to the constructor, and can be retrieved via
       accessor methods with the same name.  All attributes are read-only, and cannot be changed
       once the object is constructed.

ATTRIBUTES

   repository_url => 'http://somewhere'
       The base URL of the repository you want to get the index from.  This is usually a CPAN
       mirror, but can be any site or directory that is organized in a CPAN-like structure.  This
       attribute is required.

   user_agent => $user_agent_obj
       The LWP::UserAgent object that will fetch the index file.  If you do not provide a user
       agent, then a default one will be constructed for you.

   cache_dir => '/some/directory/path'
       The path (as a string or Path::Class::Dir object) to a directory where the index file will
       be cached.  If the directory does not exist, it will be created for you.  If you do not
       specify a cache directory, then a temporary directory will be used.  The temporary
       directory will be deleted when your application terminates.

   force => $boolean
       Causes any cached index files to be removed, thus forcing a new one to be downloaded when
       the object is constructed.  This only has effect if you specified the "cache_dir"
       attribute.  The default is false.

METHODS

   index_file()
       Returns the path to the local copy of the index file (as a Path::Class::File).

   distributions
       Returns a hashref representing the contents of the index.  The keys are the paths to the
       distributions (as they appear in the index).  The values are data structures that look
       like this:

         {
           path     => 'A/AU/AUTHOR/FooBar-1.0.tar.gz',
           source   => 'http://some.cpan.mirror'
           packages => [ ## See package structure below ## ]
         }

   packages
       Returns a hashref representing the contents of the index.  The keys are the names of
       packages.  The values are data structures that look like this:

         {
           name         => 'Foo',
           version      => '1.0',
           distribution => 'A/AU/AUTHOR/FooBar-1.0.tar.gz'
         }

MOTIVATION

       There are numerous existing modules for parsing the 02packages.details.txt file, but I
       wasn't completely happy with any of them.  Most of the existing modules transform the data
       into various flavors of Distribution and Package objects. But I'm not ready to commit to
       any particular API for Distributions and Packages (not even one of my own).  So
       Package::Locator::Index exposes the index data as simple data structures.

AUTHOR

       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Imaginative Software Systems.

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