Class::ReturnValue − A return−value object that lets you treat it as as a boolean, array or object
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)
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;
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
Jesse Vincent <[email protected]>
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−[email protected]> or
report your error on the web
at http://rt.cpan.org/
Copyright (c)
2002,2003,2005,2007 Jesse Vincent
<[email protected]>
You may use, modify, fold, spindle or mutilate this module
under
the same terms as perl itself.
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.
Hey! The
above document had some coding errors, which are explained
below:
Around line 97:
’=item’ outside of any ’=over’
Around line 264:
=cut found outside a pod block. Skipping to next block.
Around line 296:
You forgot a ’=back’ before ’=head1’