[Summary view] [Print] [Text view]

   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;