.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPAN::SQLite 3pm"
.TH CPAN::SQLite 3pm "2014-08-04" "perl v5.18.2" "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 \- maintain and search a minimal CPAN database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& my $obj = CPAN::SQLite\->new(CPAN => \*(Aq/path/to/CPAN\*(Aq);
\& $obj\->index(setup => 1);
\&
\& $obj\->query(mode => \*(Aqdist\*(Aq, name => \*(AqCPAN\*(Aq);
\& my $results = $obj\->{results};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package is used for setting up, maintaining, and
searching a \s-1CPAN\s0 database consisting of the information
stored in the three main \s-1CPAN\s0 indices:
\&\fI\f(CI$CPAN\fI/modules/03modlist.data.gz\fR,
\&\fI\f(CI$CPAN\fI/modules/02packages.details.txt.gz\fR, and
\&\fI\f(CI$CPAN\fI/authors/01mailrc.txt.gz\fR. It should be
considered at an alpha stage of development.
.PP
One begins by creating the object as
.PP
.Vb 1
\& my $obj = CPAN::SQLite\->new(%args);
.Ve
.PP
which accepts the following arguments:
.IP "\(bu" 3
\&\f(CW\*(C`CPAN => \*(Aq/path/to/CPAN\*(Aq\*(C'\fR
.Sp
This specifies the path to where the index files are
to be stored. This could be a local \s-1CPAN\s0 mirror,
defined here by the presence of a \fI\s-1MIRRORED.BY\s0\fR file beneath
this directory, or a local directory in which to store
these files from a remote \s-1CPAN\s0 mirror. In the latter case,
the index files are fetched from a remote \s-1CPAN\s0 mirror,
using the same list that \f(CW\*(C`CPAN.pm\*(C'\fR uses, if this is
configured, and are updated if they are more than one
day old.
.Sp
If the \f(CW\*(C`CPAN\*(C'\fR option is not given, it will default
to \f(CW\*(C`cpan_home\*(C'\fR of \s-1CPAN\s0, if this is configured,
with the index files found under \f(CW\*(C`keep_source_where\*(C'\fR.
A fatal error results if such a directory isn't found.
Updates to these index files are assumed here to be
handled by \f(CW\*(C`CPAN.pm\*(C'\fR.
.IP "\(bu" 3
\&\f(CW\*(C`db_dir => \*(Aq/path/to/db/dir\*(Aq\*(C'\fR
.Sp
This specifies the path to where the database file is
found. If not given, it defaults to the
\&\f(CW\*(C`cpan_home\*(C'\fR directory of \f(CW\*(C`CPAN.pm\*(C'\fR, if present, or to
the directory in which the script was invoked. The name
of the database file is \f(CW\*(C`cpandb.sql\*(C'\fR.
.PP
There are two main methods available.
.ie n .SS """$obj\->index(%args);"""
.el .SS "\f(CW$obj\->index(%args);\fP"
.IX Subsection "$obj->index(%args);"
This is used to set up and maintain the database. The
following arguments are accepted:
.IP "\(bu" 3
setup => 1
.Sp
This specifies that the database is to be created and
populated from the \s-1CPAN\s0 indices; any exisiting database
will be overwritten. Not specifying this option will
assume that an existing database is to be updated.
.IP "\(bu" 3
reindex => 'dist_name'
.Sp
This specifies that the \s-1CPAN\s0 distribution \f(CW\*(C`dist_name\*(C'\fR
is to be reindexed.
.ie n .SS """$obj\->query(%args);"""
.el .SS "\f(CW$obj\->query(%args);\fP"
.IX Subsection "$obj->query(%args);"
This is used for querying the database by distribution
name, module name, or \s-1CPAN\s0 author name. There are
two arguments needed to specify such queries.
.IP "\(bu" 3
\&\f(CW\*(C`mode => some_value\*(C'\fR
.Sp
This specifies what type of query to perform,
with \f(CW\*(C`mode\*(C'\fR being one of \f(CW\*(C`dist\*(C'\fR, \f(CW\*(C`module\*(C'\fR,
or \f(CW\*(C`author\*(C'\fR, for searching through, respectively,
\&\s-1CPAN\s0 distribution names, module names, or author names and
\&\s-1CPAN\s0 ids.
.IP "\(bu" 3
\&\f(CW\*(C`type => query_term\*(C'\fR
.Sp
This specifies the query term for the search, with
\&\f(CW\*(C`type\*(C'\fR being one of \f(CW\*(C`name\*(C'\fR, to search for an
exact match, or \f(CW\*(C`search\*(C'\fR, for searching for partial
matches. Perl regular expressions are supported in
the \f(CW\*(C`query_term\*(C'\fR for the \f(CW\*(C`search\*(C'\fR option.
.PP
As well, an option of \f(CW\*(C`max_results => some_number\*(C'\fR will
limit the number of results returned; if not specified,
this defaults to 200.
.SH "CPAN.pm support"
.IX Header "CPAN.pm support"
As of \s-1CPAN\s0.pm version 1.88_65, there is experimental support
within \s-1CPAN\s0.pm for using CPAN::SQLite to obtain
information on packages, modules, and authors. One goal
of this is to reduce the memory footprint of the \s-1CPAN\s0.pm
shell, as this information is no longer all preloaded into
memory. This can be enabled through
.PP
.Vb 2
\& perl \-MCPAN \-e shell
\& cpan> o conf use_sqlite 1
.Ve
.PP
Use
.PP
.Vb 1
\& cpan> o conf commit
.Ve
.PP
to save this setting for future sessions.
.PP
Using CPAN::SQLite, what happens is that a request for information
through \s-1CPAN\s0.pm, such as
.PP
.Vb 1
\& cpan> a ANDK
.Ve
.PP
will cause a query to the SQLite database to be made.
If successful, this will place the relevant data for this
request into the data structure \s-1CPAN\s0.pm uses to store and
retrieve such information. Thus, at any given time, the
only information \s-1CPAN\s0.pm stores in memory is that for
packages, modules, and authors for which previous queries
have been made. There are certain requests, such as
.PP
.Vb 1
\& cpan> r
.Ve
.PP
to make a list of recommended packages for which upgrades
on \s-1CPAN\s0 are available, which will result in loading
information on all available packages into memory; if such
a query is made, the subsequent memory footprint of \s-1CPAN\s0.pm
with and without CPAN::SQLite will be essentially the same.
.PP
The database itself, called \fIcpandb.sql\fR, will be stored
in the location specified by \f(CW\*(C`$CPAN::Config\->{cpan_home}\*(C'\fR.
When first started, this database will be created, and afterwards,
it will be updated if the database is older than one day since
the last update. A log file of the creation or update process, called
\&\fIcpan_search_log.dddddddddd\fR, will be created in the same
directory as the database file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CPAN::SQLite::Index, for setting up and maintaining
the database, and CPAN::SQLite::Search for an
interface to querying the database. Some details
of the interaction with \s-1CPAN\s0 is available from
CPAN::SQLite::META. See also the cpandb script for a
command-line interface to the
indexing and querying of the database.
.PP
Development takes place on the CPAN-Search-Lite project
at .
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\& perldoc CPAN::SQLite
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
.IP "\(bu" 4
CPAN::Forum: Discussion forum
.Sp
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
.SH "BUGS"
.IX Header "BUGS"
At this time, CPAN::SQLite keeps information contained only
in the latest version of a \s-1CPAN\s0 distribution. This means that
modules that are provided only in older versions of a \s-1CPAN\s0
distribution will not be present in the database; for example,
at this time, the latest version of the \fIlibwww-perl\fR distribution
on \s-1CPAN\s0 is 5.805, but there are modules such as \fIURI::URL::finger\fR
contained in version 5.10 of libwww-perl that are not present in 5.805.
This behaviour differs from that of \s-1CPAN\s0 without CPAN::SQLite.
This may change in the future.
.PP
Please report bugs and feature requests via
.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
Information messages from the indexing procedures are printed
out to \s-1STDOUT\s0 if the environment variable \s-1CPAN_SQLITE_DEBUG\s0
is set. This is automatically set within CPAN::SQLite::Index.
If \s-1CPAN_SQLITE_NO_LOG_FILES\s0 is set, no log files will be created
during the indexing procedures. Log files are deleted automatically
in 30 days. To override this, set \s-1CPAN_SQLITE_LOG_FILES_CLEANUP.\s0
To stop automatic cleanup, set this variable to 0.
.SH "AUTHORS"
.IX Header "AUTHORS"
Randy Kobes (passed away on September 18, 2010)
.PP
Serguei Trouchelle
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006,2008 by Randy Kobes .
.PP
Copyright 2011\-2014 by Serguei Trouchelle .
.PP
Use and redistribution are under the same terms as Perl itself.