Class::ReturnValue.3pm

Langue: en

Autres versions - même langue

Version: 2007-08-29 (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

NAME

Class::ReturnValue - A return-value object that lets you treat it as as a boolean, array or object

DESCRIPTION

Class::ReturnValue is a ``clever'' return value object that can allow code calling your routine to expect:
    a boolean value (did it fail) or a list (what are the return values)

EXAMPLE

     sub demo {
         my $value = shift;
         my $ret = Class::ReturnValue->new();
         $ret->as_array('0', 'No results found');
 
 
         unless($value) {
             $ret->as_error(errno => '1',
                                message => "You didn't supply a parameter.",
                                do_backtrace => 1);
         }
 
 
         return($ret->return_value);
     }
 
 
     if (demo('foo')){ 
         print "the routine succeeded with one parameter";
     }
     if (demo()) {
         print "The routine succeeded with 0 paramters. shouldn't happen";
     } else {
         print "The routine failed with 0 parameters (as it should).";
     }
 
 
     my $return = demo();
     if ($return) {
         print "The routine succeeded with 0 paramters. shouldn't happen";
     } else {
         print "The routine failed with 0 parameters (as it should). ".
               "Stack trace:\n".
         $return->backtrace;
     }
 
 
     my @return3 = demo('foo');
     print "The routine got ".join(',',@return3).
           "when asking for demo's results as an array";
 
 
     my $return2 = demo('foo');
 
 
     unless ($return2) {
         print "The routine failed with a parameter. shouldn't happen.".
              "Stack trace:\n".
         $return2->backtrace;
     }
 
 
     my @return2_array = @{$return2}; # TODO: does this work
     my @return2_array2 = $return2->as_array;
 
 

METHODS

new
Instantiate a new Class::ReturnValue object
as_array
Return the 'as_array' attribute of this object as an array.
as_array [ARRAY]
If $self is called in an array context, returns the array specified in ARRAY
as_error HASH
Turns this return-value object into an error return object. TAkes three parameters:
     message
     do_backtrace
     errno
 
 
     'message' is a human readable error message explaining what's going on
 
 
     'do_backtrace' is a boolean. If it's true, a carp-style backtrace will be 
     stored in $self->{'backtrace'}. It defaults to true
 
 
     errno and message default to undef. errno _must_ be specified. 
     It's a numeric error number.  Any true integer value  will cause the 
     object to evaluate to false in a scalar context. At first, this may look a 
     bit counterintuitive, but it means that you can have error codes and still 
     allow simple use of your functions in a style like this:
 
 
         if ($obj->do_something) {
             print "Yay! it worked";
         } else {
             print "Sorry. there's been an error.";
         }
 
 
         as well as more complex use like this:
 
 
         my $retval = $obj->do_something;
 
 
         if ($retval) {
             print "Yay. we did something\n";
             my ($foo, $bar, $baz) = @{$retval};
             my $human_readable_return = $retval;
         } else {
             if ($retval->errno == 20) {
                 die "Failed with error 20 (Not enough monkeys).";
             } else {
                 die  $retval->backtrace; # Die and print out a backtrace 
             }
         }
 
 
errno
Returns the errno if there's been an error. Otherwise, return undef
error_message
If there's been an error return the error message.
backtrace
If there's been an error and we asked for a backtrace, return the backtrace. Otherwise, return undef.
error_condition
If there's been an error, return undef. Otherwise return 1

AUTHOR

     Jesse Vincent <jesse@bestpractical.com>
 
 

BUGS

     This module has, as yet, not been used in production code. I thing
     it should work, but have never benchmarked it. I have not yet used
     it extensively, though I do plan to in the not-too-distant future.
     If you have questions or comments,  please write me.
 
 
     If you need to report a bug, please send mail to 
     <bug-class-returnvalue@rt.cpan.org> or report your error on the web
     at http://rt.cpan.org/
 
 
     Copyright (c) 2002,2003,2005,2007 Jesse Vincent <jesse@bestpractical.com>
     You may use, modify, fold, spindle or mutilate this module under
     the same terms as perl itself.
 
 

SEE ALSO

     Class::ReturnValue isn't an exception handler. If it doesn't
     do what you want, you might want look at one of the exception handlers
     below:
 
 
     Error, Exception, Exceptions, Exceptions::Class
 
 
     You might also want to look at Contextual::Return, another implementation
     of the same concept as this module.