CPANPLUS::Backend - Object-oriented interface for CPAN++
use CPANPLUS::Backend; my $cp = new CPANPLUS::Backend; ##### Methods which return trees of objects ##### my $module_obj = $cp->module_tree()->{'Dir::Purge'}; my $all_authors = $cp->author_tree(); ##### Methods which return objects ##### my $err = $cp->error_object(); my $conf = $cp->configure_object(); ### Methods returning RV objects 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 $bundle = $cp->autobundle(); 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 ## # Backend method my $fetch_result = $cp->fetch(modules => ['Dir::Purge']) my $rv = $fetch_result->rv(); # Module method # The value of $rv->{'Dir::Purge'} is returned by the module method my $module = $cp->module_tree()->{'Dir::Purge'}; $module->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']); my $result = $mods_by_same_auth->rv(); my $dt = $cp->module_tree()->{'Debug::Trace'}; $$result{'JV'} = $dt->modules(); $$result{'JV'} = $all_authors->{'JV'}->modules(); ## # Backend method my $dists_by_same_auth = $cp->distributions(authors => ['KANE']); ##### Methods with other return values ##### ### Backend and Module methods # Backend method my $path = $cp->pathname(to => 'C::Scan'); my $reload = $cp->reload_indices(update_source => 1); ### Module methods my $result = $module_obj->extract();
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.
If you prefer to use a package manager to manage distributions, refer to CPANPLUS::Dist.
The CPANPLUS::Backend interface will become stable with the release of CPANPLUS version 1.0.
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 the return values of these methods will be a CPANPLUS::Backend::RV object. If the RV object cannot be created, undef will be returned. Versions before 0.04 returned hash references.
A synopsis of the result can be obtained by using the RV method ok, which will return a boolean value indicating success or failure. For instance:
ok
my $err = $cp->error_object(); ... my $result = $cp->some_backend_function(modules => ['Acme::Comment']); print 'Error: '.$err->stack() unless $result->ok();
In boolean context, the RV object returns the value of ok, so the last line could actually be written like this:
print 'Error: '.$err->stack() unless ($result);
If you want to examine the results in more detail, please refer to CPANPLUS::Backend::RV for descriptions of the other methods available.
This creates and returns a backend object.
Arguments may be provided to override CPAN++ settings.
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.
See "GENERAL NOTES" for more information about methods with modules arguments.
Values for the rv section of the RV object are 0 for unavailable modules. Available modules have hash references with 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 rv() values this method returns are the contents of the readme files, or 0 for errors.
rv()
Install is a shortcut for performing fetch, extract and make on the specified modules. If a full filename is supplied, it will be treated as an autobundle.
fetch
extract
make
Optional arguments can be used to override configuration information.
format
Run install with the format of the given package manager. This is handy when you're, for example, on windows and like your perl package management done by PPM. Entering a format will make CPANPLUS build a package conforming to that package managers specifications and install it as such.
PPM
CPANPLUS
See CPANPLUS::Dist for details on what package managers have interfaces ot them available.
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 of the perl to use. This will default to $^X (ie. the perl used to start the script).
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. It will also force installation even if the module is up-to-date.
fetchdir
The directory fetched files should be stored in. By default it will store in your cpanplus home directory. If called from the command line (as in perl -MCPANPLUS -e'fetch POE'), it will default to the current working directory.
perl -MCPANPLUS -e'fetch POE'
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, or install (the default). Each target implies all the preceding ones.
makefile
test
install
skiptest
If this flag is set to true, tests will be skipped.
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.
If the prerequisite target is set to test, prerequisites won't be installed, but their build directory will be added to the PERL5LIB environment variable, so it will be in the path. This option is useful when building distributions.
Note that a failure in ok() 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 RV and/or error objects.
ok()
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 return value for rv() will be a hash reference for each module; values are either the fully qualified path plus the file name of the saved module, or, in the case of failure, 0.
Here is an example of a successful return value:
'C:\\temp\\Acme-POE-Knee-1.10.zip'
Given the full local path and file name of a module, this function will extract it.
Successful rv() values will be the directory the file was extracted to.
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.
Below is an example of the data structure returned by rv():
{ 'D:\\cpanplus\\5.6.0\\build\\Acme-Bleach-1.12' => { 'install' => 1, 'dir' => 'D:\\cpanplus\\5.6.0\\build\\Acme-Bleach-1.12', 'prereq' => {}, 'overall' => 1, 'test' => 1 }
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.
rv() gives boolean indications of status for each module name key.
Note that uninstall only uninstalls the module you ask for -- It does not track prerequisites for you, nor will it warn you if you uninstall a module another module depends on!
uninstall
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.
The module's rv() value will be 0 if the module is not installed. Otherwise, it will be 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.
Here is a cropped example of the CPAN author id 'KANE':
... 'rv' => { 'KANE' => { 'CPANPLUS-0.033.tar.gz' => { 'md5-ungz' => 'ccf827622d95479d6c02aa2f851468f2', 'mtime' => '2002-04-30', 'shortname' => 'cpan0033.tgz', 'md5' => 'ce911062b432dcbf93a19a0f1ec87bbc', 'size' => '192376' }, 'Acme-POE-Knee-1.01.zip' => { 'mtime' => '2001-08-14', 'shortname' => 'acmep101.zip', 'md5' => '4ba5db4c515397ec1b841f7474c8f406', 'size' => '14246' }, 'Acme-Comment-1.00.tar.gz' => { 'md5-ungz' => '166b8df707a22180a46c9042bd0deef8', 'mtime' => '2002-05-12', 'shortname' => 'acmec100.tgz', 'md5' => 'dec0c064ba3055042fecffc5e0add648', 'size' => '6272' }, } }
Given a CPAN author identification, this function will return modules by the author specified as an RV 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 (fetching only reports for the current version).
all_versions
The rv() function will give the following data structure:
'Devel::Size' => [ { 'dist' => 'Devel-Size-0.54', 'grade' => 'PASS', 'platform' => 'linux 2.2.16c32_iii i586-linux' }, { 'dist' => 'Devel-Size-0.54', 'grade' => 'PASS', 'platform' => 'linux 2.4.16-6mdksmp i386-linux' }, { 'dist' => 'Devel-Size-0.54', 'grade' => 'PASS', 'platform' => 'solaris 2.7 sun4-solaris' }, { 'dist' => 'Devel-Size-0.54', 'grade' => 'PASS', 'platform' => 'solaris 2.8 sun4-solaris' } ]
The status of the test can be one of the following: UNKNOWN, PASS, FAIL or NA (not applicable).
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 for the module from rv() may be undef if the module is not installed, or a hash reference. The hash reference contains the following keys: uptodate, version and file.
The version is your currently installed version. The file is where the module is installed on your system. Uptodate is 1 if your version is equal to or higher than the most recent version found on the CPAN, and 0 if it is not.
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.
The rv() module 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 in question is not 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.
Values of modules returned by rv() will be the location of the module.
For example, the following code:
my $rv = $cp->installed(); print Dumper $rv->rv();
might give something like the following (example cropped):
$VAR1 = { ... 'URI::telnet' => '/usr/local/lib/perl5/site_perl/5.005/URI/telnet.pm' 'Tie::Array' => '/usr/local/lib/perl5/5.6.1/Tie/Array.pm', 'URI::file' => '/usr/local/lib/perl5/site_perl/5.005/URI/file.pm', ... }
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.
Creates a local mirror of CPAN, of only the most recent sources in a location you specify. If you set this location equal to a custom host in your CPANPLUS::Config you can use your local mirror to install from.
CPANPLUS::Config
It takes the following argument:
The location where to create the local mirror
Disable fetching of index files. This is ok if you don't plan to use the local mirror as your primary sites, or if you'd like uptodate index files be fetched from elsewhere.
Defaults to false.
Forces refetching of packages, even if they are there already.
Defaults to whatever setting you have in your CPANPLUS::Config.
Prints more messages about what it's doing.
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.
lib
This resets PERL5LIB which is changed to ensure that while installing modules they are in our @INC.
all
Flush all 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
This method autobundles your current installation as $cpanhome/$version/dist/autobundle/Snapshot_xxxx_xx_xx_xx.pm. For example, it might create:
D:\cpanplus\5.6.0\dist\autobundle\Snapshot_2002_11_03_03.pm
This function returns the path, from the CPAN author id, of the distribution when rv() is used. 0 is used 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.
Module methods return a subsection of what Backend methods return. The value of the module name key in the rv portion of the RV object is returned. For example, $cp->uptodate(modules => ['Devel::Size']); might return:
$cp->uptodate(modules => ['Devel::Size']);
bless( { 'args' => { 'modules' => [ 'Devel::Size' ] }, 'rv' => { 'Devel::Size' => { 'version' => '0.54', 'file' => '/usr/local/lib/perl5/site_perl/5.6.1/i386-freebsd/Dev el/Size.pm', 'uptodate' => 1 } }, '_id' => 1, 'type' => 'CPANPLUS::Backend::uptodate', 'ok' => '1' }, 'CPANPLUS::Backend::RV' );
but when called as the Module method $ds->uptodate(); just the following will be returned:
$ds->uptodate();
{ 'version' => '0.54', 'file' => '/usr/local/lib/perl5/site_perl/5.6.1/i386-freebsd/Devel/Size.pm', 'uptodate' => 1 };
Refer to the Backend methods to determine what type of data structure will be returned for the Module method of the same name.
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->extract()
In order to use this method, you must have first used fetch().
$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.
$module_object->status()
This method returns an CPANPLUS::Internals::Module::Status object, which provides methods to tell you about the current status of the module object. For example, where it has been saved to, what prereqs it has and so on.
CPANPLUS::Internals::Module::Status
Please refer to the CPANPLUS::Internals::Module::Status manpage for details.
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' => bless( {}, 'CPANPLUS::Internals::Module::Status' ), 'prereqs' => {}, 'module' => 'Acme::Buffy', 'comment' => '', 'author' => 'LBROCARD', '_id' => 6, 'package' => 'Acme-Buffy-1.2.tar.gz', 'version' => '1.3' }, '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, but this information is included in the return value for make() and install()
make()
install()
status
Internal storage for module 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 value of $rv{rv}{'Name'} where 'Name' corresponds to the name of the author (or module, in the case of the Module methods) and $rv is a return value object.
$rv{rv}{'Name'}
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, CPANPLUS::Backend::RV, CPANPLUS::Dist, 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.