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 <[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 
    <[email protected]> or report your error on the web
    at http://rt.cpan.org/

COPYRIGHT

    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.

POD ERRORS

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'