1Class::ReturnValue(3) User Contributed Perl DocumentationClass::ReturnValue(3)
2
6 Class::ReturnValue - A return-value object that lets you treat it as as
7 a boolean, array or object
8
10 Class::ReturnValue is a "clever" return value object that can allow
11 code calling your routine to expect:
12 a boolean value (did it fail) or a list (what are the return
13 values)
14
16 sub demo {
17 my $value = shift;
18 my $ret = Class::ReturnValue->new();
19 $ret->as_array('0', 'No results found');
20 unless($value) {
22 $ret->as_error(errno => '1',
23 message => "You didn't supply a parameter.",
24 do_backtrace => 1);
25 }
26 return($ret->return_value);
28 }
29 if (demo('foo')){
31 print "the routine succeeded with one parameter";
32 }
33 if (demo()) {
34 print "The routine succeeded with 0 paramters. shouldn't happen";
35 } else {
36 print "The routine failed with 0 parameters (as it should).";
37 }
38 my $return = demo();
41 if ($return) {
42 print "The routine succeeded with 0 paramters. shouldn't happen";
43 } else {
44 print "The routine failed with 0 parameters (as it should). ".
45 "Stack trace:\n".
46 $return->backtrace;
47 }
48 my @return3 = demo('foo');
50 print "The routine got ".join(',',@return3).
51 "when asking for demo's results as an array";
52 my $return2 = demo('foo');
55 unless ($return2) {
57 print "The routine failed with a parameter. shouldn't happen.".
58 "Stack trace:\n".
59 $return2->backtrace;
60 }
61 my @return2_array = @{$return2}; # TODO: does this work
63 my @return2_array2 = $return2->as_array;
64
66 new Instantiate a new Class::ReturnValue object
67 as_array
69 Return the 'as_array' attribute of this object as an array.
70 as_array [ARRAY]
72 If $self is called in an array context, returns the array specified
73 in ARRAY
74 as_error HASH
76 Turns this return-value object into an error return object. TAkes
77 three parameters:
78 message
80 do_backtrace
81 errno
82 'message' is a human readable error message explaining what's going on
84 'do_backtrace' is a boolean. If it's true, a carp-style backtrace will be
86 stored in $self->{'backtrace'}. It defaults to true
87 errno and message default to undef. errno _must_ be specified.
89 It's a numeric error number. Any true integer value will cause the
90 object to evaluate to false in a scalar context. At first, this may look a
91 bit counterintuitive, but it means that you can have error codes and still
92 allow simple use of your functions in a style like this:
93 if ($obj->do_something) {
96 print "Yay! it worked";
97 } else {
98 print "Sorry. there's been an error.";
99 }
100 as well as more complex use like this:
103 my $retval = $obj->do_something;
105 if ($retval) {
107 print "Yay. we did something\n";
108 my ($foo, $bar, $baz) = @{$retval};
109 my $human_readable_return = $retval;
110 } else {
111 if ($retval->errno == 20) {
112 die "Failed with error 20 (Not enough monkeys).";
113 } else {
114 die $retval->backtrace; # Die and print out a backtrace
115 }
116 }
117 errno
119 Returns the errno if there's been an error. Otherwise, return undef
120 error_message
122 If there's been an error return the error message.
123 backtrace
125 If there's been an error and we asked for a backtrace, return the
126 backtrace. Otherwise, return undef.
127 error_condition
129 If there's been an error, return undef. Otherwise return 1
130
132 Jesse Vincent <jesse@bestpractical.com>
133
135 This module has, as yet, not been used in production code. I thing
136 it should work, but have never benchmarked it. I have not yet used
137 it extensively, though I do plan to in the not-too-distant future.
138 If you have questions or comments, please write me.
139 If you need to report a bug, please send mail to
141 <bug-class-returnvalue@rt.cpan.org> or report your error on the web
142 at http://rt.cpan.org/
143
145 Copyright (c) 2002,2003,2005,2007 Jesse Vincent <jesse@bestpractical.com>
146 You may use, modify, fold, spindle or mutilate this module under
147 the same terms as perl itself.
148
150 Class::ReturnValue isn't an exception handler. If it doesn't
151 do what you want, you might want look at one of the exception handlers
152 below:
153 Error, Exception, Exceptions, Exceptions::Class
155 You might also want to look at Contextual::Return, another implementation
157 of the same concept as this module.
158
160 Hey! The above document had some coding errors, which are explained
161 below:
162 Around line 97:
164 '=item' outside of any '=over'
165 Around line 264:
167 =cut found outside a pod block. Skipping to next block.
168 Around line 296:
170 You forgot a '=back' before '=head1'
171perl v5.12.0 2007-08-20 Class::ReturnValue(3)