1package CPANPLUS::Backend::RV;
2
3use strict;
4use vars qw[$STRUCT $VERSION];
5$VERSION = "0.9912";
6
7use CPANPLUS::Error;
8use CPANPLUS::Internals::Constants;
9
10use IPC::Cmd                    qw[can_run run];
11use Params::Check               qw[check];
12
13use base 'Object::Accessor';
14
15local $Params::Check::VERBOSE = 1;
16
17
18=pod
19
20=head1 NAME
21
22CPANPLUS::Backend::RV - return value objects
23
24=head1 SYNOPSIS
25
26    ### create a CPANPLUS::Backend::RV object
27    $backend_rv     = CPANPLUS::Backend::RV->new(
28                                ok          => $boolean,
29                                args        => $args,
30                                rv          => $return_value
31                                function    => $calling_function );
32
33    ### if you have a CPANPLUS::Backend::RV object
34    $passed_args    = $backend_rv->args;    # args passed to function
35    $ok             = $backend_rv->ok;      # boolean indication overall
36                                            # result of the call
37    $function       = $backend_rv->function # name of the calling
38                                            # function
39    $rv             = $backend_rv->rv       # the actual return value
40                                            # of the calling function
41
42=head1 DESCRIPTION
43
44This module provides return value objects for multi-module
45calls to CPANPLUS::Backend. In boolean context, it returns the status
46of the overall result (ie, the same as the C<ok> method would).
47
48=head1 METHODS
49
50=head2 new( ok => BOOL, args => DATA, rv => DATA, [function => $method_name] )
51
52Creates a new CPANPLUS::Backend::RV object from the data provided.
53This method should only be called by CPANPLUS::Backend functions.
54The accessors may be used by users inspecting an RV object.
55
56All the argument names can be used as accessors later to retrieve the
57data.
58
59Arguments:
60
61=over 4
62
63=item ok
64
65Boolean indicating overall success
66
67=item args
68
69The arguments provided to the function that returned this rv object.
70Useful to inspect later to see what was actually passed to the function
71in case of an error.
72
73=item rv
74
75An arbitrary data structure that has the detailed return values of each
76of your multi-module calls.
77
78=item function
79
80The name of the function that created this rv object.
81Can be explicitly passed. If not, C<new()> will try to deduce the name
82from C<caller()> information.
83
84=back
85
86=cut
87
88sub new {
89    my $class   = shift;
90    my %hash    = @_;
91
92    my $tmpl = {
93        ok          => { required => 1, allow => BOOLEANS },
94        args        => { required => 1 },
95        rv          => { required => 1 },
96        function    => { default => CALLING_FUNCTION->() },
97    };
98
99    my $args    = check( $tmpl, \%hash ) or return;
100    my $self    = bless {}, $class;
101
102#    $self->mk_accessors( qw[ok args function rv] );
103    $self->mk_accessors( keys %$tmpl );
104
105    ### set the values passed in the struct ###
106    while( my($key,$val) = each %$args ) {
107        $self->$key( $val );
108    }
109
110    return $self;
111}
112
113sub _ok { return shift->ok }
114#sub _stringify  { Carp::carp( "stringifying!" ); overload::StrVal( shift ) }
115
116### make it easier to check if($rv) { foo() }
117### this allows people to not have to explicitly say
118### if( $rv->ok ) { foo() }
119### XXX add an explicit stringify, so it doesn't fall back to "bool"? :(
120use overload bool       => \&_ok,
121#             '""'       => \&_stringify,
122             fallback   => 1;
123
124=pod
125
126=head1 BUG REPORTS
127
128Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
129
130=head1 AUTHOR
131
132This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
133
134=head1 COPYRIGHT
135
136The CPAN++ interface (of which this module is a part of) is copyright (c)
1372001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
138
139This library is free software; you may redistribute and/or modify it
140under the same terms as Perl itself.
141
142=cut
143
1441;
145