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

  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.

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.

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

* subchapter => $subchapter

This argument will look up all distributions with the specified $subchapter within the given chapter specified by $chapterid.

* query => $query_term

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.

* 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.

* 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 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.

* 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.

* 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 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.

* 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.

* 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.

* query => $query_term

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.

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.