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


line stmt bran cond sub pod time code
1             package CPANPLUS::Backend::RV;
2              
3 15     15   306 use strict;
  15         270  
  15         261  
4 15     15   515 use vars qw[$STRUCT];
  15         207  
  15         233  
5              
6              
7 15     15   315 use CPANPLUS::Error;
  15         180  
  15         272  
8 15     15   464 use CPANPLUS::Internals::Constants;
  15         137  
  15         275  
9              
10 15     15   534 use IPC::Cmd qw[can_run run];
  15         4871  
  15         518  
11 15     15   295 use Params::Check qw[check];
  15         141  
  15         297  
12              
13 15     15   245 use base 'Object::Accessor';
  15         180  
  15         282  
14              
15             local $Params::Check::VERBOSE = 1;
16              
17              
18             =pod
19            
20             =head1 NAME
21            
22             CPANPLUS::Backend::RV
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->fucntion # 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<ok> 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<new()> will try to deduce the name
82             from C<caller()> information.
83            
84             =back
85            
86             =cut
87              
88             sub new {
89 1     1 1 11     my $class = shift;
90 1         65     my %hash = @_;
91              
92 1         73     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       68     my $args = check( $tmpl, \%hash ) or return;
100 1         195     my $self = bless {}, $class;
101              
102             # $self->mk_accessors( qw[ok args function rv] );
103 1         78     $self->mk_accessors( keys %$tmpl );
104              
105             ### set the values passed in the struct ###
106 1         19     while( my($key,$val) = each %$args ) {
107 4         122         $self->$key( $val );
108                 }
109              
110 1         114     return $self;
111             }
112              
113 3     3   70 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 15         908 use overload bool => \&_ok,
121             # '""' => \&_stringify,
122 15     15   634              fallback => 1;
  15         173  
123              
124             =pod
125            
126             =head1 AUTHOR
127            
128             This module by
129             Jos Boumans E<lt>kane@cpan.orgE<gt>.
130            
131             =head1 COPYRIGHT
132            
133             The CPAN++ interface (of which this module is a part of) is
134             copyright (c) 2001, 2002, 2003, 2004, Jos Boumans E<lt>kane@cpan.orgE<gt>.
135             All rights reserved.
136            
137             This library is free software;
138             you may redistribute and/or modify it under the same
139             terms as Perl itself.
140            
141             =cut
142              
143             1;
144