.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Class::ReturnValue 3pm" .TH Class::ReturnValue 3pm "2007-08-20" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Class::ReturnValue \- A return\-value object that lets you treat it as as a boolean, array or object .SH "DESCRIPTION" .IX Header "DESCRIPTION" Class::ReturnValue is a \*(L"clever\*(R" return value object that can allow code calling your routine to expect: a boolean value (did it fail) or a list (what are the return values) .SH "EXAMPLE" .IX Header "EXAMPLE" .Vb 4 \& sub demo { \& my $value = shift; \& my $ret = Class::ReturnValue\->new(); \& $ret\->as_array(\*(Aq0\*(Aq, \*(AqNo results found\*(Aq); \& \& unless($value) { \& $ret\->as_error(errno => \*(Aq1\*(Aq, \& message => "You didn\*(Aqt supply a parameter.", \& do_backtrace => 1); \& } \& \& return($ret\->return_value); \& } \& \& if (demo(\*(Aqfoo\*(Aq)){ \& print "the routine succeeded with one parameter"; \& } \& if (demo()) { \& print "The routine succeeded with 0 paramters. shouldn\*(Aqt happen"; \& } else { \& print "The routine failed with 0 parameters (as it should)."; \& } \& \& \& my $return = demo(); \& if ($return) { \& print "The routine succeeded with 0 paramters. shouldn\*(Aqt happen"; \& } else { \& print "The routine failed with 0 parameters (as it should). ". \& "Stack trace:\en". \& $return\->backtrace; \& } \& \& my @return3 = demo(\*(Aqfoo\*(Aq); \& print "The routine got ".join(\*(Aq,\*(Aq,@return3). \& "when asking for demo\*(Aqs results as an array"; \& \& \& my $return2 = demo(\*(Aqfoo\*(Aq); \& \& unless ($return2) { \& print "The routine failed with a parameter. shouldn\*(Aqt happen.". \& "Stack trace:\en". \& $return2\->backtrace; \& } \& \& my @return2_array = @{$return2}; # TODO: does this work \& my @return2_array2 = $return2\->as_array; .Ve .SH "METHODS" .IX Header "METHODS" .IP "new" 4 .IX Item "new" Instantiate a new Class::ReturnValue object .IP "as_array" 4 .IX Item "as_array" Return the 'as_array' attribute of this object as an array. .IP "as_array [\s-1ARRAY\s0]" 4 .IX Item "as_array [ARRAY]" If \f(CW$self\fR is called in an array context, returns the array specified in \s-1ARRAY\s0 .IP "as_error \s-1HASH\s0" 4 .IX Item "as_error HASH" Turns this return-value object into an error return object. TAkes three parameters: .Sp .Vb 3 \& message \& do_backtrace \& errno \& \& \*(Aqmessage\*(Aq is a human readable error message explaining what\*(Aqs going on \& \& \*(Aqdo_backtrace\*(Aq is a boolean. If it\*(Aqs true, a carp\-style backtrace will be \& stored in $self\->{\*(Aqbacktrace\*(Aq}. It defaults to true \& \& errno and message default to undef. errno _must_ be specified. \& It\*(Aqs a numeric error number. Any true integer value will cause the \& object to evaluate to false in a scalar context. At first, this may look a \& bit counterintuitive, but it means that you can have error codes and still \& allow simple use of your functions in a style like this: \& \& \& if ($obj\->do_something) { \& print "Yay! it worked"; \& } else { \& print "Sorry. there\*(Aqs been an error."; \& } \& \& \& as well as more complex use like this: \& \& my $retval = $obj\->do_something; \& \& if ($retval) { \& print "Yay. we did something\en"; \& my ($foo, $bar, $baz) = @{$retval}; \& my $human_readable_return = $retval; \& } else { \& if ($retval\->errno == 20) { \& die "Failed with error 20 (Not enough monkeys)."; \& } else { \& die $retval\->backtrace; # Die and print out a backtrace \& } \& } .Ve .IP "errno" 4 .IX Item "errno" Returns the errno if there's been an error. Otherwise, return undef .IP "error_message" 4 .IX Item "error_message" If there's been an error return the error message. .IP "backtrace" 4 .IX Item "backtrace" If there's been an error and we asked for a backtrace, return the backtrace. Otherwise, return undef. .IP "error_condition" 4 .IX Item "error_condition" If there's been an error, return undef. Otherwise return 1 .SH "AUTHOR" .IX Header "AUTHOR" .Vb 1 \& Jesse Vincent .Ve .SH "BUGS" .IX Header "BUGS" .Vb 4 \& This module has, as yet, not been used in production code. I thing \& it should work, but have never benchmarked it. I have not yet used \& it extensively, though I do plan to in the not\-too\-distant future. \& If you have questions or comments, please write me. \& \& If you need to report a bug, please send mail to \& or report your error on the web \& at http://rt.cpan.org/ .Ve .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 3 \& Copyright (c) 2002,2003,2005,2007 Jesse Vincent \& You may use, modify, fold, spindle or mutilate this module under \& the same terms as perl itself. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 3 \& Class::ReturnValue isn\*(Aqt an exception handler. If it doesn\*(Aqt \& do what you want, you might want look at one of the exception handlers \& below: \& \& Error, Exception, Exceptions, Exceptions::Class \& \& You might also want to look at Contextual::Return, another implementation \& of the same concept as this module. .Ve .SH "POD ERRORS" .IX Header "POD ERRORS" Hey! \fBThe above document had some coding errors, which are explained below:\fR .IP "Around line 97:" 4 .IX Item "Around line 97:" \&'=item' outside of any '=over' .IP "Around line 264:" 4 .IX Item "Around line 264:" =cut found outside a pod block. Skipping to next block. .IP "Around line 296:" 4 .IX Item "Around line 296:" You forgot a '=back' before '=head1'