Class::ReturnValue(3pm)

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 val‐
13       ues)
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           my $return = demo();
40           if ($return) {
41               print "The routine succeeded with 0 paramters. shouldn't happen";
42           } else {
43               print "The routine failed with 0 parameters (as it should). ".
44                     "Stack trace:\n".
45               $return->backtrace;
46           }
47
48           my @return3 = demo('foo');
49           print "The routine got ".join(',',@return3).
50                 "when asking for demo's results as an array";
51
52           my $return2 = demo('foo');
53
54           unless ($return2) {
55               print "The routine failed with a parameter. shouldn't happen.".
56                    "Stack trace:\n".
57               $return2->backtrace;
58           }
59
60           my @return2_array = @{$return2}; # TODO: does this work
61           my @return2_array2 = $return2->as_array;
62

METHODS

64new
65Instantiate a new Class::ReturnValue object
66
67as_array
68Return the 'as_array' attribute of this object as an array.
69
70as_array [ARRAY]
71If $self is called in an array context, returns the array specified in ARRAY
72
73as_error HASH
74Turns this return-value object into  an error return object.  TAkes three
75parameters:
76
77    message
78    do_backtrace
79    errno
80
81    'message' is a human readable error message explaining what's going on
82
83    'do_backtrace' is a boolean. If it's true, a carp-style backtrace will be
84    stored in $self->{'backtrace'}. It defaults to true
85
86    errno and message default to undef. errno _must_ be specified.
87    It's a numeric error number.  Any true integer value  will cause the
88    object to evaluate to false in a scalar context. At first, this may look a
89    bit counterintuitive, but it means that you can have error codes and still
90    allow simple use of your functions in a style like this:
91
92        if ($obj->do_something) {
93            print "Yay! it worked";
94        } else {
95            print "Sorry. there's been an error.";
96        }
97
98        as well as more complex use like this:
99
100        my $retval = $obj->do_something;
101
102        if ($retval) {
103            print "Yay. we did something\n";
104            my ($foo, $bar, $baz) = @{$retval};
105            my $human_readable_return = $retval;
106        } else {
107            if ($retval->errno == 20) {
108                die "Failed with error 20 (Not enough monkeys).";
109            } else {
110                die  $retval->backtrace; # Die and print out a backtrace
111            }
112        }
113
114errno
115Returns the errno if there's been an error. Otherwise, return undef
116
117error_message
118If there's been an error return the error message.
119
120backtrace
121If there's been an error and we asked for a backtrace, return the backtrace.
122Otherwise, return undef.
123
124error_condition
125If there's been an error, return undef. Otherwise return 1
126

AUTHOR

128           Jesse Vincent <jesse@bestpractical.com>
129

BUGS

131           This module has, as yet, not been used in production code. I thing
132           it should work, but have never benchmarked it. I have not yet used
133           it extensively, though I do plan to in the not-too-distant future.
134           If you have questions or comments,  please write me.
135
136           If you need to report a bug, please send mail to
137           <bug-class-returnvalue@rt.cpan.org> or report your error on the web
138           at http://rt.cpan.org/
139

COPYRIGHT

141           Copyright (c) 2002,2003,2005,2007 Jesse Vincent <jesse@bestpractical.com>
142           You may use, modify, fold, spindle or mutilate this module under
143           the same terms as perl itself.
144