1Return::Value(3) User Contributed Perl Documentation Return::Value(3)
2
6 Return::Value - (deprecated) polymorphic return values
7
9 version 1.666005
10
12 Used with basic function-call interface:
13 use Return::Value;
15 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 my $result = $net->send_over_network( "Data" );
26 # boolean
28 unless ( $result ) {
29 # string
30 print $result;
31 }
32 Or, build your Return::Value as an object:
34 sub build_up_return {
36 my $return = failure;
37 if ( ! foo() ) {
39 $return->string("Can't foo!");
40 return $return;
41 }
42 if ( ! bar() ) {
44 $return->string("Can't bar");
45 $return->prop(failures => \@bars);
46 return $return;
47 }
48 # we're okay if we made it this far.
50 $return++;
51 return $return; # success!
52 }
53
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 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 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 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 type
80 A value's type is either "success" or "failure" and (obviously)
81 reflects whether the value is returning success or failure.
82 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 string
89 The value's string attribute is a simple message describing the
90 value.
91 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 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
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 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 Objects that are false are just a dreadful idea in almost every
117 circumstance, especially when the object has useful properties.
118 Please do not use this library. You will just regret it later.
120 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
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 success
132 The "success" function returns a "Return::Value" with the type
133 "success".
134 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 # simplest possible case
141 return success;
142 failure
144 "failure" is identical to "success", but returns an object with the
145 type "failure"
146
148 The object API is useful in code that is catching "Return::Value"
149 objects.
150 new
152 my $return = Return::Value->new(
153 type => 'failure',
154 string => "YOU FAIL",
155 prop => {
156 failed_objects => \@objects,
157 },
158 );
159 Creates a new "Return::Value" object. Named parameters can be used
161 to set the object's attributes.
162 bool
164 print "it worked" if $result->bool;
165 Returns the result in boolean context: true for success, false for
167 failure.
168 prop
170 printf "%s: %s',
171 $result->string, join ' ', @{$result->prop('strings')}
172 unless $result->bool;
173 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 other attribute accessors
179 Simple accessors exist for the object's other attributes: "type",
180 "errno", "string", and "data".
181 Overloading
183 Several operators are overloaded for "Return::Value" objects. They are
184 listed here.
185 Stringification
187 print "$result\n";
188 Stringifies to the string attribute.
190 Boolean
192 print $result unless $result;
193 Returns the "bool" representation.
195 Numeric
197 Also returns the "bool" value.
198 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
206 • Ricardo SIGNES <rjbs@cpan.org>
207 • Casey West
209
211 • David Steinbrunner <dsteinbrunner@pobox.com>
212 • Karen Etheridge <ether@cpan.org>
214 • Ricardo SIGNES <rjbs@codesimply.com>
216
218 This software is copyright (c) 2005 by Casey West.
219 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.
222perl v5.32.1 2021-01-27 Return::Value(3)