NAME¶
CPAN::SQLite - maintain and search a minimal CPAN database
SYNOPSIS¶
my $obj = CPAN::SQLite->new(CPAN => '/path/to/CPAN');
$obj->index(setup => 1);
$obj->query(mode => 'dist', name => 'CPAN');
my $results = $obj->{results};
DESCRIPTION¶
This package is used for setting up, maintaining, and searching a CPAN database
consisting of the information stored in the three main CPAN indices:
$CPAN/modules/03modlist.data.gz,
$CPAN/modules/02packages.details.txt.gz, and
$CPAN /authors/01mailrc.txt.gz. It should be considered
at an alpha stage of development.
One begins by creating the object as
my $obj = CPAN::SQLite->new(%args);
which accepts the following arguments:
- •
- "CPAN => '/path/to/CPAN'"
This specifies the path to where the index files are to be stored. This
could be a local CPAN mirror, defined here by the presence of a
MIRRORED.BY file beneath this directory, or a local directory in
which to store these files from a remote CPAN mirror. In the latter case,
the index files are fetched from a remote CPAN mirror, using the same list
that "CPAN.pm" uses, if this is configured, and are updated if
they are more than one day old.
If the "CPAN" option is not given, it will default to
"cpan_home" of CPAN, if this is configured, with the index files
found under "keep_source_where". A fatal error results if such a
directory isn't found. Updates to these index files are assumed here to be
handled by "CPAN.pm".
- •
- "db_dir => '/path/to/db/dir'"
This specifies the path to where the database file is found. If not given,
it defaults to the "cpan_home" directory of "CPAN.pm",
if present, or to the directory in which the script was invoked. The name
of the database file is "cpandb.sql".
There are two main methods available.
"$obj->index(%args);"¶
This is used to set up and maintain the database. The following arguments are
accepted:
- •
- setup => 1
This specifies that the database is to be created and populated from the
CPAN indices; any exisiting database will be overwritten. Not specifying
this option will assume that an existing database is to be updated.
- •
- reindex => 'dist_name'
This specifies that the CPAN distribution "dist_name" is to be
reindexed.
"$obj->query(%args);"¶
This is used for querying the database by distribution name, module name, or
CPAN author name. There are two arguments needed to specify such queries.
- •
- "mode => some_value"
This specifies what type of query to perform, with "mode" being
one of "dist", "module", or "author", for
searching through, respectively, CPAN distribution names, module names, or
author names and CPAN ids.
- •
- "type => query_term"
This specifies the query term for the search, with "type" being
one of "name", to search for an exact match, or
"search", for searching for partial matches. Perl regular
expressions are supported in the "query_term" for the
"search" option.
As well, an option of "max_results => some_number" will limit the
number of results returned; if not specified, this defaults to 200.
CPAN.pm support¶
As of CPAN.pm version 1.88_65, there is experimental support within CPAN.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 CPAN.pm shell, as
this information is no longer all preloaded into memory. This can be enabled
through
perl -MCPAN -e shell
cpan> o conf use_sqlite 1
Use
cpan> o conf commit
to save this setting for future sessions.
Using CPAN::SQLite, what happens is that a request for information through
CPAN.pm, such as
cpan> a ANDK
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 CPAN.pm uses
to store and retrieve such information. Thus, at any given time, the only
information CPAN.pm stores in memory is that for packages, modules, and
authors for which previous queries have been made. There are certain requests,
such as
cpan> r
to make a list of recommended packages for which upgrades on CPAN 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 CPAN.pm
with and without CPAN::SQLite will be essentially the same.
The database itself, called
cpandb.sql, will be stored in the location
specified by "$CPAN::Config->{cpan_home}". 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
cpan_search_log.dddddddddd, will be
created in the same directory as the database file.
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 CPAN is available from CPAN::SQLite::META. See also
the cpandb script for a command-line interface to the indexing and querying of
the database.
Development takes place on the CPAN-Search-Lite project at
<
http://cpan-search.svn.sourceforge.net/viewvc/cpan-search/CPAN-SQLite/>.
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc CPAN::SQLite
You can also look for information at:
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/CPAN-SQLite>
- •
- CPAN::Forum: Discussion forum
<http:///www.cpanforum.com/dist/CPAN-SQLite>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/CPAN-SQLite>
- •
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=CPAN-SQLite>
- •
- Search CPAN
<http://search.cpan.org/dist/CPAN-SQLite>
BUGS¶
At this time, CPAN::SQLite keeps information contained only in the latest
version of a CPAN distribution. This means that modules that are provided only
in older versions of a CPAN distribution will not be present in the database;
for example, at this time, the latest version of the
libwww-perl
distribution on CPAN is 5.805, but there are modules such as
URI::URL::finger contained in version 5.10 of libwww-perl that are not
present in 5.805. This behaviour differs from that of CPAN without
CPAN::SQLite. This may change in the future.
Please report bugs and feature requests via
<
http://rt.cpan.org/NoAuth/Bugs.html?Dist=CPAN-SQLite>.
ENVIRONMENT VARIABLES¶
Information messages from the indexing procedures are printed out to STDOUT if
the environment variable CPAN_SQLITE_DEBUG is set. This is automatically set
within CPAN::SQLite::Index. If CPAN_SQLITE_NO_LOG_FILES is set, no log files
will be created during the indexing procedures. Log files are deleted
automatically in 30 days. To override this, set CPAN_SQLITE_LOG_FILES_CLEANUP.
To stop automatic cleanup, set this variable to 0.
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-2014 by Serguei Trouchelle <stro@cpan.org>.
Use and redistribution are under the same terms as Perl itself.