1Return::Value(3)      User Contributed Perl Documentation     Return::Value(3)
2
3
4

NAME

6       Return::Value - (deprecated) polymorphic return values
7

VERSION

9       version 1.666005
10

SYNOPSIS

12       Used with basic function-call interface:
13
14         use Return::Value;
15
16         sub send_over_network {
17             my ($net, $send) = @_:
18             if ( $net->transport( $send ) ) {
19                 return success;
20             } else {
21                 return failure "Was not able to transport info.";
22             }
23         }
24
25         my $result = $net->send_over_network(  "Data" );
26
27         # boolean
28         unless ( $result ) {
29             # string
30             print $result;
31         }
32
33       Or, build your Return::Value as an object:
34
35         sub build_up_return {
36             my $return = failure;
37
38             if ( ! foo() ) {
39                 $return->string("Can't foo!");
40                 return $return;
41             }
42
43             if ( ! bar() ) {
44                 $return->string("Can't bar");
45                 $return->prop(failures => \@bars);
46                 return $return;
47             }
48
49             # we're okay if we made it this far.
50             $return++;
51             return $return; # success!
52         }
53

DESCRIPTION

55       Polymorphic return values are a horrible idea, but this library was
56       written based on the notion that they were useful.  Often, we just want
57       to know if something worked or not.  Other times, we'd like to know
58       what the error text was.  Still others, we may want to know what the
59       error code was, and what the error properties were.  We don't want to
60       handle objects or data structures for every single return value, but we
61       do want to check error conditions in our code because that's what good
62       programmers do.
63
64       When functions are successful they may return true, or perhaps some
65       useful data.  In the quest to provide consistent return values, this
66       gets confusing between complex, informational errors and successful
67       return values.
68
69       This module provides these features with a simplistic API that should
70       get you what you're looking for in each context a return value is used
71       in.
72
73   Attributes
74       All return values have a set of attributes that package up the
75       information returned.  All attributes can be accessed or changed via
76       methods of the same name, unless otherwise noted.  Many can also be
77       accessed via overloaded operations on the object, as noted below.
78
79       type
80           A value's type is either "success" or "failure" and (obviously)
81           reflects whether the value is returning success or failure.
82
83       errno
84           The errno attribute stores the error number of the return value.
85           For success-type results, it is by default undefined.  For other
86           results, it defaults to 1.
87
88       string
89           The value's string attribute is a simple message describing the
90           value.
91
92       data
93           The data attribute stores a reference to a hash or array, and can
94           be used as a simple way to return extra data.  Data stored in the
95           data attribute can be accessed by dereferencing the return value
96           itself.  (See below.)
97
98       prop
99           The most generic attribute of all, prop is a hashref that can be
100           used to pass an arbitrary number of data structures, just like the
101           data attribute.  Unlike the data attribute, though, these
102           structures must be retrieved via method calls.
103

DO NOT USE THIS LIBRARY

105       Return::Value was a bad idea.  I'm sorry that I had it, sorry that I
106       followed through, and sorry that it got used in other useful libraries.
107       Fortunately there are not many things using it.  One of those things is
108       Email::Send which is also deprecated in favor of Email::Sender.
109
110       There's no reason to specify a new module to replace Return::Value.  In
111       general, routines should return values of uniform type or throw
112       exceptions.  Return::Value tried to be a uniform type for all routines,
113       but has so much weird behavior that it ends up being confusing and not
114       very Perl-like.
115
116       Objects that are false are just a dreadful idea in almost every
117       circumstance, especially when the object has useful properties.
118
119       Please do not use this library.  You will just regret it later.
120
121       A release of this library in June 2009 promised that deprecation
122       warnings would start being issued in June 2010.  It is now December
123       2012, and the warnings are now being issued.  They can be disabled
124       through means made clear from the source.
125

FUNCTIONS

127       The functional interface is highly recommended for use within functions
128       that are using "Return::Value" for return values.  It's simple and
129       straightforward, and builds the entire return value in one statement.
130
131       success
132           The "success" function returns a "Return::Value" with the type
133           "success".
134
135           Additional named parameters may be passed to set the returned
136           object's attributes.  The first, optional, parameter is the string
137           attribute and does not need to be named.  All other parameters must
138           be passed by name.
139
140            # simplest possible case
141            return success;
142
143       failure
144           "failure" is identical to "success", but returns an object with the
145           type "failure"
146

METHODS

148       The object API is useful in code that is catching "Return::Value"
149       objects.
150
151       new
152             my $return = Return::Value->new(
153                 type   => 'failure',
154                 string => "YOU FAIL",
155                 prop   => {
156                     failed_objects => \@objects,
157                 },
158             );
159
160           Creates a new "Return::Value" object.  Named parameters can be used
161           to set the object's attributes.
162
163       bool
164             print "it worked" if $result->bool;
165
166           Returns the result in boolean context: true for success, false for
167           failure.
168
169       prop
170             printf "%s: %s',
171               $result->string, join ' ', @{$result->prop('strings')}
172                 unless $result->bool;
173
174           Returns the return value's properties. Accepts the name of a
175           property returned, or returns the properties hash reference if
176           given no name.
177
178       other attribute accessors
179           Simple accessors exist for the object's other attributes: "type",
180           "errno", "string", and "data".
181
182   Overloading
183       Several operators are overloaded for "Return::Value" objects. They are
184       listed here.
185
186       Stringification
187             print "$result\n";
188
189           Stringifies to the string attribute.
190
191       Boolean
192             print $result unless $result;
193
194           Returns the "bool" representation.
195
196       Numeric
197           Also returns the "bool" value.
198
199       Dereference
200           Dereferencing the value as a hash or array will return the value of
201           the data attribute, if it matches that type, or an empty reference
202           otherwise.  You can check "ref $result->data" to determine what
203           kind of data (if any) was passed.
204

AUTHORS

206       •   Ricardo SIGNES <rjbs@cpan.org>
207
208       •   Casey West
209

CONTRIBUTORS

211       •   David Steinbrunner <dsteinbrunner@pobox.com>
212
213       •   Karen Etheridge <ether@cpan.org>
214
215       •   Ricardo SIGNES <rjbs@codesimply.com>
216
218       This software is copyright (c) 2005 by Casey West.
219
220       This is free software; you can redistribute it and/or modify it under
221       the same terms as the Perl 5 programming language system itself.
222
223
224
225perl v5.34.0                      2021-07-22                  Return::Value(3)
Impressum