Class::ReturnValue(3pm) 				User Contributed Perl Documentation				   Class::ReturnValue(3pm)

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:
".
	       $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:
".
	       $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
";
		   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.

perl v5.8.8							    2007-08-29						   Class::ReturnValue(3pm)