NAME

CPANPLUS::Backend::RV - Return Value class for CPAN++

SYNOPSIS

    my $rv = $backend_obj->some_function();

    unless ($rv->ok()) {
        warn "There was an error with ".$rv->type().".  Examining it.\n";
        my $calling_args = $rv->args();
        my $full_return = $rv->rv();

        # See what extra method calls are valid for this object
        my $allowed = $rv->can();

        # Refer to the 'rv' method for documentation on key accessors
        my $fetch_results = $rv->fetch();
        my $make_results = $rv->make();
        ...
    }

DESCRIPTION

A return value class for CPANPLUS to facilitate error checking and to handle the many possible values in an expandable manner. The RV object is provided as a return value for most CPANPLUS::Backend functions.

METHODS

ok()

This is the most basic method of the RV class. It returns a boolean value indicating overall success or failure.

It is also possible to get the result of ok simply by checking the RV object in boolean context. Thus these two statements are equivalent:

    # $return is a RV object

    if ($return) ...
    if ($return->ok()) ...

can()

This method returns an array ref of all extra methods which are valid for the object.

For example, the extract method will be available only if an action including extraction was attempted.

Refer to rv() for more information about what sorts of methods will be available.

rv()

This method returns a hash reference of the original return value. The structure is a bit complex, so it is recommended that you delve in to it only if you receive a failure value from ok.

Methods also exist for all of the 'top level keys' (in reality the keys one level below the module names). Examine this dumper of one of the more elaborate results of rv:

    {
        'Exporter::Lite' => {
            'install' => '1',
            'extract' => 'D:\\cpanplus\\5.6.0\\build\\Exporter-Lite-0.01',
            'md5' => 1,
            'fetch' => 'D:\\cpanplus\\authors\\id\\M\\MS\\MSCHWERN\\Exporter-Lite-0.01.tar.gz',
            'make' => {
                'dir' => 'D:\\cpanplus\\5.6.0\\build\\Exporter-Lite-0.01',
                'prereq' => {},
                'makefile' => 1,
                'overall' => 1,
                'make' => 1,
                'test' => 1
            },
        },
        'UNIVERSAL::exports' => {
            'install' => '1',
            'extract' => 'D:\\cpanplus\\5.6.0\\build\\UNIVERSAL-exports-0.03',
            'md5' => 1,
            'fetch' => 'D:\\cpanplus\\authors\\id\\M\\MS\\MSCHWERN\\UNIVERSAL-exports-0.03.tar.gz',
            'make' => {
                'dir' => 'D:\\cpanplus\\5.6.0\\build\\UNIVERSAL-exports-0.03',
                'prereq' => {
                    'Exporter::Lite' => '0.01'
                },
                'makefile' => 1,
                'overall' => 1,
                'make' => 1,
                'test' => 1
            },
        }
    };

In this example, the 'top level keys' include install, extract, md5, fetch, make and ppm. A summary of all md5s, for example, could be fetched with the following code:

    my $md5s = $rv->md5();

This will return a hash reference where each key corresponds to the module name and each value is the value for that module. The example code used on the dumper above would return:

    {
        'UNIVERSAL::exports' => 1,
        'Exporter::Lite' => 1
    }

A warning will be given if the key that is being accessed doesn't exist.

type()

This function will return the type of return value, usually the name of the method that generated it.

args()

This will return a hash reference of the arguments that were passed to the method. Note that the arguments may have been modified by the input checker.

For example, the following code:

    my $rv = $backend_obj->distributions(authors => ['KANE', 'KUDRA']);

generates this structure for args:

    {
        'authors' => [
            'KANE',
            'KUDRA'
        ]
    }

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

cpanm CPANPLUS

perl -MCPAN -e shell
install CPANPLUS