NAME¶
CPAN::SQLite::Search - perform queries on the database
SYNOPSIS¶
my $max_results = 200;
my $query = CPAN::SQLite::Search->new(db_dir => $db_dir,
db_name => $db_name,
max_results => $max_results);
$query->query(mode => 'module', name => 'Net::FTP');
my $results = $query->{results};
CONSTRUCTING THE QUERY¶
This module queries the database via various types of queries and returns the
results for subsequent display. The "CPAN::SQLite::Search" object is
created via the "new" method as
my $query = CPAN::SQLite::Search->new(db_dir => $db_dir,
db_name => $db_name,
max_results => $max_results);
which takes as arguments
- •
- db_dir => $db_dir
This is the directory where the database file is stored. This is optional if
the "CPAN" option is given.
- •
- CPAN => $CPAN
This option specifies the "cpan_home" directory of an already
configured CPAN.pm, which is where the database file will be stored if
"db_dir" is not given.
- •
- 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::SQLite::Search" will be used.
A basic query then is constructed as
$query->query(mode => $mode, $type => $value);
with the results available as
my $results = $query->{results}
There are three 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.
"module", "dist", and "author" modes¶
For a mode of "module", "dist", and "author",
there are four basic options to be used for the "$type => $value"
option:
- •
- query => $query_term
This will search through module names, distribution names, or CPAN author
names and ids (for "module", "dist", and
"author" modes respectively). The results are case insensitive,
and Perl regular expressions for the $query_term are recognized.
- •
- 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.
- •
- 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.
RESULTS¶
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::SQLite::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.
"author" mode¶
- •
- "name" or "id" query
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", "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.
- •
- "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.
"module" mode¶
- •
- "name" or "id" query
This returns the "mod_id", "mod_name",
"mod_abs", "mod_vers", "dslip",
"chapterid", "dist_id", "dist_name",
"dist_file", "auth_id", "cpanid",
"fullname", and "email" of the "auths",
"mods", and "dists" tables. As well, the following
entries may be present.
- •
- "download"
This can be used as "$CPAN/authors/id/$download" to specify the
url of the distribution.
- •
- "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.
- •
- "query" query
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", "mod_abs", "mod_abs",
"dist_vers", "dist_abs", "auth_id",
"cpanid", "dist_id", "dist_name", and
"dist_file". As well, a "download" field which can be
used as "$CPAN/authors/id/$download" to specify the url of the
distribution is provided. If there is only one result found, a
"name" query based on the matched "mod_name" is
performed.
"dist" mode¶
- •
- "name" or "id" query
This returns the "dist_id", "dist_name",
"dist_abs", "dist_vers", "dist_file",
"size", "birth", "auth_id",
"cpanid", and "fullname" of the "auths",
"mods", and "dists" tables. As well, the following
entries may be present.
- •
- "download"
This can be used as "$CPAN/authors/id/$download" to specify the
url of the distribution.
- •
- "mods"
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", and
"dslip" fields for the module.
- •
- "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.
- •
- "query" query
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", "dist_abs", "dist_file", and
"cpanid" fields. As well, a "download" field which can
be used as "$CPAN/authors/id/$download" to specify the url of
the distribution is provided. If there is only one result found, a
"name" query based on the matched "dist_name" is
performed.
SEE ALSO¶
CPAN::SQLite::Populate.
AUTHORS¶
Randy Kobes (passed away on September 18, 2010)
Serguei Trouchelle <stro@cpan.org>
COPYRIGHT¶
Copyright 2006,2008 by Randy Kobes <r.kobes@uwinnipeg.ca>.
Copyright 2011-2013 by Serguei Trouchelle <stro@cpan.org>.
Use and redistribution are under the same terms as Perl itself.