File Coverage

lib/CPANPLUS/Backend/RV.pm
Criterion Covered Total %
statement 34 34 100.0
branch 1 2 50.0
condition n/a
subroutine 10 10 100.0
pod 1 1 100.0
total 46 47 97.8


line stmt bran cond sub pod time code
1             package CPANPLUS::Backend::RV;
2              
3 20     20   139 use strict;
  20         40  
  20         910  
4 20     20   127 use vars qw[$STRUCT $VERSION];
  20         46  
  20         1387  
5             $VERSION = "0.9914";
6              
7 20     20   147 use CPANPLUS::Error;
  20         44  
  20         1303  
8 20     20   203 use CPANPLUS::Internals::Constants;
  20         73  
  20         7188  
9              
10 20     20   154 use IPC::Cmd qw[can_run run];
  20         40  
  20         1460  
11 20     20   149 use Params::Check qw[check];
  20         37  
  20         962  
12              
13 20     20   140 use base 'Object::Accessor';
  20         44  
  20         7297  
14              
15             local $Params::Check::VERBOSE = 1;
16              
17              
18             =pod
19              
20             =head1 NAME
21              
22             CPANPLUS::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              
44             This module provides return value objects for multi-module
45             calls to CPANPLUS::Backend. In boolean context, it returns the status
46             of the overall result (ie, the same as the C method would).
47              
48             =head1 METHODS
49              
50             =head2 new( ok => BOOL, args => DATA, rv => DATA, [function => $method_name] )
51              
52             Creates a new CPANPLUS::Backend::RV object from the data provided.
53             This method should only be called by CPANPLUS::Backend functions.
54             The accessors may be used by users inspecting an RV object.
55              
56             All the argument names can be used as accessors later to retrieve the
57             data.
58              
59             Arguments:
60              
61             =over 4
62              
63             =item ok
64              
65             Boolean indicating overall success
66              
67             =item args
68              
69             The arguments provided to the function that returned this rv object.
70             Useful to inspect later to see what was actually passed to the function
71             in case of an error.
72              
73             =item rv
74              
75             An arbitrary data structure that has the detailed return values of each
76             of your multi-module calls.
77              
78             =item function
79              
80             The name of the function that created this rv object.
81             Can be explicitly passed. If not, C will try to deduce the name
82             from C information.
83              
84             =back
85              
86             =cut
87              
88             sub new {
89 1     1 1 12 my $class = shift;
90 1         42 my %hash = @_;
91              
92 1         40 my $tmpl = {
93             ok => { required => 1, allow => BOOLEANS },
94             args => { required => 1 },
95             rv => { required => 1 },
96             function => { default => CALLING_FUNCTION->() },
97             };
98              
99 1 50       18 my $args = check( $tmpl, \%hash ) or return;
100 1         314 my $self = bless {}, $class;
101              
102             # $self->mk_accessors( qw[ok args function rv] );
103 1         40 $self->mk_accessors( keys %$tmpl );
104              
105             ### set the values passed in the struct ###
106 1         188 while( my($key,$val) = each %$args ) {
107 4         421 $self->$key( $val );
108             }
109              
110 1         125 return $self;
111             }
112              
113 1     1   749 sub _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"? :(
120 20         225 use overload bool => \&_ok,
121             # '""' => \&_stringify,
122 20     20   179 fallback => 1;
  20         53  
123              
124             =pod
125              
126             =head1 BUG REPORTS
127              
128             Please report bugs or other issues to Ebug-cpanplus@rt.cpan.org.
129              
130             =head1 AUTHOR
131              
132             This module by Jos Boumans Ekane@cpan.orgE.
133              
134             =head1 COPYRIGHT
135              
136             The CPAN++ interface (of which this module is a part of) is copyright (c)
137             2001 - 2007, Jos Boumans Ekane@cpan.orgE. All rights reserved.
138              
139             This library is free software; you may redistribute and/or modify it
140             under the same terms as Perl itself.
141              
142             =cut
143              
144             1;