NAME¶
Return::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.