---
name: "Class::ReturnValue"
section: "3pm"
platform: "linux"
package: "libclass-returnvalue-perl"
version: "0.55-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Class::ReturnValue"
---

# Class::ReturnValue(3pm)

A return-value object that lets you treat it as as a boolean, array or object

## 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 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

## 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.
```