1Return::Value(3) User Contributed Perl Documentation Return::Value(3)
2
6 Return::Value - (deprecated) polymorphic return values
7
9 version 1.666001
10
12 This library will begin issuing deprecation warnings in June 2010.
13 Return::Value was a bad idea. i'm sorry that I had it, sorry that I
15 followed through, and sorry that it got used in other useful libraries.
16 Fortunately there are not many things using it. One of those things is
17 Email::Send which is also deprecated in favor of Email::Sender.
18 There's no reason to specify a new module to replace Return::Value. In
20 general, routines should return values of uniform type or throw
21 exceptions. Return::Value tried to be a uniform type for all routines,
22 but has so much weird behavior that it ends up being confusing and not
23 very Perl-like.
24 Objects that are false are just a dreadful idea in almost every
26 circumstance, especially when the object has useful properties.
27 Please do not use this library. You will just regret it later.
29
31 Used with basic function-call interface:
32 use Return::Value;
34 sub send_over_network {
36 my ($net, $send) = @_:
37 if ( $net->transport( $send ) ) {
38 return success;
39 } else {
40 return failure "Was not able to transport info.";
41 }
42 }
43 my $result = $net->send_over_network( "Data" );
45 # boolean
47 unless ( $result ) {
48 # string
49 print $result;
50 }
51 Or, build your Return::Value as an object:
53 sub build_up_return {
55 my $return = failure;
56 if ( ! foo() ) {
58 $return->string("Can't foo!");
59 return $return;
60 }
61 if ( ! bar() ) {
63 $return->string("Can't bar");
64 $return->prop(failures => \@bars);
65 return $return;
66 }
67 # we're okay if we made it this far.
69 $return++;
70 return $return; # success!
71 }
72
74 Polymorphic return values are a horrible idea, but this library was
75 written based on the notion that they were useful. Often, we just want
76 to know if something worked or not. Other times, we'd like to know
77 what the error text was. Still others, we may want to know what the
78 error code was, and what the error properties were. We don't want to
79 handle objects or data structures for every single return value, but we
80 do want to check error conditions in our code because that's what good
81 programmers do.
82 When functions are successful they may return true, or perhaps some
84 useful data. In the quest to provide consistent return values, this
85 gets confusing between complex, informational errors and successful
86 return values.
87 This module provides these features with a simplistic API that should
89 get you what you're looking for in each context a return value is used
90 in.
91 Attributes
93 All return values have a set of attributes that package up the
94 information returned. All attributes can be accessed or changed via
95 methods of the same name, unless otherwise noted. Many can also be
96 accessed via overloaded operations on the object, as noted below.
97 type
99 A value's type is either "success" or "failure" and (obviously)
100 reflects whether the value is returning success or failure.
101 errno
103 The errno attribute stores the error number of the return value.
104 For success-type results, it is by default undefined. For other
105 results, it defaults to 1.
106 string
108 The value's string attribute is a simple message describing the
109 value.
110 data
112 The data attribute stores a reference to a hash or array, and can
113 be used as a simple way to return extra data. Data stored in the
114 data attribute can be accessed by dereferencing the return value
115 itself. (See below.)
116 prop
118 The most generic attribute of all, prop is a hashref that can be
119 used to pass an arbitrary number of data structures, just like the
120 data attribute. Unlike the data attribute, though, these
121 structures must be retrived via method calls.
122
124 The functional interface is highly recommended for use within functions
125 that are using "Return::Value" for return values. It's simple and
126 straightforward, and builds the entire return value in one statement.
127 success
129 The "success" function returns a "Return::Value" with the type
130 "success".
131 Additional named parameters may be passed to set the returned
133 object's attributes. The first, optional, parameter is the string
134 attribute and does not need to be named. All other parameters must
135 be passed by name.
136 # simplest possible case
138 return success;
139 failure
141 "failure" is identical to "success", but returns an object with the
142 type "failure"
143
145 The object API is useful in code that is catching "Return::Value"
146 objects.
147 new
149 my $return = Return::Value->new(
150 type => 'failure',
151 string => "YOU FAIL",
152 prop => {
153 failed_objects => \@objects,
154 },
155 );
156 Creates a new "Return::Value" object. Named parameters can be used
158 to set the object's attributes.
159 bool
161 print "it worked" if $result->bool;
162 Returns the result in boolean context: true for success, false for
164 failure.
165 prop
167 printf "%s: %s',
168 $result->string, join ' ', @{$result->prop('strings')}
169 unless $result->bool;
170 Returns the return value's properties. Accepts the name of a
172 property retured, or returns the properties hash reference if given
173 no name.
174 other attribute accessors
176 Simple accessors exist for the object's other attributes: "type",
177 "errno", "string", and "data".
178 Overloading
180 Several operators are overloaded for "Return::Value" objects. They are
181 listed here.
182 Stringification
184 print "$result\n";
185 Stringifies to the string attribute.
187 Boolean
189 print $result unless $result;
190 Returns the "bool" representation.
192 Numeric
194 Also returns the "bool" value.
195 Dereference
197 Dereferencing the value as a hash or array will return the value of
198 the data attribute, if it matches that type, or an empty reference
199 otherwise. You can check "ref $result->data" to determine what
200 kind of data (if any) was passed.
201
203 Add deprecation.
204
206 Casey West, <casey@geeknest.com>.
207 Ricardo Signes, <rjbs@cpan.org>.
209
211 Copyright (c) 2004-2006 Casey West and Ricardo SIGNES. All rights reserved.
212 This module is free software; you can redistribute it and/or modify it under
213 the same terms as Perl itself.
214perl v5.12.1 2009-06-08 Return::Value(3)