Provided by: libcpan-sqlite-perl_0.211-3_all bug

NAME

       CPAN::SQLite::Search - perform queries on the database

VERSION

       version 0.211

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