NAME

       CPAN::SQLite - maintain and search a minimal CPAN database

VERSION

       version 0.211

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