.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .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. | will give a .\" real vertical bar. \*(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-|\(bv\*(Tr .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" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" 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 "Zoidberg::Utils::Error 3" .TH Zoidberg::Utils::Error 3 "2008-01-12" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" Zoidberg::Utils::Error \- OO error handling .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Zoidberg::Utils qw/:error/; .Ve .PP .Vb 5 \& sub some_command { \& error "Wrong number of arguments" \& unless scalar(@_) == 3; \& # do stuff \& } .Ve .PP .Vb 1 \& # this raises an object oriented exception .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This library supplies the methods to replace \f(CW\*(C`die()\*(C'\fR. These methods raise an exception but passing a object containing both the error string and caller information. Thus, when the exception is caught, more subtle error messages can be produced depending on for example verbosity settings. .PP If the global variable \f(CW$ERROR_CALLER\fR is set in a package using this library, all errors will pretend to originate from the call-frame identified by the number of the variable. Setting \f(CW$ERROR_CALLER\fR to 1 will result in Carp like behaviour. .PP Although when working within the Zoidberg framework this module should be used through the Zoidberg::Utils interface, it also can be used on it's own. .SH "EXPORT" .IX Header "EXPORT" By default \f(CW\*(C`error()\*(C'\fR, \f(CW\*(C`bug()\*(C'\fR and \f(CW\*(C`todo()\*(C'\fR. When using the Zoidberg::Utils interface you also get \f(CW\*(C`complain()\*(C'\fR, which actually belongs to Zoidberg::Utils::Output. .SH "METHODS" .IX Header "METHODS" .Sh "Exported methods" .IX Subsection "Exported methods" .ie n .IP """error($error, ..)""" 4 .el .IP "\f(CWerror($error, ..)\fR" 4 .IX Item "error($error, ..)" Raises an exception which passes on \f(CW\*(C`\e%error\*(C'\fR. .ie n .IP """bug($error, ..)""" 4 .el .IP "\f(CWbug($error, ..)\fR" 4 .IX Item "bug($error, ..)" Like \f(CW\*(C`error()\*(C'\fR, but with \f(CW\*(C`is_bug\*(C'\fR field set. .ie n .IP """todo($error, ..)""" 4 .el .IP "\f(CWtodo($error, ..)\fR" 4 .IX Item "todo($error, ..)" Like \f(CW\*(C`error()\*(C'\fR, but with \f(CW\*(C`is_todo\*(C'\fR field set. .Sh "Object methods" .IX Subsection "Object methods" .ie n .IP """stringify(%opts)""" 4 .el .IP "\f(CWstringify(%opts)\fR" 4 .IX Item "stringify(%opts)" Returns an error string. .Sp Known options: .RS 4 .IP "format" 4 .IX Item "format" Types 'gnu' and 'perl' are supported. The format 'perl' is the default, 'gnu' is used by zoidberg's \f(CW\*(C`complain()\*(C'\fR function. .RE .RS 4 .RE .ie n .IP """PROPAGATE($file, $line)""" 4 .el .IP "\f(CWPROPAGATE($file, $line)\fR" 4 .IX Item "PROPAGATE($file, $line)" Is automaticly called by \f(CW\*(C`die()\*(C'\fR when you use for example: .Sp .Vb 1 \& use Zoidberg::Utils::Error; .Ve .Sp .Vb 2 \& eval { error 'test' } \& die if $@; # die is called without explicit argument ! .Ve .Sp See also \*(L"die\*(R" in perlfunc. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" The exception raised can have the folowing attributes: .IP "string" 4 .IX Item "string" Original error string. .IP "scope" 4 .IX Item "scope" The global \f(CW$Zoidberg::Utils::Error::Scope\fR at the time of the exception. This is used to hide the real caller information in the gnu formatted error string with for example the name of a builtin command. .IP "package" 4 .IX Item "package" Calling package. .IP "file" 4 .IX Item "file" Source file where the exception was raised. .IP "line" 4 .IX Item "line" Line in source file where the exception was raised. .IP "debug" 4 .IX Item "debug" The calling package had the global variable \f(CW$DEBUG\fR set to a non-zero value. .IP "stack" 4 .IX Item "stack" When debug was in effect, the caller stack is traced for a number of frames equal to the value of the debug variable and put in the stack attribute. .IP "is_bug" 4 .IX Item "is_bug" This exception should never happen, if it does this is considered a bug. .IP "is_todo" 4 .IX Item "is_todo" This exception is raised because some feature isn't yet implemented. .IP "propagated" 4 .IX Item "propagated" Array of arrays containg information about file and line numbers where this error was propagated, see \*(L"\s-1PROPAGATE\s0\*(R". .Sh "Overloading" .IX Subsection "Overloading" When the methods are given a hash reference as one of there arguments this hash overloads the default values of \f(CW%error\fR. Thus it is possible to fake for example the calling package, or add meta data to an exception. .SH "AUTHOR" .IX Header "AUTHOR" Jaap Karssenberg || Pardus [Larus] .PP Copyright (c) 2003 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Zoidberg, Zoidberg::Utils,