CPANPLUS::Backend - Object-oriented interface for CPAN++
use CPANPLUS::Backend; my $cp = new CPANPLUS::Backend; ##### Methods which return objects ##### my $err = $cp->error_object(); my $conf = $cp->configure_object(); my $module_obj = $cp->module_tree()->{'Dir::Purge'}; my $all_authors = $cp->author_tree(); ##### Methods which return hash references ##### my $mod_search = $cp->search(type => 'module', list => ['xml', '^dbix?']); my $auth_search = $cp->search(type => 'author', list => ['(?i:mi)'], data => $search, authors_only => 1); $cp->flush('modules'); my $extract = $cp->extract(files => [$fetch_result->{B::Tree}, '/tmp/POE-0.17.tar.gz']); my $make = $cp->make(dirs => ['/home/munchkin/Data-Denter-0.13'] target => 'skiptest'); my $installed = $cp->installed(); my $validated = $cp->validate(modules => ['Rcs', $module_obj]); ### Backend methods with corresponding Module methods # The same result, first with a Backend then a Module method my $fetch_result = $cp->fetch(modules => ['Dir::Purge']); $fetch_result = $module_obj->fetch(); # Backend method my $txt = $cp->readme(modules => ['Mail::Box', '/K/KA/KANE/Acme-POE-Knee-1.10.zip']); # Module method my $install_result = $module_obj->install(fetchdir => '/tmp'); # Backend method my $info = $cp->details(modules => ['Math::Random', 'NexTrieve']); # Backend method my $test_report = $cp->reports(modules => ['Festival::Client']); # Backend method my $uninstalled = $cp->uninstall(modules => ['Acme::POE::Knee'], type => 'prog'); # Backend method my $version_is_cur = $cp->uptodate(modules => ['ControlX10::CM11']); # Backend method my $files_in_dist = $cp->files(modules => ['LEGO::RCX']); ### Backend methods with corresponding Module and Author methods # The same result via Backend, Module and Author methods my $mods_by_same_auth = $cp->modules(authors => ['JV']); $mods_by_same_auth = $module_obj->modules(); $mods_by_same_auth = $all_authors->{'JV'}->modules(); # Backend method my $dists_by_same_auth = $cp->distributions(authors => 'Acme::USIG'); ##### Methods with other return values ##### ### Backend and Module methods # Backend method my $path = $cp->pathname(to => 'C::Scan'); ### Backend methods my $reload = $cp->reload_indices(update_source => 1);
CPANPLUS::Backend is the OO interface to CPAN. It is designed to be used by other programs, such as custom install scripts or tailored shells.
See CPANPLUS::Shell::Default if you are looking for a ready-made interactive interface.
Unless otherwise noted, all functions which accept the modules argument accept module array elements in the form of strings or module objects. Strings containing characters other than letters, digits, underscores and colons will be treated as distribution files.
So, for example, the following are all valid values for modules:
['/K/KA/KANE/Acme-POE-Knee-1.10.zip']
[$module_object, 'XML::Twig']
In general these methods return hash references where the keys correspond to the names of listed modules, or, in the case of distributions, the name of the distribution from the CPAN author id directory, as returned by the pathname method.
pathname
This creates and returns a backend object.
Arguments may be provided to override CPAN++ settings. Settings can also be modified with set_conf.
set_conf
Provide either a single CPANPLUS::Configure object:
my $backend = new CPANPLUS::Backend($config);
or use the following syntax:
my $backend = new CPANPLUS::Backend(conf => {debug => 0, verbose => 1});
Refer to CPANPLUS::Configure for a list of available options.
This function returns a CPANPLUS::Error object which maintains errors and warnings for this backend session.
Be aware that you should flush the error and warning caches for long-running programs.
See CPANPLUS::Error for details on using the error object.
This function returns a CPANPLUS::Configure object for the current invocation of Backend.
See CPANPLUS::Configure for available methods and note that you modify this object at your own risk.
This method will return a hash reference where each key in the hash is a module name and the values are module objects.
Refer to "MODULE OBJECTS" for more information on using module objects.
This function returns a hash reference with all authors. Each key corresponds to a CPAN identification. The values are author objects.
Refer to "AUTHOR OBJECTS" for more information on using author objects.
The search function accepts the following arguments:
type
This indicates what type of search should be performed. Any module object key may be provided as a type. The most common types are author and module. For a complete list, refer to "MODULE OBJECTS".
list
This argument indicates what should be searched for. Multiple strings are joined in an 'or' search--modules which match any of the patterns are returned. An 'and' search can be performed with multiple searches by the use of the data argument.
Search strings should be specified as regular expressions. If your version of perl supports it, you can use introduce flags with the (?f:) syntax. Refer to perlre for more information.
data
In order to perform a search which matches more than pattern (and), as opposed to matching any pattern supplied (or) as the list argument does, first search on one pattern, then perform the second search with the results of the first search input via the optional argument data.
authors_only
With this flag, searches of type author can be made to return a hash reference of author objects instead of module objects. By default, its value is false. The results of an author_only search can not be used as data for subsequent searches.
It returns a hash reference of module objects which matched any of the list criteria.
See "GENERAL NOTES" for more information about methods with modules arguments.
Values of the returned hash reference are 0 for unavailable modules, or hash references containing the following keys:
Author
The CPAN identification of the module author.
Description
The description of the module. If one was not provided, the description will be None given.
Development Stage
The stage of development the module is in. This detail is expanded from dslip information.
Interface Style
The interface style of the module. This detail is expanded from dslip information.
Language Used
The language used in the module. This detail is expanded from dslip information.
Package
The package that the module is a part of.
Support Level
The level at which support is offered for the module. This detail is expanded from dslip information.
Version
The version of the module. If the version information is not available, the version will be None given.
This field is only available for modules, not distributions.
For example, the module details for Apache::Leak look like this:
Author => 'DOUGM', Development Stage => 'Beta testing', Description => 'Memory leak tracking routines', Version => '1.00', Package => 'mod_perl-1.26.tar.gz', Language Used => 'C and perl, a C compiler will be needed', Interface Style => 'plain Functions, no references used', Support Level => 'Mailing-list'
The values this method returns are the contents of the readme files, or 0 for errors.
Install is a shortcut for performing fetch, extract and make on the specified modules.
fetch
extract
make
Optional arguments can be used to override configuration information.
Identify the program to use for make.
makeflags
Flags to use with make; may be a string, a hash reference, or an array reference. In other words, all three forms below are equivalent:
makeflags => '--quiet UNINST=1' makeflags => [ '--quiet', 'UNINST=1' ] makeflags => { '--quiet' => undef, 'UNINST' => 1 }
makemakerflags
Flags for MakeMaker may be a string, an array reference, or a hash reference, just like makeflags. An example argument for MakeMaker is { INST_LIB => '/home/ann/perl/lib/' }. See ExtUtils::MakeMaker for a complete list of possible arguments.
{ INST_LIB => '/home/ann/perl/lib/' }
Note that individual modules may provide their own additional flags.
perl
The path to Perl to use.
force
Force downloads even if files of the same name exist and force installation even if tests fail by setting force to a true value.
fetchdir
The directory fetched files should be stored in. By default it will store to the directory you started from.
extractdir
The directory files will be extracted into. For example, if you provide /tmp as an argument and the file being extracted is POE-0.17.tar.gz, the extracted files will be in /tmp/POE-0.17.
/tmp
POE-0.17.tar.gz
/tmp/POE-0.17
target
The objective of this attempt. It can be one of makefile, make, test, install (the default) or skiptest. Each target except skiptest implies all preceding ones.
makefile
test
install
skiptest
The special skiptest target has the same meaning as install, but will skip the test step.
prereq_target
This argument is the objective when making prerequisite modules. It takes the same range of values as target and also defaults to install. Usually install is the correct value, or the parent module won't make properly, but you may want to set it to skiptest if some of the prerequisites are known to fail.
The values of the returned hash reference are 1 for success or 0 for failure.
Note that a failure does not identify the source of the problem, which could be caused by a dependency rather than the named module. It also does not indicate in what stage of the installation procedure the failure occurred. For more detailed information it is necessary to examine the error object.
This function will retrieve the distributions that contains the modules specified with the modules argument. Refer to "GENERAL NOTES" for more information about methods with modules arguments.
modules
The remaining arguments are optional. A true value for force means that pre-existing files will be overwritten. Fetchdir behaves like the install argument of the same name.
The method will return a hash reference; values are either the fully qualified path plus the file name of the saved module, or--in the case of a failure--0.
Here is an example of a successful return value:
'.\\Acme-POE-Knee-1.10.zip'
Given the full local path and file name of a module, this function will extract it.
A hash reference will be returned. Keys are the files specified. If successful, the value is the directory the file was extracted to. Failure results in a value of 0.
Extractdir is optional and behaves like the install argument of the same name.
This function will attempt to install the module in the specified directory with perl Makefile.PL, make, make test, and make install.
perl Makefile.PL
make test
make install
Optional arguments are described fully in install.
The method returns a hash reference. Directory names are keys and values are boolean indications of status.
This function uninstalls the modules specified. There are three possible arguments for type: prog, man and all which specify what files should be uninstalled: program files, man pages, or both. The default type is all.
It returns a hash reference where the value is 1 for success or 0 for failure.
See "GENERAL NOTES" for more information about this method.
This function lists all files belonging to a module if the module is installed. See "GENERAL NOTES" for more information about this method.
It returns a hash reference. The value will be 0 if the module is not installed. Otherwise, it returns an array reference of files as shown below.
[ 'C:\\Perl\\site\\lib\\Acme\\POE\\demo_race.pl', 'C:\\Perl\\site\\lib\\Acme\\POE\\Knee.pm', 'C:\\Perl\\site\\lib\\Acme\\POE\\demo_simple.pl' ];
This provides a list of all distributions by the author of the module (given in the form of the CPAN author identification). This information is provided by the CHECKSUMS file in the authors directory.
It returns a hash reference where each key is the name of a distribution and each value is a hash reference containing additional information: the last modified time, the CPAN short name, md5 and the distribution size in kilobytes.
For example, the CPAN author id 'KANE' might return the following:
{ 'Acme-POE-Knee-1.10.zip' => { 'mtime' => '2001-08-23', 'shortname' => 'acmep110.zip', 'md5' => '6314eb799a0f2d7b22595bc7ad3df369', 'size' => '6625' }, 'Acme-POE-Knee-1.00.zip' => { 'mtime' => '2001-08-13', 'shortname' => 'acmep100.zip', 'md5' => '07a781b498bd403fb12e52e5146ac6f4', 'size' => '12230' }, }
Given a CPAN author identification, this function returns the modules by the author specified. Multiple authors may be specified.
It returns a hash reference where each key is a module name and each value is a module object.
This function queries the CPAN tester database at http://testers.cpan.org/ for test results of specified module objects, module names or distributions.
The optional argument all_versions controls whether all versions of a given distribution should be grabbed. It defaults to false.
all_versions
The function returns a hash reference. See "GENERAL NOTES" for more information about this method.
The values are themselves array references, the keys to which are the distribution name and version.
The values are hash references, the keys to which are the operating system name, operating system version and the architecture name.
The values are the status of the test, which can be one of the following: UNKNOWN, PASS, FAIL or NA.
For example,
$cp->reports(modules => [ 'CPANPLUS' ], all_versions => 1);
might return the following data structure:
{ 'CPANPLUS' => [ { 'grade' => 'PASS', 'dist' => 'CPANPLUS-0.031', 'platform' => 'freebsd 4.5-release i386-freebsd' }, { 'grade' => 'FAIL', 'dist' => 'CPANPLUS-0.03', 'platform' => 'freebsd 4.2-stable i386-freebsd', 'details' => 'http://testers.cpan.org/search?request=dist&dist=CPANPLUS#0.03+freebsd+4.2-stable+i386-freebsd' }, { 'grade' => 'PASS', 'dist' => 'CPANPLUS-0.01', 'platform' => 'linux 2.4.8-11mdkenter i386-linux' }, { 'grade' => 'PASS', 'dist' => 'CPANPLUS-0.01', 'platform' => 'MSWin32 4.0 MSWin32-x86-multi-thread', 'details' => 'http://testers.cpan.org/search?request=dist&dist=CPANPLUS#0.01+MSWin32+4.0+MSWin32-x86-multi-thread' }, ] }
This function can be used to see if your installation of a specified module is up-to-date. See "GENERAL NOTES" for more information about this method.
Values of the returned hash reference may be undef if the module is not installed, or a hash reference. The hash reference contains the following keys: uptodate, version and file. Their values are 0 or 1 if the file is not up-to-date or is up-to-date, the number of the most recent version found on the CPAN, and the file in which the most recent version was found.
For example, assuming you have Acme::POE::Knee but not XML::Twig installed, and provide the argument ['Acme::POE::Knee', 'XML::Twig' the following data structure might be returned:
['Acme::POE::Knee', 'XML::Twig'
{ 'XML::Twig' => undef, 'Acme::POE::Knee' => { 'version' => '1.10', 'file' => 'C:\\Perl\\site\\lib\\Acme\\POE\\Knee.pm', 'uptodate' => 1 } }
See "GENERAL NOTES" for information about the modules argument or the keys of the returned hash reference.
Hash reference values will be either an empty array reference (if no files are missing), an array reference containing the missing files, or 0 if there was an error (such as the module not being installed).
It is probably best to use the results of the installed method because not all modules have proper names. For instance, 'LWP' is installed as 'Libwww'.
installed
This function returns all modules currently installed on your system.
The values in the returned hash reference are module objects.
If there was an ambiguity in finding the object, the value will be 0. An example of an ambiguous module is LWP, which is in the packlist as 'libwww-perl', along with many other modules.
This method allows flushing of caches. There are several things which can be flushed:
methods
The return status of methods which have been attempted, such as different ways of fetching files. It is recommended that automatic flushing be used instead.
uris
The return status of URIs which have been attempted, such as different hosts of fetching files. It is recommended that automatic flushing be used instead.
Information about modules such as prerequisites and whether installation succeeded, failed, or was not attempted.
path
The location of modules on the local system.
List of archives extracted.
all
Flush all three of the aforementioned caches.
This method refetches and reloads index files. It accepts one optional argument. If the value of update_source is true, CPANPLUS will download new source files regardless. Otherwise, if your current source files are up-to-date according to your config, it will not fetch them.
update_source
It returns 0 in the event of failure, and 1 for success.
This function returns the path, from the CPAN author id, of the distribution. It returns 0 for failure.
The value for to can be a module name, a module object, or part of a distribution name. For instance, the following values for to would all return '/M/MS/MSCHWERN/Test-Simple-0.42.tar.gz' (as of this writing):
'/M/MS/MSCHWERN/Test-Simple-0.42.tar.gz'
'Test::Simple'
$cp-module_tree->{'Test::Simple'}>
$cp-
'Test-Simple-0.42.tar.gz'
The first two examples will return the most recent version of the module, whereas the last will explicitly return version 0.42.
Module objects belong to CPANPLUS::Internals::Module but should not be created manually. Instead, use the objects returned by Backend methods, such as module_tree.
For many Backend functions, it is also possible to call the function with a module object instead of a Backend object. In this case the 'modules' argument of the Backend function is no longer valid--the (single) module is assumed to be the object through which the function is accessed. All other arguments available for the Backend method may be used.
The functions return almost what the Backend method returns, except whereas the Backend method returns a hash reference where each module name is a key, the Module methods return only the value, because they can only be called on one module at a time.
For example, $cp->readme(modules => 'Gtk'); will return
$cp->readme(modules => 'Gtk');
{ 'Gtk' => $some_result }
but the module method, $gtk_module_obj->readme(); will return simply
$gtk_module_obj->readme();
$some_result
The following methods are available:
$module_object->details()
$module_object->readme()
$module_object->distributions()
$module_object->files()
Note that this method only works for installed modules, since it reads the .packlist present on the local disk.
$module_object->fetch()
$module_object->install()
$module_object->uninstall()
$module_object->uptodate()
$module_object->reports()
$module_object->pathname()
This method is an exception to the rule in that the module object does not replace the modules argument but the to argument.
$module_object->modules()
This method is another exception in that the module object replaces the authors argument instead of the modules argument.
In addition to these methods, access methods are available for all the keys in the module object. These are simply the name of the key and return the value.
For example, $module_object->path() for the object shown below would return 'L/LB/LBROCARD'.
$module_object->path()
'L/LB/LBROCARD'
Here is a sample dump of the module object for Acme::Buffy:
'Acme::Buffy' => bless( { 'path' => 'L/LB/LBROCARD', 'description' => 'An encoding scheme for Buffy fans', 'dslip' => 'Rdph', 'status' => '', 'prereqs' => {}, 'module' => 'Acme::Buffy', 'comment' => '', 'author' => 'LBROCARD', '_id' => 6, 'package' => 'Acme-Buffy-1.2.tar.gz', 'version' => 'undef' }, 'CPANPLUS::Internals::Module' )
The module object contains the following information:
author
The CPAN identification for the module author.
comment
This is any comment which appears in the source files; it is largely unused.
description
The description of the module.
dslip
Information on development stage, support level, language used, interface style and public license.
The dslip consists of single-letter codes which can be expanded with the details method from either Backend or Modules.
details
module
The name of the module.
package
The file name of the module on CPAN.
The path of the module on CPAN, starting from the CPAN author id directory. For example, if a module was found in /pub/mirror/CPAN/authors/id/I/IR/IROBERTS/Crypt-OpenSSL-RSA-0.12.tar.gz the value for path would be just I/IR/IROBERTS.
/pub/mirror/CPAN/authors/id/I/IR/IROBERTS/Crypt-OpenSSL-RSA-0.12.tar.gz
I/IR/IROBERTS
prereqs
Currently not in use.
status
version
The version of the module.
_id
The internal identification number of the Backend object that created this object.
Author objects belong to CPANPLUS::Internals::Author but should not be created manually. Instead, use the objects returned by Backend methods such as author_tree.
Functions which are available for author objects are also available for Backend objects. Calling through the author object eliminates the need to use the authors argument.
Like the Module object methods, the Author object methods return the same results as the Backend methods, minus one level of references.
The following methods may be called with an Author object:
$author_object->distributions()
$author_object->modules()
In addition to these methods, access methods are available for all the keys in the author object. These are simply the name of the key and return the value.
Here is a sample dump of the author object for KANE:
'KANE' => bless( { 'cpanid' => 'KANE', '_id' => 6, 'email' => 'boumans@frg.eur.nl', 'name' => 'Jos Boumans' }, 'CPANPLUS::Internals::Author' );
The author object contains the following information:
The author's email address.
The author's full name.
This module by Jos Boumans <kane@cpan.org>.
This pod text by Ann Barcomb <kudra@cpan.org>.
The CPAN++ interface (of which this module is a part of) is copyright (c) 2001, 2002 Jos Boumans <kane@cpan.org>. All rights reserved.
This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.
CPANPLUS::Shell::Default, CPANPLUS::Configure, CPANPLUS::Error, ExtUtils::MakeMaker, CPANPLUS::Internals::Module, perlre http://testers.cpan.org
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install CPANPLUS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPANPLUS
CPAN shell
perl -MCPAN -e shell install CPANPLUS
For more information on module installation, please visit the detailed CPAN module installation guide.