.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CPAN::SQLite::Search 3"
.TH CPAN::SQLite::Search 3 "2015-07-15" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CPAN::SQLite::Search \- perform queries on the database
.SH "VERSION"
.IX Header "VERSION"
version 0.211
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  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 => \*(Aqmodule\*(Aq, name => \*(AqNet::FTP\*(Aq);
\&  my $results = $query\->{results};
.Ve
.SH "CONSTRUCTING THE QUERY"
.IX Header "CONSTRUCTING THE QUERY"
This module queries the database via various types of queries
and returns the results for subsequent display. The
\&\f(CW\*(C`CPAN::SQLite::Search\*(C'\fR object is created via the \f(CW\*(C`new\*(C'\fR method as
.PP
.Vb 3
\&  my $query = CPAN::SQLite::Search\->new(db_dir => $db_dir,
\&                                        db_name => $db_name,
\&                                        max_results => $max_results);
.Ve
.PP
which takes as arguments
.IP "\(bu" 3
db_dir => \f(CW$db_dir\fR
.Sp
This is the directory where the database file is stored. This is
optional if the \f(CW\*(C`CPAN\*(C'\fR option is given.
.IP "\(bu" 3
\&\s-1CPAN\s0 => \f(CW$CPAN\fR
.Sp
This option specifies the \f(CW\*(C`cpan_home\*(C'\fR directory of an
already configured \s-1CPAN\s0.pm, which is where the database
file will be stored if \f(CW\*(C`db_dir\*(C'\fR is not given.
.IP "\(bu" 3
max_results => \f(CW$max_results\fR
.Sp
This is the maximum value used to limit the number of results
returned under a user query. If not specified, a value contained
within \f(CW\*(C`CPAN::SQLite::Search\*(C'\fR will be used.
.PP
A basic query then is constructed as
.PP
.Vb 1
\&   $query\->query(mode => $mode, $type => $value);
.Ve
.PP
with the results available as
.PP
.Vb 1
\&   my $results = $query\->{results}
.Ve
.PP
There are three basic modes:
.IP "\(bu" 3
module
.Sp
This is for information on modules.
.IP "\(bu" 3
dist
.Sp
This is for information on distributions.
.IP "\(bu" 3
author
.Sp
This is for information on \s-1CPAN\s0 authors or cpanids.
.ie n .SS """module"", ""dist"", and ""author"" modes"
.el .SS "\f(CWmodule\fP, \f(CWdist\fP, and \f(CWauthor\fP modes"
.IX Subsection "module, dist, and author modes"
For a mode of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`dist\*(C'\fR, and \f(CW\*(C`author\*(C'\fR, there are
four basic options to be used for the \f(CW\*(C`$type => $value\*(C'\fR option:
.IP "\(bu" 3
query => \f(CW$query_term\fR
.Sp
This will search through module names,
distribution names, or \s-1CPAN\s0 author names and ids
(for \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`dist\*(C'\fR, and \f(CW\*(C`author\*(C'\fR modes
respectively). The results are case insensitive,
and Perl regular expressions for the \f(CW$query_term\fR
are recognized.
.IP "\(bu" 3
name => \f(CW$name\fR
.Sp
This will report exact matches (in a case sensitive manner)
for the module name, distribution name, or \s-1CPAN\s0 author id,
for \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`dist\*(C'\fR, and \f(CW\*(C`author\*(C'\fR modes
respectively.
.IP "\(bu" 3
id => \f(CW$id\fR
.Sp
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 \*(L"publically\*(R" is
probably not a good idea, as the ids may change over the
course of time.
.SH "RESULTS"
.IX Header "RESULTS"
After making the query, the results can be accessed through
.PP
.Vb 1
\&  my $results = $query\->{results};
.Ve
.PP
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 \f(CW\*(C`$query\->{error}\*(C'\fR).
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.
.ie n .SS """author"" mode"
.el .SS "\f(CWauthor\fP mode"
.IX Subsection "author mode"
.IP "\(bu" 3
\&\f(CW\*(C`name\*(C'\fR or \f(CW\*(C`id\*(C'\fR query
.Sp
This returns the \f(CW\*(C`auth_id\*(C'\fR, \f(CW\*(C`cpanid\*(C'\fR, \f(CW\*(C`email\*(C'\fR, and \f(CW\*(C`fullname\*(C'\fR
of the \f(CW\*(C`auths\*(C'\fR table. As well, an array reference
\&\f(CW\*(C`$results\->{dists}\*(C'\fR is returned representing
all distributions associated with that \f(CW\*(C`cpanid\*(C'\fR \- each
member of the array reference is a hash reference
describing the \f(CW\*(C`dist_id\*(C'\fR, \f(CW\*(C`dist_name\*(C'\fR,
\&\f(CW\*(C`dist_abs\*(C'\fR, \f(CW\*(C`dist_vers\*(C'\fR, and \f(CW\*(C`dist_file\*(C'\fR fields in the
\&\f(CW\*(C`dists\*(C'\fR table. An additional entry, \f(CW\*(C`download\*(C'\fR, is
supplied, which can be used as \f(CW\*(C`$CPAN/authors/id/$download\*(C'\fR
to specify the url of the distribution.
.IP "\(bu" 3
\&\f(CW\*(C`query\*(C'\fR query
.Sp
If this results in more than one match, an array reference
is returned, each member of which is a hash reference containing
the \f(CW\*(C`auth_id\*(C'\fR, \f(CW\*(C`cpanid\*(C'\fR, and \f(CW\*(C`fullname\*(C'\fR fields. If there
is only one result found, a \f(CW\*(C`name\*(C'\fR query based on the
matched \f(CW\*(C`cpanid\*(C'\fR is performed.
.ie n .SS """module"" mode"
.el .SS "\f(CWmodule\fP mode"
.IX Subsection "module mode"
.IP "\(bu" 3
\&\f(CW\*(C`name\*(C'\fR or \f(CW\*(C`id\*(C'\fR query
.Sp
This returns the \f(CW\*(C`mod_id\*(C'\fR, \f(CW\*(C`mod_name\*(C'\fR, \f(CW\*(C`mod_abs\*(C'\fR, \f(CW\*(C`mod_vers\*(C'\fR,
\&\f(CW\*(C`dslip\*(C'\fR, \f(CW\*(C`chapterid\*(C'\fR, \f(CW\*(C`dist_id\*(C'\fR, \f(CW\*(C`dist_name\*(C'\fR, \f(CW\*(C`dist_file\*(C'\fR,
\&\f(CW\*(C`auth_id\*(C'\fR, \f(CW\*(C`cpanid\*(C'\fR, \f(CW\*(C`fullname\*(C'\fR, and \f(CW\*(C`email\*(C'\fR
of the \f(CW\*(C`auths\*(C'\fR, \f(CW\*(C`mods\*(C'\fR, and \f(CW\*(C`dists\*(C'\fR tables.
As well, the following entries may be present.
.RS 3
.IP "\(bu" 3
\&\f(CW\*(C`download\*(C'\fR
.Sp
This can be used as \f(CW\*(C`$CPAN/authors/id/$download\*(C'\fR
to specify the url of the distribution.
.IP "\(bu" 3
\&\f(CW\*(C`dslip_info\*(C'\fR
.Sp
If \f(CW\*(C`dslip\*(C'\fR is available, an array reference \f(CW\*(C`dslip_info\*(C'\fR is supplied,
each entry being a hash reference. The hash reference contains
two keys \- \f(CW\*(C`desc\*(C'\fR, whose value is a general description of the
what the dslip entry represents, and \f(CW\*(C`what\*(C'\fR, whose value is
a description of the entry itself.
.RE
.RS 3
.RE
.IP "\(bu" 3
\&\f(CW\*(C`query\*(C'\fR query
.Sp
If this results in more than one match, an array reference
is returned, each member of which is a hash reference containing
the \f(CW\*(C`mod_id\*(C'\fR, \f(CW\*(C`mod_name\*(C'\fR, \f(CW\*(C`mod_abs\*(C'\fR, \f(CW\*(C`mod_abs\*(C'\fR, \f(CW\*(C`dist_vers\*(C'\fR, \f(CW\*(C`dist_abs\*(C'\fR,
\&\f(CW\*(C`auth_id\*(C'\fR, \f(CW\*(C`cpanid\*(C'\fR, \f(CW\*(C`dist_id\*(C'\fR, \f(CW\*(C`dist_name\*(C'\fR, and \f(CW\*(C`dist_file\*(C'\fR.
As well, a \f(CW\*(C`download\*(C'\fR field which
can be used as \f(CW\*(C`$CPAN/authors/id/$download\*(C'\fR
to specify the url of the distribution is provided. If there
is only one result found, a \f(CW\*(C`name\*(C'\fR query based on the
matched \f(CW\*(C`mod_name\*(C'\fR is performed.
.ie n .SS """dist"" mode"
.el .SS "\f(CWdist\fP mode"
.IX Subsection "dist mode"
.IP "\(bu" 3
\&\f(CW\*(C`name\*(C'\fR or \f(CW\*(C`id\*(C'\fR query
.Sp
This returns the \f(CW\*(C`dist_id\*(C'\fR, \f(CW\*(C`dist_name\*(C'\fR, \f(CW\*(C`dist_abs\*(C'\fR, \f(CW\*(C`dist_vers\*(C'\fR,
\&\f(CW\*(C`dist_file\*(C'\fR, \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`birth\*(C'\fR, \f(CW\*(C`auth_id\*(C'\fR, \f(CW\*(C`cpanid\*(C'\fR, and \f(CW\*(C`fullname\*(C'\fR
of the \f(CW\*(C`auths\*(C'\fR, \f(CW\*(C`mods\*(C'\fR, and \f(CW\*(C`dists\*(C'\fR tables.
As well, the following entries may be present.
.RS 3
.IP "\(bu" 3
\&\f(CW\*(C`download\*(C'\fR
.Sp
This can be used as \f(CW\*(C`$CPAN/authors/id/$download\*(C'\fR
to specify the url of the distribution.
.IP "\(bu" 3
\&\f(CW\*(C`mods\*(C'\fR
.Sp
This is an array reference containing information on the
modules present. Each entry is a hash reference containing the
\&\f(CW\*(C`mod_id\*(C'\fR, \f(CW\*(C`mod_name\*(C'\fR, \f(CW\*(C`mod_abs\*(C'\fR, \f(CW\*(C`mod_vers\*(C'\fR, and \f(CW\*(C`dslip\*(C'\fR
fields for the module.
.IP "\(bu" 3
\&\f(CW\*(C`dslip\*(C'\fR and \f(CW\*(C`dslip_info\*(C'\fR
.Sp
If the module name and distribution name are related by
\&\f(CW\*(C`s/::/\-\*(C'\fR, the \f(CW\*(C`dslip\*(C'\fR and \f(CW\*(C`dslip_info\*(C'\fR entries for
that module are returned.
.RE
.RS 3
.RE
.IP "\(bu" 3
\&\f(CW\*(C`query\*(C'\fR query
.Sp
If this results in more than one match, an array reference
is returned, each member of which is a hash reference containing
the \f(CW\*(C`dist_id\*(C'\fR, \f(CW\*(C`dist_name\*(C'\fR, \f(CW\*(C`dist_abs\*(C'\fR, \f(CW\*(C`dist_file\*(C'\fR,
and \f(CW\*(C`cpanid\*(C'\fR fields. As well, a \f(CW\*(C`download\*(C'\fR field which
can be used as \f(CW\*(C`$CPAN/authors/id/$download\*(C'\fR
to specify the url of the distribution is provided. If there
is only one result found, a \f(CW\*(C`name\*(C'\fR query based on the
matched \f(CW\*(C`dist_name\*(C'\fR is performed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CPAN::SQLite::Populate.
.SH "AUTHORS"
.IX Header "AUTHORS"
Randy Kobes (passed away on September 18, 2010)
.PP
Serguei Trouchelle <stro@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006,2008 by Randy Kobes <r.kobes@uwinnipeg.ca>.
.PP
Copyright 2011\-2013 by Serguei Trouchelle <stro@cpan.org>.
.PP
Use and redistribution are under the same terms as Perl itself.