.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Common::Index 3pm" .TH CPAN::Common::Index 3pm "2021-01-03" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Common::Index \- Common library for searching CPAN modules, authors and distributions .SH "VERSION" .IX Header "VERSION" version 0.010 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use CPAN::Common::Index::Mux::Ordered; \& use Data::Dumper; \& \& $index = CPAN::Common::Index::Mux::Ordered\->assemble( \& MetaDB => {}, \& Mirror => { mirror => "http://cpan.cpantesters.org" }, \& ); \& \& $result = $index\->search_packages( { package => "Moose" } ); \& \& print Dumper($result); \& \& # { \& # package => \*(AqMOOSE\*(Aq, \& # version => \*(Aq2.0802\*(Aq, \& # uri => "cpan:///distfile/ETHER/Moose\-2.0802.tar.gz" \& # } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a common library for working with a variety of \s-1CPAN\s0 index services. It is intentionally minimalist, trying to use as few non-core modules as possible. .PP The \f(CW\*(C`CPAN::Common::Index\*(C'\fR module is an abstract base class that defines a common \s-1API.\s0 Individual backends deliver the \s-1API\s0 for a particular index. .PP As shown in the \s-1SYNOPSIS,\s0 one interesting application is multiplexing \*(-- using different index backends, querying each in turn, and returning the first result. .SH "METHODS" .IX Header "METHODS" .SS "search_packages (\s-1ABSTRACT\s0)" .IX Subsection "search_packages (ABSTRACT)" .Vb 2 \& $result = $index\->search_packages( { package => "Moose" }); \& @result = $index\->search_packages( \e%advanced_query ); .Ve .PP Searches the index for a package such as listed in the \s-1CPAN\s0 \&\fI02packages.details.txt\fR file. The query must be provided as a hash reference. Valid keys are .IP "\(bu" 4 package \*(-- a string, regular expression or code reference .IP "\(bu" 4 version \*(-- a version number or code reference .IP "\(bu" 4 dist \*(-- a string, regular expression or code reference .PP If the query term is a string or version number, the query will be for an exact match. If a code reference, the code will be called with the value of the field for each potential match. It should return true if it matches. .PP Not all backends will implement support for all fields or all types of queries. If it does not implement either, it should \*(L"decline\*(R" the query with an empty return. .PP The return should be context aware, returning either a single result or a list of results. .PP The result must be formed as follows: .PP .Vb 5 \& { \& package => \*(AqMOOSE\*(Aq, \& version => \*(Aq2.0802\*(Aq, \& uri => "cpan:///distfile/ETHER/Moose\-2.0802.tar.gz" \& } .Ve .PP The \f(CW\*(C`uri\*(C'\fR field should be a valid \s-1URI.\s0 It may be a URI::cpan or any other \&\s-1URI.\s0 (It is up to a client to do something useful with any given \s-1URI\s0 scheme.) .SS "search_authors (\s-1ABSTRACT\s0)" .IX Subsection "search_authors (ABSTRACT)" .Vb 2 \& $result = $index\->search_authors( { id => "DAGOLDEN" }); \& @result = $index\->search_authors( \e%advanced_query ); .Ve .PP Searches the index for author data such as from the \s-1CPAN\s0 \fI01mailrc.txt\fR file. The query must be provided as a hash reference. Valid keys are .IP "\(bu" 4 id \*(-- a string, regular expression or code reference .IP "\(bu" 4 fullname \*(-- a string, regular expression or code reference .IP "\(bu" 4 email \*(-- a string, regular expression or code reference .PP If the query term is a string, the query will be for an exact match. If a code reference, the code will be called with the value of the field for each potential match. It should return true if it matches. .PP Not all backends will implement support for all fields or all types of queries. If it does not implement either, it should \*(L"decline\*(R" the query with an empty return. .PP The return should be context aware, returning either a single result or a list of results. .PP The result must be formed as follows: .PP .Vb 5 \& { \& id => \*(AqDAGOLDEN\*(Aq, \& fullname => \*(AqDavid Golden\*(Aq, \& email => \*(Aqdagolden@cpan.org\*(Aq, \& } .Ve .PP The \f(CW\*(C`email\*(C'\fR field may not reflect an actual email address. The 01mailrc file on \s-1CPAN\s0 often shows \*(L"\s-1CENSORED\*(R"\s0 when email addresses are concealed. .SS "index_age" .IX Subsection "index_age" .Vb 1 \& $epoch = $index\->index_age; .Ve .PP Returns the modification time of the index in epoch seconds. This may not make sense for some backends. By default it returns the current time. .SS "refresh_index" .IX Subsection "refresh_index" .Vb 1 \& $index\->refresh_index; .Ve .PP This ensures the index source is up to date. For example, a remote mirror file would be re-downloaded. By default, it does nothing. .SS "attributes" .IX Subsection "attributes" Return attributes and default values as a hash reference. By default returns an empty hash reference. .SS "validate_attributes" .IX Subsection "validate_attributes" .Vb 1 \& $self\->validate_attributes; .Ve .PP This is called by the constructor to validate any arguments. Subclasses should override the default one to perform validation. It should not be called by application code. By default, it does nothing. .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Common\-Index.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" David Golden .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Helmut Wollmersdorfer .IP "\(bu" 4 Kenichi Ishigaki .IP "\(bu" 4 Shoichi Kaji .IP "\(bu" 4 Tatsuhiko Miyagawa .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2013 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve