1CPAN::Common::Index(3)User Contributed Perl DocumentationCPAN::Common::Index(3)
2
3
4

NAME

6       CPAN::Common::Index - Common library for searching CPAN modules,
7       authors and distributions
8

VERSION

10       version 0.010
11

SYNOPSIS

13           use CPAN::Common::Index::Mux::Ordered;
14           use Data::Dumper;
15
16           $index = CPAN::Common::Index::Mux::Ordered->assemble(
17               MetaDB => {},
18               Mirror => { mirror => "http://cpan.cpantesters.org" },
19           );
20
21           $result = $index->search_packages( { package => "Moose" } );
22
23           print Dumper($result);
24
25           # {
26           #   package => 'MOOSE',
27           #   version => '2.0802',
28           #   uri     => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
29           # }
30

DESCRIPTION

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
36       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
40       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

METHODS

45   search_packages (ABSTRACT)
46           $result = $index->search_packages( { package => "Moose" });
47           @result = $index->search_packages( \%advanced_query );
48
49       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
53       •   package -- a string, regular expression or code reference
54
55       •   version -- a version number or code reference
56
57       •   dist -- a string, regular expression or code reference
58
59       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
64       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
68       The return should be context aware, returning either a single result or
69       a list of results.
70
71       The result must be formed as follows:
72
73           {
74             package => 'MOOSE',
75             version => '2.0802',
76             uri     => "cpan:///distfile/ETHER/Moose-2.0802.tar.gz"
77           }
78
79       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
83   search_authors (ABSTRACT)
84           $result = $index->search_authors( { id => "DAGOLDEN" });
85           @result = $index->search_authors( \%advanced_query );
86
87       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
90       •   id -- a string, regular expression or code reference
91
92       •   fullname -- a string, regular expression or code reference
93
94       •   email -- a string, regular expression or code reference
95
96       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
100       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
104       The return should be context aware, returning either a single result or
105       a list of results.
106
107       The result must be formed as follows:
108
109           {
110               id       => 'DAGOLDEN',
111               fullname => 'David Golden',
112               email    => 'dagolden@cpan.org',
113           }
114
115       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
119   index_age
120           $epoch = $index->index_age;
121
122       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
126   refresh_index
127           $index->refresh_index;
128
129       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
132   attributes
133       Return attributes and default values as a hash reference.  By default
134       returns an empty hash reference.
135
136   validate_attributes
137           $self->validate_attributes;
138
139       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

SUPPORT

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
149   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
153       <https://github.com/Perl-Toolchain-Gang/CPAN-Common-Index>
154
155         git clone https://github.com/Perl-Toolchain-Gang/CPAN-Common-Index.git
156

AUTHOR

158       David Golden <dagolden@cpan.org>
159

CONTRIBUTORS

161       •   David Golden <xdg@xdg.me>
162
163       •   Helmut Wollmersdorfer <helmut@wollmersdorfer.at>
164
165       •   Kenichi Ishigaki <ishigaki@cpan.org>
166
167       •   Shoichi Kaji <skaji@cpan.org>
168
169       •   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
170
172       This software is Copyright (c) 2013 by David Golden.
173
174       This is free software, licensed under:
175
176         The Apache License, Version 2.0, January 2004
177
178
179
180perl v5.38.0                      2023-07-20            CPAN::Common::Index(3)
Impressum