NAME

CPANPLUS::Backend - Object-oriented interface for CPAN++

SYNOPSIS

    use CPANPLUS::Backend;

    my $cp = new CPANPLUS::Backend;


    ### Backend methods which return objects ###

    my $err  = $cp->error_object();
    my $conf = $cp->configure_object();

    my $all_modules = $cp->module_tree(); 
    my $all_authors = $cp->author_tree();


    ### Backend 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);

    $cp->flush('modules');

    $extract = $cp->extract(files => [$fetch_result->{B::Tree},
                                      '/tmp/POE-0.17.tar.gz']);

    $make = $cp->make(dirs => ['/home/munchkin/Data-Denter-0.13']);


    ### Backend methods with corresponding Module methods ###

    my $fetch_result =
      $cp->fetch(modules  => ['/K/KA/KANE/Acme-POE-Knee-1.10.zip'],
                 fetchdir => '/tmp');              # Backend method
    $fetch_result = $all_modules{'Gtk'}->fetch();  # Module method

    my $install_result = 
      $cp->install(modules => ['GD', 'Gtk'], force => 1); # Backend 
    $install_result = $all_modules{'GD'}->install();      # Module

    my $info = $cp->details(modules => ['Math::Random']); # Backend
    $info    = $all_modules{'Math::Random'}->details();   # Module


    ### Additional Module and Author methods ###

    my $mods_by_same_auth = $all_modules{'LEGO::RCX'}->modules();
    $mods_by_same_auth    = $all_authors{'JQUILLAN'}->modules();

    my $dists_by_same_auth = $all_modules{'Acme::USIG'}->distributions();
    $dists_by_same_auth    = $all_authors{'RCLAMP'}->distributions();

    my $files_in_dist = $all_modules{'Mail::Box'}->files();

    my $version_is_cur = $all_modules{'ControlX10::CM11'}->uptodate();

DESCRIPTION

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.

METHODS

new(CONFIGURATION);

This creates and returns a backend object.

Arguments may be provided to override CPAN++ settings. Settings can also be modified with 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.

error_object();

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.

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

module_tree();

This method will return a hash reference where each key in the hash is a module name and the values are module objects.

Module objects belong to CPANPLUS::Internals::Module but should not be created manually. Instead, use the objects returned by Backend methods.

The following methods may be called with a module object:

$module_object->details()

This method returns a hash reference with more details about the module.

It strongly resembles the CPANPLUS::Backend method details. The Backend method returns a hash reference of module names where each value is another hash reference--the same hash reference returned by this method.

Refer to the CPANPLUS::Backend method details for a description of module details.

$module_object->distributions()

This provides a list of all distributions by the author of the module (object). 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'
                                    },
    }

$module_object->modules()

This returns other modules by the author of this module (object) in the form of a hash reference where each key is the name of a module and each value is a module object.
$module_object->files()

This function lists all files belonging to a module if the module is installed. It returns 0 if it is not installed. Otherwise, it returns an array references of files like the one in the following example:
```
    [
        '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'
    ];
```
$module_object->fetch()

This method will attempt to fetch the module. It returns 0 in the event of failure, or the path of the file for success. An example return value:
```
    '.\\Acme-POE-Knee-1.10.zip'
```
This method is similar to the CPANPLUS::Backend method fetch.
$module_object->install()

This method will try to install the module. It returns 1 for success and 0 for failure.

A similar result can be achieved through the CPANPLUS::Backend method install.
$module_object->uptodate()

This method will check if the currently installed version of the module is the most recent distribution. It returns 1 if it is and 0 if it is not.

All these methods can take the same arguments as the corresponding Backend methods. For example, the following is valid:

    $module_object->install(force=>1);

author_tree();

This function returns a hash reference with all authors. Each key corresponds to a CPAN identification. The values are author objects.

Author objects belong to CPANPLUS::Internals::Author but should not be created manually. Instead, use the objects returned by Backend methods.

The following methods may be called with an author object:

$author_object->distributions()

This method will list all distributions by an author. It returns a hash reference where each key is the name of a distribution and each value is a hash reference with additional information.

Refer to the module object method distributions for an example return.
$author_object->modules()

This method will return a a hash reference where each key is the name of a module and each value is a module object.

Refer to the documentation for module_tree() for more information on module objects.

All these methods can take the same arguments as the corresponding Backend methods.

details(modules => [LIST]);

Given a list of strings of module names, this function will return a hash reference containing detailed information about the modules in the list.

Keys correspond to the modules specified in the call, while values are hash references which contain the following keys:

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.

For example, the module details for Apache::Leak look like this:

    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'

install(modules => [LIST], make => PROGRAM, makeflags => FLAGS, makemakerflags => HASHREF_OF_FLAGS, perl => PERL, force => BOOL fetchdir => DIRECTORY, extractdir => DIRECTORY);

Install is a shortcut for performing fetch, extract and make on the specified modules. See the documentation on these methods for more information.

Optional arguments can be used to override configuration information.

make

Identify the program to use for make.
makeflags

Flags to use with make. An example is --quiet.
makemakerflags

Flags for MakeMaker. An example argument for MakeMaker is INST_LIB => '/home/ann/perl/lib/'. See ExtUtils::MakeMaker for a complete list of possible arguments.

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

Install returns a hash reference. The keys are the modules specified and the values are either 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.

fetch(modules => [LIST], force => BOOL, fetchdir => DIRECTORY);

This function will retrieve the modules specified with the modules argument. Modules can be specified by name or by a fully qualified file name relative to the /authors/id directory on a CPAN mirror. Names which contain a / will be treated as files.

The first example is a module by name, and the second is a fully qualified file name beginning with a /.

Acme::POE::Knee
/K/KA/KANE/Acme-POE-Knee-1.10.zip

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 where keys are the names of the modules in the list. The value will either be the fully qualified path plus the file name of the saved module, or--in the case of a failure--0.

extract(files => [FILES], extractdir => DIRECTORY);

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.

make(dirs => [DIRECTORIES], force => BOOL, makeflags => FLAGS, makemakerflags => FLAGS, perl => PERL);

This function will attempt to install the module in the specified directory with perl Makefile.PL, make, make test, and 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.

flush(CACHE_NAME);

This method allows flushing of caches. There are three 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.
modules

Information about modules such as prerequisites and whether installation succeeded, failed, or was not attempted.
path

The location of modules on the local system.
extract

List of archives extracted.
all

Flush all three of the aforementioned caches.

AUTHORS

This module by Jos Boumans <kane@cpan.org>.

This pod text by Ann Barcomb <kudra@cpan.org>.

COPYRIGHT

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)