Class::ReturnValue3pm

Overview

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)

Examples

    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 parameters. 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 parameters. 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