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

           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.