++ed by:
JNBEK DAGOLDEN EMAZEP KEEDI YUSRIDEB

6 PAUSE users
6 non-PAUSE users.

Jos Boumans

NAME

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

SYNOPSIS

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

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

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:

  • ['/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.

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.

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:

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

details(modules => [LIST]);

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'

readme(modules => [LIST]);

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

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

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

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.

Optional arguments can be used to override configuration information.

  • make

    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.

    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.

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

    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.

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

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

The method returns a hash reference. Directory names are keys and values are boolean indications of status.

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.

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.

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.

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

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.

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

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

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.

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.

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

uptodate(modules => [LIST]);

See "GENERAL NOTES" for more information about this method.

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:

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

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.

See "GENERAL NOTES" for more information about this method.

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.

flush(CACHE_NAME);

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.

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

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.

It returns 0 in the event of failure, and 1 for success.

pathname(to => MODULE);

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

  • 'Test::Simple'

  • $cp-module_tree->{'Test::Simple'}>

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

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.

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

    { 'Gtk' => $some_result }

but the module method, $gtk_module_obj->readme(); will return simply

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

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

  • module

    The name of the module.

  • package

    The file name of the module on CPAN.

  • path

    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.

  • prereqs

    Currently not in use.

  • status

    Currently not in use.

  • version

    The version of the module.

  • _id

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

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

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

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:

Around line 1731:

'=item' outside of any '=over'

Around line 1786:

You forgot a '=back' before '=head1'