1Return::Value(3) User Contributed Perl Documentation Return::Value(3)
2
6 Return::Value - Polymorphic Return Values
7
9 version 1.302
10 $Id: /my/cs/projects/return/trunk/lib/Return/Value.pm 28007 2006-11-14T22:21:03.864745Z rjbs $
12
14 Used with basic function-call interface:
15 use Return::Value;
17 sub send_over_network {
19 my ($net, $send) = @_:
20 if ( $net->transport( $send ) ) {
21 return success;
22 } else {
23 return failure "Was not able to transport info.";
24 }
25 }
26 my $result = $net->send_over_network( "Data" );
28 # boolean
30 unless ( $result ) {
31 # string
32 print $result;
33 }
34 Or, build your Return::Value as an object:
36 sub build_up_return {
38 my $return = failure;
39 if ( ! foo() ) {
41 $return->string("Can't foo!");
42 return $return;
43 }
44 if ( ! bar() ) {
46 $return->string("Can't bar");
47 $return->prop(failures => \@bars);
48 return $return;
49 }
50 # we're okay if we made it this far.
52 $return++;
53 return $return; # success!
54 }
55
57 Polymorphic return values are really useful. Often, we just want to
58 know if something worked or not. Other times, we'd like to know what
59 the error text was. Still others, we may want to know what the error
60 code was, and what the error properties were. We don't want to handle
61 objects or data structures for every single return value, but we do
62 want to check error conditions in our code because that's what good
63 programmers do.
64 When functions are successful they may return true, or perhaps some
66 useful data. In the quest to provide consistent return values, this
67 gets confusing between complex, informational errors and successful
68 return values.
69 This module provides these features with a simple API that should get
71 you what you're looking for in each contex a return value is used in.
72 Attributes
74 All return values have a set of attributes that package up the informa‐
76 tion returned. All attributes can be accessed or changed via methods
77 of the same name, unless otherwise noted. Many can also be accessed
78 via overloaded operations on the object, as noted below.
79 type
81 A value's type is either "success" or "failure" and (obviously)
82 reflects whether the value is returning success or failure.
83 errno
85 The errno attribute stores the error number of the return value.
86 For success-type results, it is by default undefined. For other
87 results, it defaults to 1.
88 string
90 The value's string attribute is a simple message describing the
91 value.
92 data
94 The data attribute stores a reference to a hash or array, and can
95 be used as a simple way to return extra data. Data stored in the
96 data attribute can be accessed by dereferencing the return value
97 itself. (See below.)
98 prop
100 The most generic attribute of all, prop is a hashref that can be
101 used to pass an arbitrary number of data structures, just like the
102 data attribute. Unlike the data attribute, though, these struc‐
103 tures must be retrived via method calls.
104
106 The functional interface is highly recommended for use within functions
107 that are using "Return::Value" for return values. It's simple and
108 straightforward, and builds the entire return value in one statement.
109 success
111 The "success" function returns a "Return::Value" with the type
112 "success".
113 Additional named parameters may be passed to set the returned
115 object's attributes. The first, optional, parameter is the string
116 attribute and does not need to be named. All other parameters must
117 be passed by name.
118 # simplest possible case
120 return success;
121 failure
123 "failure" is identical to "success", but returns an object with the
124 type "failure"
125
127 The object API is useful in code that is catching "Return::Value"
128 objects.
129 new
131 my $return = Return::Value->new(
132 type => 'failure',
133 string => "YOU FAIL",
134 prop => {
135 failed_objects => \@objects,
136 },
137 );
138 Creates a new "Return::Value" object. Named parameters can be used
140 to set the object's attributes.
141 bool
143 print "it worked" if $result->bool;
144 Returns the result in boolean context: true for success, false for
146 failure.
147 prop
149 printf "%s: %s',
150 $result->string, join ' ', @{$result->prop('strings')}
151 unless $result->bool;
152 Returns the return value's properties. Accepts the name of a prop‐
154 erty retured, or returns the properties hash reference if given no
155 name.
156 other attribute accessors
158 Simple accessors exist for the object's other attributes: "type",
159 "errno", "string", and "data".
160 Overloading
162 Several operators are overloaded for "Return::Value" objects. They are
164 listed here.
165 Stringification
167 print "$result\n";
168 Stringifies to the string attribute.
170 Boolean
172 print $result unless $result;
173 Returns the "bool" representation.
175 Numeric
177 Also returns the "bool" value.
178 Dereference
180 Dereferencing the value as a hash or array will return the value of
181 the data attribute, if it matches that type, or an empty reference
182 otherwise. You can check "ref $result->data" to determine what
183 kind of data (if any) was passed.
184
186 No plans!
187
189 Casey West, <casey@geeknest.com>.
190 Ricardo Signes, <rjbs@cpan.org>.
192
194 Copyright (c) 2004-2006 Casey West and Ricardo SIGNES. All rights reserved.
195 This module is free software; you can redistribute it and/or modify it under
196 the same terms as Perl itself.
197perl v5.8.8 2006-11-14 Return::Value(3)