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


line stmt bran cond sub pod time code
1 5     5   1947 use 5.008001;
  5         17  
2 5     5   22 use strict;
  5         9  
  5         77  
3 5     5   19 use warnings;
  5         11  
  5         190  
4              
5             package CPAN::Common::Index;
6             # ABSTRACT: Common library for searching CPAN modules, authors and distributions
7              
8             our $VERSION = '0.009'; # TRIAL
9              
10 5     5   25 use Carp ();
  5         7  
  5         75  
11              
12 5     5   1871 use Class::Tiny;
  5         11114  
  5         36  
13              
14             #--------------------------------------------------------------------------#
15             # Document abstract methods
16             #--------------------------------------------------------------------------#
17              
18             #pod =method search_packages (ABSTRACT)
19             #pod
20             #pod $result = $index->search_packages( { package => "Moose" });
21             #pod @result = $index->search_packages( \%advanced_query );
22             #pod
23             #pod Searches the index for a package such as listed in the CPAN
24             #pod F<02packages.details.txt> file. The query must be provided as a hash
25             #pod reference. Valid keys are
26             #pod
27             #pod =for :list
28             #pod * package -- a string, regular expression or code reference
29             #pod * version -- a version number or code reference
30             #pod * dist -- a string, regular expression or code reference
31             #pod
32             #pod If the query term is a string or version number, the query will be for an exact
33             #pod match. If a code reference, the code will be called with the value of the
34             #pod field for each potential match. It should return true if it matches.
35             #pod
36             #pod Not all backends will implement support for all fields or all types of queries.
37             #pod If it does not implement either, it should "decline" the query with an empty
38             #pod return.
39             #pod
40             #pod The return should be context aware, returning either a
41             #pod single result or a list of results.
42             #pod
43             #pod The result must be formed as follows:
44             #pod
45             #pod {
46             #pod package => 'MOOSE',
47             #pod version => '2.0802',
48             #pod uri => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
49             #pod }
50             #pod
51             #pod The C field should be a valid URI. It may be a L or any other
52             #pod URI. (It is up to a client to do something useful with any given URI scheme.)
53             #pod
54             #pod =method search_authors (ABSTRACT)
55             #pod
56             #pod $result = $index->search_authors( { id => "DAGOLDEN" });
57             #pod @result = $index->search_authors( \%advanced_query );
58             #pod
59             #pod Searches the index for author data such as from the CPAN F<01mailrc.txt> file.
60             #pod The query must be provided as a hash reference. Valid keys are
61             #pod
62             #pod =for :list
63             #pod * id -- a string, regular expression or code reference
64             #pod * fullname -- a string, regular expression or code reference
65             #pod * email -- a string, regular expression or code reference
66             #pod
67             #pod If the query term is a string, the query will be for an exact match. If a code
68             #pod reference, the code will be called with the value of the field for each
69             #pod potential match. It should return true if it matches.
70             #pod
71             #pod Not all backends will implement support for all fields or all types of queries.
72             #pod If it does not implement either, it should "decline" the query with an empty
73             #pod return.
74             #pod
75             #pod The return should be context aware, returning either a single result or a list
76             #pod of results.
77             #pod
78             #pod The result must be formed as follows:
79             #pod
80             #pod {
81             #pod id => 'DAGOLDEN',
82             #pod fullname => 'David Golden',
83             #pod email => 'dagolden@cpan.org',
84             #pod }
85             #pod
86             #pod The C field may not reflect an actual email address. The 01mailrc file
87             #pod on CPAN often shows "CENSORED" when email addresses are concealed.
88             #pod
89             #pod =cut
90              
91             #--------------------------------------------------------------------------#
92             # stub methods
93             #--------------------------------------------------------------------------#
94              
95             #pod =method index_age
96             #pod
97             #pod $epoch = $index->index_age;
98             #pod
99             #pod Returns the modification time of the index in epoch seconds. This may not make sense
100             #pod for some backends. By default it returns the current time.
101             #pod
102             #pod =cut
103              
104 0     0 1   sub index_age { time }
105              
106             #pod =method refresh_index
107             #pod
108             #pod $index->refresh_index;
109             #pod
110             #pod This ensures the index source is up to date. For example, a remote
111             #pod mirror file would be re-downloaded. By default, it does nothing.
112             #pod
113             #pod =cut
114              
115 0     0 1   sub refresh_index { 1 }
116              
117             #pod =method attributes
118             #pod
119             #pod Return attributes and default values as a hash reference. By default
120             #pod returns an empty hash reference.
121             #pod
122             #pod =cut
123              
124 0     0 1   sub attributes { {} }
125              
126             #pod =method validate_attributes
127             #pod
128             #pod $self->validate_attributes;
129             #pod
130             #pod This is called by the constructor to validate any arguments. Subclasses
131             #pod should override the default one to perform validation. It should not be
132             #pod called by application code. By default, it does nothing.
133             #pod
134             #pod =cut
135              
136 0     0 1   sub validate_attributes { 1 }
137              
138             1;
139              
140              
141             # vim: ts=4 sts=4 sw=4 et:
142              
143             __END__