1CPAN::Common::Index(3)User Contributed Perl DocumentationCPAN::Common::Index(3)
2
6 CPAN::Common::Index - Common library for searching CPAN modules,
7 authors and distributions
8
10 version 0.010
11
13 use CPAN::Common::Index::Mux::Ordered;
14 use Data::Dumper;
15 $index = CPAN::Common::Index::Mux::Ordered->assemble(
17 MetaDB => {},
18 Mirror => { mirror => "http://cpan.cpantesters.org" },
19 );
20 $result = $index->search_packages( { package => "Moose" } );
22 print Dumper($result);
24 # {
26 # package => 'MOOSE',
27 # version => '2.0802',
28 # uri => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
29 # }
30
32 This module provides a common library for working with a variety of
33 CPAN index services. It is intentionally minimalist, trying to use as
34 few non-core modules as possible.
35 The "CPAN::Common::Index" module is an abstract base class that defines
37 a common API. Individual backends deliver the API for a particular
38 index.
39 As shown in the SYNOPSIS, one interesting application is multiplexing
41 -- using different index backends, querying each in turn, and returning
42 the first result.
43
45 search_packages (ABSTRACT)
46 $result = $index->search_packages( { package => "Moose" });
47 @result = $index->search_packages( \%advanced_query );
48 Searches the index for a package such as listed in the CPAN
50 02packages.details.txt file. The query must be provided as a hash
51 reference. Valid keys are
52 • package -- a string, regular expression or code reference
54 • version -- a version number or code reference
56 • dist -- a string, regular expression or code reference
58 If the query term is a string or version number, the query will be for
60 an exact match. If a code reference, the code will be called with the
61 value of the field for each potential match. It should return true if
62 it matches.
63 Not all backends will implement support for all fields or all types of
65 queries. If it does not implement either, it should "decline" the
66 query with an empty return.
67 The return should be context aware, returning either a single result or
69 a list of results.
70 The result must be formed as follows:
72 {
74 package => 'MOOSE',
75 version => '2.0802',
76 uri => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
77 }
78 The "uri" field should be a valid URI. It may be a URI::cpan or any
80 other URI. (It is up to a client to do something useful with any given
81 URI scheme.)
82 search_authors (ABSTRACT)
84 $result = $index->search_authors( { id => "DAGOLDEN" });
85 @result = $index->search_authors( \%advanced_query );
86 Searches the index for author data such as from the CPAN 01mailrc.txt
88 file. The query must be provided as a hash reference. Valid keys are
89 • id -- a string, regular expression or code reference
91 • fullname -- a string, regular expression or code reference
93 • email -- a string, regular expression or code reference
95 If the query term is a string, the query will be for an exact match.
97 If a code reference, the code will be called with the value of the
98 field for each potential match. It should return true if it matches.
99 Not all backends will implement support for all fields or all types of
101 queries. If it does not implement either, it should "decline" the
102 query with an empty return.
103 The return should be context aware, returning either a single result or
105 a list of results.
106 The result must be formed as follows:
108 {
110 id => 'DAGOLDEN',
111 fullname => 'David Golden',
112 email => 'dagolden@cpan.org',
113 }
114 The "email" field may not reflect an actual email address. The
116 01mailrc file on CPAN often shows "CENSORED" when email addresses are
117 concealed.
118 index_age
120 $epoch = $index->index_age;
121 Returns the modification time of the index in epoch seconds. This may
123 not make sense for some backends. By default it returns the current
124 time.
125 refresh_index
127 $index->refresh_index;
128 This ensures the index source is up to date. For example, a remote
130 mirror file would be re-downloaded. By default, it does nothing.
131 attributes
133 Return attributes and default values as a hash reference. By default
134 returns an empty hash reference.
135 validate_attributes
137 $self->validate_attributes;
138 This is called by the constructor to validate any arguments.
140 Subclasses should override the default one to perform validation. It
141 should not be called by application code. By default, it does nothing.
142
144 Bugs / Feature Requests
145 Please report any bugs or feature requests through the issue tracker at
146 <https://github.com/Perl-Toolchain-Gang/CPAN-Common-Index/issues>. You
147 will be notified automatically of any progress on your issue.
148 Source Code
150 This is open source software. The code repository is available for
151 public review and contribution under the terms of the license.
152 <https://github.com/Perl-Toolchain-Gang/CPAN-Common-Index>
154 git clone https://github.com/Perl-Toolchain-Gang/CPAN-Common-Index.git
156
158 David Golden <dagolden@cpan.org>
159
161 • David Golden <xdg@xdg.me>
162 • Helmut Wollmersdorfer <helmut@wollmersdorfer.at>
164 • Kenichi Ishigaki <ishigaki@cpan.org>
166 • Shoichi Kaji <skaji@cpan.org>
168 • Tatsuhiko Miyagawa <miyagawa@bulknews.net>
170
172 This software is Copyright (c) 2013 by David Golden.
173 This is free software, licensed under:
175 The Apache License, Version 2.0, January 2004
177perl v5.38.0 2023-07-20 CPAN::Common::Index(3)