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)