• NAME
• SYNOPSIS
• CONSTRUCTING THE QUERY
• module, dist, and author modes
• chapter mode
• RESULTS
• author mode
• module mode
• dist mode
• chapter mode
• SEE ALSO
• COPYRIGHT

NAME

CPAN::Search::Lite::Query - perform queries on the database

SYNOPSIS

  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};

CONSTRUCTING THE QUERY

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

  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.

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.

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 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.
• 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).
• 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.

chapter mode

For a mode of chapter, one can specify two additional arguments:

• id => $chapterid
  
This argument (which is required) will look up all subchapters with the specified numerical $chapterid (see %chaps of the CPAN::Search::Lite::Util manpage for a description).
• subchapter => $subchapter
  
This argument (which is optional) will look up all distributions with the specified $subchapter within the given chapter specified by $chapterid.

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 the CPAN::Search::Lite::Populate manpage 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, 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.
• letter query
  
This returns an array reference, each member of which is a hash reference containing the auth_id, cpanid, and fullname fields.
• 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, 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.
• html
  
If doc is true, an entry html is constructed giving the location (relative to html_root) of the html file.
• download
  
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.
• 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 three keys in this hash reference (coming from $repositories of the CPAN::Search::Lite::Util manpage) - rep_id, giving the repository's rep_id, desc, giving a description of the repository, and browse, giving a url to the repository.

• letter query
  
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.
• 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, and mod_abs fields. 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, 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.
• 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, 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.
• 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).
• 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.
• ppms
  
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 the CPAN::Search::Lite::Util manpage) - rep_id, giving the repository's rep_id, desc, giving a description of the repository, and browse, giving a url to the repository.

• letter query
  
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.
• 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, and dist_abs fields. If there is only one result found, a name query based on the matched dist_name is performed.
• recent query
  
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.

chapter mode

• id => $chapterid
  
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.
• subchapter => $subchapter
  
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.

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.

SEE ALSO

Apache::CPAN::Search and Apache::CPAN::Query.

COPYRIGHT

This software is copyright 2004 by Randy Kobes <randy@theoryx5.uwinnipeg.ca>. Use and redistribution are under the same terms as Perl itself.