--- name: "CPAN::SQLite::Search" section: "3pm" platform: "linux" package: "libcpan-sqlite-perl" version: "0.220-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/CPAN::SQLite::Search" --- # CPAN::SQLite::Search(3pm) perform queries on the database ## NAME CPAN::SQLite::Search - perform queries on the database ## VERSION version 0.220 ## 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"`, `"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. - • `"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"`, and `"mod_vers"` fields for the module. - • `"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 \ ## COPYRIGHT Copyright 2006,2008 by Randy Kobes \. Copyright 2011-2013 by Serguei Trouchelle \. Use and redistribution are under the same terms as Perl itself.