File Coverage

blib/lib/CPAN/Common/Index.pm

Criterion	Covered	Total	%
statement	14	18	77.7
branch			n/a
condition			n/a
subroutine	5	9	55.5
pod	4	4	100.0
total	23	31	74.1

use 5.008001;
use strict;
use warnings;

package CPAN::Common::Index;
# ABSTRACT: Common library for searching CPAN modules, authors and distributions

our $VERSION = '0.009'; # TRIAL

use Carp ();

use Class::Tiny;

#--------------------------------------------------------------------------#
# Document abstract methods
#--------------------------------------------------------------------------#

#pod =method search_packages (ABSTRACT)
#pod
#pod     $result = $index->search_packages( { package => "Moose" });
#pod     @result = $index->search_packages( \%advanced_query );
#pod
#pod Searches the index for a package such as listed in the CPAN
#pod F<02packages.details.txt> file.  The query must be provided as a hash
#pod reference.  Valid keys are
#pod
#pod =for :list
#pod * package -- a string, regular expression or code reference
#pod * version -- a version number or code reference
#pod * dist -- a string, regular expression or code reference
#pod
#pod If the query term is a string or version number, the query will be for an exact
#pod match.  If a code reference, the code will be called with the value of the
#pod field for each potential match.  It should return true if it matches.
#pod
#pod Not all backends will implement support for all fields or all types of queries.
#pod If it does not implement either, it should "decline" the query with an empty
#pod return.
#pod
#pod The return should be context aware, returning either a
#pod single result or a list of results.
#pod
#pod The result must be formed as follows:
#pod
#pod     {
#pod       package => 'MOOSE',
#pod       version => '2.0802',
#pod       uri     => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
#pod     }
#pod
#pod The C field should be a valid URI.  It may be a L or any other
#pod URI.  (It is up to a client to do something useful with any given URI scheme.)
#pod
#pod =method search_authors (ABSTRACT)
#pod
#pod     $result = $index->search_authors( { id => "DAGOLDEN" });
#pod     @result = $index->search_authors( \%advanced_query );
#pod
#pod Searches the index for author data such as from the CPAN F<01mailrc.txt> file.
#pod The query must be provided as a hash reference.  Valid keys are
#pod
#pod =for :list
#pod * id -- a string, regular expression or code reference
#pod * fullname -- a string, regular expression or code reference
#pod * email -- a string, regular expression or code reference
#pod
#pod If the query term is a string, the query will be for an exact match.  If a code
#pod reference, the code will be called with the value of the field for each
#pod potential match.  It should return true if it matches.
#pod
#pod Not all backends will implement support for all fields or all types of queries.
#pod If it does not implement either, it should "decline" the query with an empty
#pod return.
#pod
#pod The return should be context aware, returning either a single result or a list
#pod of results.
#pod
#pod The result must be formed as follows:
#pod
#pod     {
#pod         id       => 'DAGOLDEN',
#pod         fullname => 'David Golden',
#pod         email    => '[e-mail]',
#pod     }
#pod
#pod The C field may not reflect an actual email address.  The 01mailrc file
#pod on CPAN often shows "CENSORED" when email addresses are concealed.
#pod
#pod =cut

#--------------------------------------------------------------------------#
# stub methods
#--------------------------------------------------------------------------#

#pod =method index_age
#pod
#pod     $epoch = $index->index_age;
#pod
#pod Returns the modification time of the index in epoch seconds.  This may not make sense
#pod for some backends.  By default it returns the current time.
#pod
#pod =cut

sub index_age { time }

#pod =method refresh_index
#pod
#pod     $index->refresh_index;
#pod
#pod This ensures the index source is up to date.  For example, a remote
#pod mirror file would be re-downloaded.  By default, it does nothing.
#pod
#pod =cut

sub refresh_index { 1 }

#pod =method attributes
#pod
#pod Return attributes and default values as a hash reference.  By default
#pod returns an empty hash reference.
#pod
#pod =cut

sub attributes { {} }

#pod =method validate_attributes
#pod
#pod     $self->validate_attributes;
#pod
#pod This is called by the constructor to validate any arguments.  Subclasses
#pod should override the default one to perform validation.  It should not be
#pod called by application code.  By default, it does nothing.
#pod
#pod =cut

sub validate_attributes { 1 }

1;


# vim: ts=4 sts=4 sw=4 et:

__END__