Class:...nValue(3pm)

✨ NAME ✨

okay bestie, welcome to Class::ReturnValue — it's a Perl module (a 3pm manual page, user contributed, if you're keeping track of your man sections 💅) and it's basically a return-value object that lets you treat it as a boolean, an array, or an object. three vibes, one little guy. iconic. 👑

---

🦋 DESCRIPTION 🦋

so Class::ReturnValue is what the docs themselves call a "clever" return value object 🎀 and the whole point is that it lets the code calling your routine expect either:

• a boolean value (did it fail), or
• a list (what are the return values)

like, it just... flexes into whichever one the caller wanted. main character energy fr fr. 💖

---

🌸 EXAMPLE 🌸

here's the whole thing in action, no cap:

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;

(and yes, that # TODO: does this work comment is in the original and I am not touching it, it's part of the lore 😭)

---

💅 METHODS 💅

• new — instantiate a brand new Class::ReturnValue object. baby's first return value 🫶
• as_array — hand back the 'as_array' attribute of this object, but as an actual array. slay.
• as_array [ARRAY] — if $self gets called in an array context, it returns the array you specified in ARRAY. ✨
• as_error HASH — turns this return-value object into an error return object. it takes three parameters:
  • message
  • do_backtrace
  • errno

okay let me break those down because there's lore:

• 'message' is a human readable error message explaining what's going on. like, words. for humans. 💬
• '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. and 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.

bestie. I know. "true value makes it false??" at first, this may look a bit counterintuitive, but it means 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. (yes it's the lil inverse guy, we love him 💜)

---

🎀 AUTHOR 🎀

Jesse Vincent <jesse@bestpractical.com> — shoutout to the author, absolute legend. 👑

---

💀 BUGS 💀

okay so real talk, the original docs say this module has, as yet, not been used in production code. the author says "I thing it should work" (that typo is verbatim and I'm keeping it, it's a whole mood 🍓) but it has never been benchmarked. it also has not yet been used extensively, though there are plans to do so in the not-too-distant future. if you have questions or comments, please write.

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. (fold. spindle. mutilate. the license said it's fine. 🙈)

---

⭐ SEE ALSO ⭐

Class::ReturnValue isn't an exception handler. if it doesn't do what you want, you might want to 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. 🧚

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-26, from the Class:...nValue(3pm) manual — go forth and return values in every format at once, you absolute icon 💖✨🎀