CPAN::Search::Lite::Query - perform queries on the database
my $max_results = 200; my $query = CPAN::Search::Lite::Query->new(db => $db, user => $user, passwd => $passwd, max_results => $max_results); $query->query(mode => 'module', name => 'Net::FTP'); my $results = $query->{results};
This module queries the database via various types of queries and returns the results for subsequent display. The CPAN::Search::Lite::Query object is created via the new method as
CPAN::Search::Lite::Query
new
my $query = CPAN::Search::Lite::Query->new(db => $db, user => $user, passwd => $passwd, max_results => $max_results);
which takes as arguments
db => $db
This is the name of the database.
user => $user
This is the user under which the database connection will be made.
passwd => $passwd
This is the password to use when connecting.
max_results => $max_results
This is the maximum value used to limit the number of results returned under a user query. If not specified, a value contained within CPAN::Search::Lite::Query will be used.
lang => $lang
This is used to specify what language the description of the CPAN chapter ids and the dslip information is to be returned in. If not specified, or if specified but not present as a key in %langs of CPAN::Search::Lite::Util, the default of en (English) will be used.
%langs
CPAN::Search::Lite::Util
en
A basic query then is constructed as
$query->query(mode => $mode, $type => $value);
with the results available as
my $results = $query->{results}
There are four basic modes:
module
This is for information on modules.
dist
This is for information on distributions.
author
This is for information on CPAN authors or cpanids.
chapter
This is for information on chapters associated with distributions and modules.
For a mode of module, dist, and author, there are four basic options to be used for the $type => $value option:
$type => $value
query => $query_term
This will search through module names and abstracts, distribution names and abstracts, or CPAN author names and full names (for module, dist, and author modes respectively). The results generally are case insensitive. Matches are reported that match all search terms supplied - for example, $query_term = 'foo bar' will find occurences of foo and bar. To exclude a term in $query_term, prepend that term with a minus sign = $query_term = 'foo -bar' will find all instances foo that don't include bar. Regular expressions (as used by mysql) are also supported.
$query_term = 'foo bar'
foo
bar
$query_term
$query_term = 'foo -bar'
mysql
name => $name
This will report exact matches (in a case sensitive manner) for the module name, distribution name, or CPAN author id, for module, dist, and author modes respectively.
letter => $letter
If $letter is a single letter, this will find all modules, distributions, or CPAN author ids beginning with that letter (for module, dist, and author modes respectively). If $letter is more than one letter, this will find all distribtion names matching $letter-* (for the dist mode) or all module names matching $letter::* (for the module mode).
$letter
$letter-*
$letter::*
id => $id
This will look up information on the primary key according to the mode specified. This is more for internal use, to help speed up queries; using this "publically" is probably not a good idea, as the ids may change over the course of time.
As well, for the dist mode there is an additional type: recent => $age, which will report all distribtions uploaded in the last $age days. If $age is not specified, it will default to 7.
recent => $age
$age
For a mode of chapter, one can specify three additional arguments:
id => $chapterid
This argument will look up all subchapters with the specified numerical $chapterid (see %chaps of CPAN::Search::Lite::Util for a description).
$chapterid
%chaps
subchapter => $subchapter
This argument will look up all distributions with the specified $subchapter within the given chapter specified by $chapterid.
$subchapter
This argument will look up all distributions who have a subchapter matching $query_term.
After making the query, the results can be accessed through
my $results = $query->{results};
No results either can mean no matches were found, or else an error in making the query resulted (in which case, a brief error message is contained in $query->{error}). Assuming there are results, what is returned depends on the mode and on the type of query. See CPAN::Search::Lite::Populate for a description of the fields in the various tables listed below - these fields are used as the keys of the hash references that arise.
$query->{error}
name or id query
name
id
This returns the auth_id, cpanid, email, and fullname of the auths table. As well, an array reference $results->{dists} is returned representing all distributions associated with that cpanid - each member of the array reference is a hash reference describing the dist_id, dist_name, birth, dist_abs, dist_vers, and dist_file fields in the dists table. An additional entry, download, is supplied, which can be used as $CPAN/authors/id/$download to specify the url of the distribution.
auth_id
cpanid
email
fullname
auths
$results->{dists}
dist_id
dist_name
birth
dist_abs
dist_vers
dist_file
dists
download
$CPAN/authors/id/$download
letter query
letter
This returns an array reference, each member of which is a hash reference containing the auth_id, cpanid, and fullname fields.
query query
query
If this results in more than one match, an array reference is returned, each member of which is a hash reference containg the auth_id, cpanid, and fullname fields. If there is only one result found, a name query based on the matched cpanid is performed.
This returns the mod_id, mod_name, mod_abs, doc, mod_vers, dslip, chapterid, dist_id, dist_name, dist_file, auth_id, cpanid, and fullname of the auths, mods, and dists tables. As well, the following entries may be present.
mod_id
mod_name
mod_abs
doc
mod_vers
dslip
chapterid
mods
html
If doc is true, an entry html is constructed giving the location (relative to html_root) of the html file.
html_root
This can be used as $CPAN/authors/id/$download to specify the url of the distribution.
chap_desc
An accompanying entry chap_desc is supplied giving a description of chapterid, if present. This is given in the language specified, if present, with a default of English.
chap_link
An accompanying entry chap_link is supplied giving a string (in English) suitable for use in a link for chapterid, if present.
dslip_info
If dslip is available, an array reference dslip_info is supplied, each entry being a hash reference. The hash reference contains two keys - desc, whose value is a general description of the what the dslip entry represents, and what, whose value is a description of the entry itself.
desc
what
ppms
If there are ppm packages available for the distribution containing the module, an array reference ppms is supplied, each item of which is a hash reference. There are four keys in this hash reference (coming from $repositories of CPAN::Search::Lite::Util) - rep_id, giving the repository's rep_id, desc, giving a description of the repository, alias, an alias for the repository, and browse, giving a url to the repository.
$repositories
rep_id
alias
browse
This returns an array reference, each entry of which can be of two types. If there are multiple occurrences of a module matching FOO::* at the top level, then the entry is a hash reference with key letter and associated value FOO, as well as a key count with value giving the number of matching entries. If there is only one module matching FOO::* at the top level, then the entry is a hash reference containing the mod_name, mod_id, and mod_abs fields.
FOO::*
FOO
count
If this results in more than one match, an array reference is returned, each member of which is a hash reference containing the mod_id, mod_name, and mod_abs fields. If there is only one result found, a name query based on the matched mod_name is performed.
This returns the dist_id, dist_name, dist_abs, dist_vers, dist_file, size, birth, readme, changes, meta, install, auth_id, cpanid, and fullname of the auths, mods, and dists tables. Note that readme, changes, meta, and install are boolean values just indicating if the corresponding file is present. As well, the following entries may be present.
size
readme
changes
meta
install
This is an array reference containing information on the modules present. Each entry is a hash reference containing the mod_id, mod_name, mod_abs, mod_vers, doc, and dslip fields for the module. If doc is present, an html entry is created giving the location (relative to html_root) of the documentation.
dslip and dslip_info
If the module name and distribution name are related by s/::/-, the dslip and dslip_info entries for that module are returned.
s/::/-
chaps
If present, an array reference chaps is returned, each entry of which is a hash reference containing chapterid, subchapter, chap_desc (a description of the chapter id, in the language specified), and chap_link (a string in English suitable for use as a link to chapterid).
subchapter
reqs
If prerequisites for the distribtion have been specified, an array reference reqs is returned, each item of which is a hash reference containing mod_id, req_vers, mod_name, and mod_abs for each prerequisite.
req_vers
If there are ppm packages available for the distribution, an array reference ppms is supplied, each item of which is a hash reference. There are three keys in this hash reference (coming from $repositories of CPAN::Search::Lite::Util) - rep_id, giving the repository's rep_id, desc, giving a description of the repository, and browse, giving a url to the repository.
This returns an array reference, each entry of which can be of two types. If there are multiple occurrences of a distribution matching FOO-* at the top level, then the entry is a hash reference with key letter and associated value FOO, as well as a key count with value giving the number of matching entries. If there is only one distribution matching FOO-* at the top level, then the entry is a hash reference containing the dist_name, dist_id, and dist_abs fields.
FOO-*
If this results in more than one match, an array reference is returned, each member of which is a hash reference containing the dist_id, dist_name, and dist_abs fields. If there is only one result found, a name query based on the matched dist_name is performed.
recent query
recent
This performs a query for all distributions uploaded to CPAN in the last 7 days. The result is an array reference, each item of which is a hash reference containing the birth, dist_id, dist_name, dist_abs, dist_vers, dist_file, auth_id, and cpanid fields. As well, for each entry a download entry is present, which can be used as $CPAN/authors/id/$download to specify the url of the distribution.
This will return an array reference, each item of which is a hash reference containing the corresponding subchapter field. If there is only one entry within a subchapter, the dist_abs and dist_id of the associated distribution is also returned, while if there is more than one entry, a key count with value giving the number of matching entries is returned.
This will return an array reference corresponding to all distributions with the specified subchapter within the given chapter. Each item of the array reference is a hash reference specifying the dist_name, dist_id, and dist_abs of the distribution.
This will return an array reference, each member of which is a hash reference containing the dist_id, dist_name, dist_abs fields, chapterid, and chap_link fields. As well, a chap_desc field is returned, giving a description of the main chapter.
For a name or id query of dist, author, or module, if the query is constructed as
$query->query(mode => $mode, $type => $value, fields => $fields);
where $fields is an array reference, then only those fields specified will be returned. For author, only the auths table is searched, for module, the mods, auths, and dists tables are searched, and for dist, the dists and auths tables are searched.
$fields
Apache2::CPAN::Search and Apache2::CPAN::Query.
This software is copyright 2004 by Randy Kobes <randy@theoryx5.uwinnipeg.ca>. Use and redistribution are under the same terms as Perl itself.
To install CPAN::Search::Lite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPAN::Search::Lite
CPAN shell
perl -MCPAN -e shell install CPAN::Search::Lite
For more information on module installation, please visit the detailed CPAN module installation guide.