Return::Value(3)

📦
version 1.666005 · 4 versions
, in opensuse-leap 16.0

💖 NAME 💖 — okay so this is Return::Value(3) 💖

This is a User Contributed Perl Documentation page, and the actual NAME is Return::Value — (deprecated) polymorphic return values. Yes bestie, the deprecation is literally in the name section. 💅

🌸 VERSION 🌸

version 1.666005 — iconic number, no notes.

✨ SYNOPSIS ✨

Okay so first, the basic function-call interface:

  use Return::Value;

  sub send_over_network {
      my ($net, $send) = @_:
      if ( $net->transport( $send ) ) {
          return success;
      } else {
          return failure "Was not able to transport info.";
      }
  }

  my $result = $net->send_over_network(  "Data" );

  # boolean
  unless ( $result ) {
      # string
      print $result;
  }

Or, build your Return::Value as an object:

  sub build_up_return {
      my $return = failure;

      if ( ! foo() ) {
          $return->string("Can't foo!");
          return $return;
      }

      if ( ! bar() ) {
          $return->string("Can't bar");
          $return->prop(failures => \@bars);
          return $return;
      }

      # we're okay if we made it this far.
      $return++;
      return $return; # success!
  }

🦋 DESCRIPTION 🦋

Polymorphic return values are a horrible idea — that's not me being shady, that's literally what the docs say — but this library was written based on the notion that they were useful. Often we just want to know if something worked or not. Other times we'd like to know what the error text was. Still other times, we may want to know the error code and the error properties. We don't want to handle objects or data structures for every single return value, but we do want to check error conditions in our code because that's what good programmers do. Periodt. ✨

When functions are successful they may return true, or perhaps some useful data. In the quest to provide consistent return values, this gets confusing between complex, informational errors and successful return values. It's giving messy, ngl.

This module provides these features with a simplistic API that should get you what you're looking for in each context a return value is used in.

🎀 Attributes 🎀

All return values have a set of attributes that package up the information returned. All attributes can be accessed or changed via methods of the same name, unless otherwise noted. Many can also be accessed via overloaded operations on the object, as noted below.

  • type — a value's type is either success or failure, and (obviously) reflects whether the value is returning success or failure.
  • errno — stores the error number of the return value. For success-type results, it is by default undefined. For other results, it defaults to 1.
  • string — a simple message describing the value. Short, sweet, to the point.
  • data — stores a reference to a hash or array, and can be used as a simple way to return extra data. Data stored in the data attribute can be accessed by dereferencing the return value itself. (See below.)
  • prop — the most generic attribute of all. It's a hashref that can be used to pass an arbitrary number of data structures, just like the data attribute. Unlike the data attribute, though, these structures must be retrieved via method calls.

🚨 DO NOT USE THIS LIBRARY 🚨

Return::Value was a bad idea. The author is sorry they had it, sorry they followed through, and sorry it got used in other useful libraries. Fortunately there are not many things using it. One of those things is Email::Send, which is also deprecated in favor of Email::Sender.

There's no reason to specify a new module to replace Return::Value. In general, routines should return values of uniform type or throw exceptions. Return::Value tried to be a uniform type for all routines, but has so much weird behavior that it ends up being confusing and not very Perl-like.

Objects that are false are just a dreadful idea in almost every circumstance, especially when the object has useful properties. Like, why. 😭

Please do not use this library. You will just regret it later.

A release of this library in June 2009 promised that deprecation warnings would start being issued in June 2010. It is now December 2012, and the warnings are now being issued. They can be disabled through means made clear from the source.

🔥 FUNCTIONS 🔥

The functional interface is highly recommended for use within functions that are using Return::Value for return values. It's simple and straightforward, and builds the entire return value in one statement.

success

The success function returns a Return::Value with the type success.

Additional named parameters may be passed to set the returned object's attributes. The first, optional, parameter is the string attribute and does not need to be named. All other parameters must be passed by name.

  # simplest possible case
  return success;

failure

failure is identical to success, but returns an object with the type failure.

🛠️ METHODS 🛠️

The object API is useful in code that's catching Return::Value objects.

new

  my $return = Return::Value->new(
      type   => 'failure',
      string => "YOU FAIL",
      prop   => {
          failed_objects => \@objects,
      },
  );

Creates a new Return::Value object. Named parameters can be used to set the object's attributes.

bool

  print "it worked" if $result->bool;

Returns the result in boolean context: true for success, false for failure. Simple vibe check.

prop

  printf "%s: %s',
    $result->string, join ' ', @{$result->prop('strings')}
      unless $result->bool;

Returns the return value's properties. Accepts the name of a property returned, or returns the properties hash reference if given no name.

other attribute accessors

Simple accessors exist for the object's other attributes: type, errno, string, and data.

🌀 Overloading 🌀

Several operators are overloaded for Return::Value objects. They are listed here.

Stringification

  print "$result\n";

Stringifies to the string attribute.

Boolean

  print $result unless $result;

Returns the bool representation.

Numeric

Also returns the bool value.

Dereference

Dereferencing the value as a hash or array will return the value of the data attribute, if it matches that type, or an empty reference otherwise. You can check ref $result->data to determine what kind of data (if any) was passed.

👑 AUTHORS 👑

  • Ricardo SIGNES <rjbs@cpan.org>
  • Casey West

🌈 CONTRIBUTORS 🌈

  • David Steinbrunner <dsteinbrunner@pobox.com>
  • Karen Etheridge <ether@cpan.org>
  • Ricardo SIGNES <rjbs@codesimply.com>

This software is copyright (c) 2005 by Casey West.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

byeee bestie, this page was brought to you by perl v5.42.0, dated 2015-12-05, and it's literally Return::Value(3) — slay and goodbye 💋✨🦋

📦 where this page comes from