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

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.