Return::Value(3) User Contributed Perl Documentation Return::Value(3)NAMEReturn::Value - (deprecated) polymorphic return values
VERSION
version 1.666001
DO NOT USE THIS LIBRARY
This library will begin issuing deprecation warnings in June 2010.
Return::Value was a bad idea. i'm sorry that I had it, sorry that I
followed through, and sorry that 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.
Please do not use this library. You will just regret it later.
SYNOPSIS
Used with 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, 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 others, we may want to know what the
error code was, and what the error properties were. 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.
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.
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
The errno attribute 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
The value's string attribute is a simple message describing the
value.
data
The data attribute 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, prop is 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 retrived via method calls.
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 is 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.
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 retured, 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.
TODO
Add deprecation.
AUTHORS
Casey West, <casey@geeknest.com>.
Ricardo Signes, <rjbs@cpan.org>.
COPYRIGHT
Copyright (c) 2004-2006 Casey West and Ricardo SIGNES. All rights reserved.
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
perl v5.14.1 2009-06-08 Return::Value(3)
