lib/CPANPLUS/Backend/RV.pm

   1 package CPANPLUS::Backend::RV;
   2
   3 use strict;
   4 use vars qw[$STRUCT];
   5
   6
   7 use CPANPLUS::Error;
   8 use CPANPLUS::Internals::Constants;
   9
  10 use IPC::Cmd                    qw[can_run run];
  11 use Params::Check               qw[check];
  12
  13 use base 'Object::Accessor';
  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     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
 113 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 use overload bool       => \&_ok,
 121 #             '""'       => \&_stringify,
 122              fallback   => 1;
 123
 124 =pod
 125
 126 =head1 BUG REPORTS
 127
 128 Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
 129
 130 =head1 AUTHOR
 131
 132 This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
 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 E<lt>kane@cpan.orgE<gt>. 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;