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



NAME

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


SYNOPSIS

    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();


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.

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.


METHODS

GENERAL NOTES

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:

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:

    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 the CPANPLUS::Backend::RV manpage for descriptions of the other methods available.

new(CONFIGURATION)

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 the CPANPLUS::Configure manpage 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 the CPANPLUS::Error manpage for details on using the error object.

configure_object()

This function returns a CPANPLUS::Configure object for the current invocation of Backend.

See the CPANPLUS::Configure manpage 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.

Refer to MODULE OBJECTS for more information on using module objects.

author_tree()

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.

search(type => TYPE, list => [LIST], [data => PREVIOUS_RESULT], [authors_only => BOOL])

The search function accepts the following arguments:

details(modules => [LIST])

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:

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'

readme(modules => [LIST])

See GENERAL NOTES for more information about methods with modules arguments.

The rv() values this method returns are the contents of the readme files, or 0 for errors.

install(modules => [LIST], format => PM, make => PROGRAM, makeflags => FLAGS, makemakerflags => FLAGS, perl => PERL, force => BOOL, fetchdir => DIRECTORY, extractdir => DIRECTORY, target => STRING, prereq_target => STRING, skiptest => BOOL)

See GENERAL NOTES for more information about methods with modules arguments.

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.

Optional arguments can be used to override configuration information.

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.

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

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.

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'

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

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.

make(dirs => [DIRECTORIES], force => BOOL, makeflags => FLAGS, makemakerflags => FLAGS, perl => PERL, target => string, prereq_target => STRING)

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.

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
    }

uninstall(modules => [LIST], type => TYPE)

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!

See GENERAL NOTES for more information about this method.

files(modules => [LIST])

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'
    ];

distributions(authors => [CPAN_ID [CPAN_ID]])

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'
            },
        }
    }

modules(authors => [CPAN_ID [CPAN_ID]])

Given a CPAN author identification, this function will return modules by the author specified as an RV object.

reports(modules => [LIST], all_versions => BOOL)

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

See GENERAL NOTES for more information about this method.

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

uptodate(modules => [LIST])

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:

    {
        'XML::Twig' => undef,
        'Acme::POE::Knee' => {
            'version'  => '1.10',
            'file'     => 'C:\\Perl\\site\\lib\\Acme\\POE\\Knee.pm',
            'uptodate' => 1
        }
    }

validate(modules => [LIST])

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.

See GENERAL NOTES for more information about this method.

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.

local_mirror( path => WHERE, [no_index_files => BOOL, force => BOOL, verbose => BOOL] )

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.

It takes the following argument:

path
The location where to create the local mirror

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

force
Forces refetching of packages, even if they are there already.

Defaults to whatever setting you have in your CPANPLUS::Config.

verbose
Prints more messages about what it's doing.

Defaults to whatever setting you have in your CPANPLUS::Config.

flush(CACHE_NAME)

This method allows flushing of caches. There are several things which can be flushed:

reload_indices([update_source => BOOL])

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.

autobundle()

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

pathname(to => MODULE)

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):

The first two examples will return the most recent version of the module, whereas the last will explicitly return version 0.42.


MODULE OBJECTS

Methods

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:

    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:

    {
        '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:

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

Object

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 OBJECTS

Methods

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.

The following methods may be called with an Author object:

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.

Object

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:

cpanid

The CPAN identification for the module author.

email

The author's email address.

name

The author's full name.

_id

The internal identification number of the Backend object that created this object.


AUTHORS

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

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


COPYRIGHT

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.


SEE ALSO

the CPANPLUS::Shell::Default manpage, the CPANPLUS::Configure manpage, the CPANPLUS::Error manpage, the CPANPLUS::Backend::RV manpage, the CPANPLUS::Dist manpage, the ExtUtils::MakeMaker manpage, the CPANPLUS::Internals::Module manpage, the perlre manpage http://testers.cpan.org

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