1Class::ReturnValue(3) User Contributed Perl DocumentationClass::ReturnValue(3)
2
3
4

NAME

6       Class::ReturnValue - A return-value object that lets you treat it as as
7       a boolean, array or object
8

DESCRIPTION

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

EXAMPLE

16           sub demo {
17               my $value = shift;
18               my $ret = Class::ReturnValue->new();
19               $ret->as_array('0', 'No results found');
20
21               unless($value) {
22                   $ret->as_error(errno => '1',
23                                      message => "You didn't supply a parameter.",
24                                      do_backtrace => 1);
25               }
26
27               return($ret->return_value);
28           }
29
30           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
39
40           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
49           my @return3 = demo('foo');
50           print "The routine got ".join(',',@return3).
51                 "when asking for demo's results as an array";
52
53
54           my $return2 = demo('foo');
55
56           unless ($return2) {
57               print "The routine failed with a parameter. shouldn't happen.".
58                    "Stack trace:\n".
59               $return2->backtrace;
60           }
61
62           my @return2_array = @{$return2}; # TODO: does this work
63           my @return2_array2 = $return2->as_array;
64

METHODS

66       new Instantiate a new Class::ReturnValue object
67
68       as_array
69           Return the 'as_array' attribute of this object as an array.
70
71       as_array [ARRAY]
72           If $self is called in an array context, returns the array specified
73           in ARRAY
74
75       as_error HASH
76           Turns this return-value object into  an error return object.  TAkes
77           three parameters:
78
79               message
80               do_backtrace
81               errno
82
83               'message' is a human readable error message explaining what's going on
84
85               '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
88               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
94
95                   if ($obj->do_something) {
96                       print "Yay! it worked";
97                   } else {
98                       print "Sorry. there's been an error.";
99                   }
100
101
102                   as well as more complex use like this:
103
104                   my $retval = $obj->do_something;
105
106                   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
118       errno
119           Returns the errno if there's been an error. Otherwise, return undef
120
121       error_message
122           If there's been an error return the error message.
123
124       backtrace
125           If there's been an error and we asked for a backtrace, return the
126           backtrace.  Otherwise, return undef.
127
128       error_condition
129           If there's been an error, return undef. Otherwise return 1
130

AUTHOR

132           Jesse Vincent <jesse@bestpractical.com>
133

BUGS

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
140           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

SEE ALSO

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
154           Error, Exception, Exceptions, Exceptions::Class
155
156           You might also want to look at Contextual::Return, another implementation
157           of the same concept as this module.
158

POD ERRORS

160       Hey! The above document had some coding errors, which are explained
161       below:
162
163       Around line 97:
164           '=item' outside of any '=over'
165
166       Around line 264:
167           =cut found outside a pod block.  Skipping to next block.
168
169       Around line 296:
170           You forgot a '=back' before '=head1'
171
172
173
174perl v5.12.0                      2007-08-20             Class::ReturnValue(3)
Impressum