/extlib/man/man3/Error.3pm
Unknown | 517 lines | 517 code | 0 blank | 0 comment | 0 complexity | b933917b8213d29460a5e1e69b7f8f37 MD5 | raw file
- .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
- .\"
- .\" 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" ''
- '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.
- .ie \nF \{\
- . de IX
- . tm Index:\\$1\t\\n%\t"\\$2"
- ..
- . nr % 0
- . rr F
- .\}
- .el \{\
- . de IX
- ..
- .\}
- .\"
- .\" 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 "Error 3pm"
- .TH Error 3pm "2010-05-08" "perl v5.10.0" "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"
- Error \- Error/exception handling in an OO\-ish way
- .SH "WARNING"
- .IX Header "WARNING"
- Using the \*(L"Error\*(R" module is \fBno longer recommended\fR due to the black-magical
- nature of its syntactic sugar, which often tends to break. Its maintainers
- have stopped actively writing code that uses it, and discourage people
- from doing so. See the \*(L"\s-1SEE\s0 \s-1ALSO\s0\*(R" section below for better recommendations.
- .SH "SYNOPSIS"
- .IX Header "SYNOPSIS"
- .Vb 1
- \& use Error qw(:try);
- \&
- \& throw Error::Simple( "A simple error");
- \&
- \& sub xyz {
- \& ...
- \& record Error::Simple("A simple error")
- \& and return;
- \& }
- \&
- \& unlink($file) or throw Error::Simple("$file: $!",$!);
- \&
- \& try {
- \& do_some_stuff();
- \& die "error!" if $condition;
- \& throw Error::Simple "Oops!" if $other_condition;
- \& }
- \& catch Error::IO with {
- \& my $E = shift;
- \& print STDERR "File ", $E\->{\*(Aq\-file\*(Aq}, " had a problem\en";
- \& }
- \& except {
- \& my $E = shift;
- \& my $general_handler=sub {send_message $E\->{\-description}};
- \& return {
- \& UserException1 => $general_handler,
- \& UserException2 => $general_handler
- \& };
- \& }
- \& otherwise {
- \& print STDERR "Well I don\*(Aqt know what to say\en";
- \& }
- \& finally {
- \& close_the_garage_door_already(); # Should be reliable
- \& }; # Don\*(Aqt forget the trailing ; or you might be surprised
- .Ve
- .SH "DESCRIPTION"
- .IX Header "DESCRIPTION"
- The \f(CW\*(C`Error\*(C'\fR package provides two interfaces. Firstly \f(CW\*(C`Error\*(C'\fR provides
- a procedural interface to exception handling. Secondly \f(CW\*(C`Error\*(C'\fR is a
- base class for errors/exceptions that can either be thrown, for
- subsequent catch, or can simply be recorded.
- .PP
- Errors in the class \f(CW\*(C`Error\*(C'\fR should not be thrown directly, but the
- user should throw errors from a sub-class of \f(CW\*(C`Error\*(C'\fR.
- .SH "PROCEDURAL INTERFACE"
- .IX Header "PROCEDURAL INTERFACE"
- \&\f(CW\*(C`Error\*(C'\fR exports subroutines to perform exception handling. These will
- be exported if the \f(CW\*(C`:try\*(C'\fR tag is used in the \f(CW\*(C`use\*(C'\fR line.
- .IP "try \s-1BLOCK\s0 \s-1CLAUSES\s0" 4
- .IX Item "try BLOCK CLAUSES"
- \&\f(CW\*(C`try\*(C'\fR is the main subroutine called by the user. All other subroutines
- exported are clauses to the try subroutine.
- .Sp
- The \s-1BLOCK\s0 will be evaluated and, if no error is throw, try will return
- the result of the block.
- .Sp
- \&\f(CW\*(C`CLAUSES\*(C'\fR are the subroutines below, which describe what to do in the
- event of an error being thrown within \s-1BLOCK\s0.
- .IP "catch \s-1CLASS\s0 with \s-1BLOCK\s0" 4
- .IX Item "catch CLASS with BLOCK"
- This clauses will cause all errors that satisfy \f(CW\*(C`$err\->isa(CLASS)\*(C'\fR
- to be caught and handled by evaluating \f(CW\*(C`BLOCK\*(C'\fR.
- .Sp
- \&\f(CW\*(C`BLOCK\*(C'\fR will be passed two arguments. The first will be the error
- being thrown. The second is a reference to a scalar variable. If this
- variable is set by the catch block then, on return from the catch
- block, try will continue processing as if the catch block was never
- found. The error will also be available in \f(CW$@\fR.
- .Sp
- To propagate the error the catch block may call \f(CW\*(C`$err\->throw\*(C'\fR
- .Sp
- If the scalar reference by the second argument is not set, and the
- error is not thrown. Then the current try block will return with the
- result from the catch block.
- .IP "except \s-1BLOCK\s0" 4
- .IX Item "except BLOCK"
- When \f(CW\*(C`try\*(C'\fR is looking for a handler, if an except clause is found
- \&\f(CW\*(C`BLOCK\*(C'\fR is evaluated. The return value from this block should be a
- \&\s-1HASHREF\s0 or a list of key-value pairs, where the keys are class names
- and the values are \s-1CODE\s0 references for the handler of errors of that
- type.
- .IP "otherwise \s-1BLOCK\s0" 4
- .IX Item "otherwise BLOCK"
- Catch any error by executing the code in \f(CW\*(C`BLOCK\*(C'\fR
- .Sp
- When evaluated \f(CW\*(C`BLOCK\*(C'\fR will be passed one argument, which will be the
- error being processed. The error will also be available in \f(CW$@\fR.
- .Sp
- Only one otherwise block may be specified per try block
- .IP "finally \s-1BLOCK\s0" 4
- .IX Item "finally BLOCK"
- Execute the code in \f(CW\*(C`BLOCK\*(C'\fR either after the code in the try block has
- successfully completed, or if the try block throws an error then
- \&\f(CW\*(C`BLOCK\*(C'\fR will be executed after the handler has completed.
- .Sp
- If the handler throws an error then the error will be caught, the
- finally block will be executed and the error will be re-thrown.
- .Sp
- Only one finally block may be specified per try block
- .SH "COMPATIBILITY"
- .IX Header "COMPATIBILITY"
- Moose exports a keyword called \f(CW\*(C`with\*(C'\fR which clashes with Error's. This
- example returns a prototype mismatch error:
- .PP
- .Vb 1
- \& package MyTest;
- \&
- \& use warnings;
- \& use Moose;
- \& use Error qw(:try);
- .Ve
- .PP
- (Thanks to \f(CW\*(C`maik.hentsche@amd.com\*(C'\fR for the report.).
- .SH "CLASS INTERFACE"
- .IX Header "CLASS INTERFACE"
- .SS "\s-1CONSTRUCTORS\s0"
- .IX Subsection "CONSTRUCTORS"
- The \f(CW\*(C`Error\*(C'\fR object is implemented as a \s-1HASH\s0. This \s-1HASH\s0 is initialized
- with the arguments that are passed to it's constructor. The elements
- that are used by, or are retrievable by the \f(CW\*(C`Error\*(C'\fR class are listed
- below, other classes may add to these.
- .PP
- .Vb 5
- \& \-file
- \& \-line
- \& \-text
- \& \-value
- \& \-object
- .Ve
- .PP
- If \f(CW\*(C`\-file\*(C'\fR or \f(CW\*(C`\-line\*(C'\fR are not specified in the constructor arguments
- then these will be initialized with the file name and line number where
- the constructor was called from.
- .PP
- If the error is associated with an object then the object should be
- passed as the \f(CW\*(C`\-object\*(C'\fR argument. This will allow the \f(CW\*(C`Error\*(C'\fR package
- to associate the error with the object.
- .PP
- The \f(CW\*(C`Error\*(C'\fR package remembers the last error created, and also the
- last error associated with a package. This could either be the last
- error created by a sub in that package, or the last error which passed
- an object blessed into that package as the \f(CW\*(C`\-object\*(C'\fR argument.
- .IP "Error\->\fInew()\fR" 4
- .IX Item "Error->new()"
- See the Error::Simple documentation.
- .IP "throw ( [ \s-1ARGS\s0 ] )" 4
- .IX Item "throw ( [ ARGS ] )"
- Create a new \f(CW\*(C`Error\*(C'\fR object and throw an error, which will be caught
- by a surrounding \f(CW\*(C`try\*(C'\fR block, if there is one. Otherwise it will cause
- the program to exit.
- .Sp
- \&\f(CW\*(C`throw\*(C'\fR may also be called on an existing error to re-throw it.
- .IP "with ( [ \s-1ARGS\s0 ] )" 4
- .IX Item "with ( [ ARGS ] )"
- Create a new \f(CW\*(C`Error\*(C'\fR object and returns it. This is defined for
- syntactic sugar, eg
- .Sp
- .Vb 1
- \& die with Some::Error ( ... );
- .Ve
- .IP "record ( [ \s-1ARGS\s0 ] )" 4
- .IX Item "record ( [ ARGS ] )"
- Create a new \f(CW\*(C`Error\*(C'\fR object and returns it. This is defined for
- syntactic sugar, eg
- .Sp
- .Vb 2
- \& record Some::Error ( ... )
- \& and return;
- .Ve
- .SS "\s-1STATIC\s0 \s-1METHODS\s0"
- .IX Subsection "STATIC METHODS"
- .IP "prior ( [ \s-1PACKAGE\s0 ] )" 4
- .IX Item "prior ( [ PACKAGE ] )"
- Return the last error created, or the last error associated with
- \&\f(CW\*(C`PACKAGE\*(C'\fR
- .IP "flush ( [ \s-1PACKAGE\s0 ] )" 4
- .IX Item "flush ( [ PACKAGE ] )"
- Flush the last error created, or the last error associated with
- \&\f(CW\*(C`PACKAGE\*(C'\fR.It is necessary to clear the error stack before exiting the
- package or uncaught errors generated using \f(CW\*(C`record\*(C'\fR will be reported.
- .Sp
- .Vb 1
- \& $Error\->flush;
- .Ve
- .SS "\s-1OBJECT\s0 \s-1METHODS\s0"
- .IX Subsection "OBJECT METHODS"
- .IP "stacktrace" 4
- .IX Item "stacktrace"
- If the variable \f(CW$Error::Debug\fR was non-zero when the error was
- created, then \f(CW\*(C`stacktrace\*(C'\fR returns a string created by calling
- \&\f(CW\*(C`Carp::longmess\*(C'\fR. If the variable was zero the \f(CW\*(C`stacktrace\*(C'\fR returns
- the text of the error appended with the filename and line number of
- where the error was created, providing the text does not end with a
- newline.
- .IP "object" 4
- .IX Item "object"
- The object this error was associated with
- .IP "file" 4
- .IX Item "file"
- The file where the constructor of this error was called from
- .IP "line" 4
- .IX Item "line"
- The line where the constructor of this error was called from
- .IP "text" 4
- .IX Item "text"
- The text of the error
- .ie n .IP "$err\->associate($obj)" 4
- .el .IP "\f(CW$err\fR\->associate($obj)" 4
- .IX Item "$err->associate($obj)"
- Associates an error with an object to allow error propagation. I.e:
- .Sp
- .Vb 2
- \& $ber\->encode(...) or
- \& return Error\->prior($ber)\->associate($ldap);
- .Ve
- .SS "\s-1OVERLOAD\s0 \s-1METHODS\s0"
- .IX Subsection "OVERLOAD METHODS"
- .IP "stringify" 4
- .IX Item "stringify"
- A method that converts the object into a string. This method may simply
- return the same as the \f(CW\*(C`text\*(C'\fR method, or it may append more
- information. For example the file name and line number.
- .Sp
- By default this method returns the \f(CW\*(C`\-text\*(C'\fR argument that was passed to
- the constructor, or the string \f(CW"Died"\fR if none was given.
- .IP "value" 4
- .IX Item "value"
- A method that will return a value that can be associated with the
- error. For example if an error was created due to the failure of a
- system call, then this may return the numeric value of \f(CW$!\fR at the
- time.
- .Sp
- By default this method returns the \f(CW\*(C`\-value\*(C'\fR argument that was passed
- to the constructor.
- .SH "PRE-DEFINED ERROR CLASSES"
- .IX Header "PRE-DEFINED ERROR CLASSES"
- .SS "Error::Simple"
- .IX Subsection "Error::Simple"
- This class can be used to hold simple error strings and values. It's
- constructor takes two arguments. The first is a text value, the second
- is a numeric value. These values are what will be returned by the
- overload methods.
- .PP
- If the text value ends with \f(CW\*(C`at file line 1\*(C'\fR as $@ strings do, then
- this infomation will be used to set the \f(CW\*(C`\-file\*(C'\fR and \f(CW\*(C`\-line\*(C'\fR arguments
- of the error object.
- .PP
- This class is used internally if an eval'd block die's with an error
- that is a plain string. (Unless \f(CW$Error::ObjectifyCallback\fR is modified)
- .ie n .SH "$Error::ObjectifyCallback"
- .el .SH "\f(CW$Error::ObjectifyCallback\fP"
- .IX Header "$Error::ObjectifyCallback"
- This variable holds a reference to a subroutine that converts errors that
- are plain strings to objects. It is used by Error.pm to convert textual
- errors to objects, and can be overrided by the user.
- .PP
- It accepts a single argument which is a hash reference to named parameters.
- Currently the only named parameter passed is \f(CW\*(Aqtext\*(Aq\fR which is the text
- of the error, but others may be available in the future.
- .PP
- For example the following code will cause Error.pm to throw objects of the
- class MyError::Bar by default:
- .PP
- .Vb 7
- \& sub throw_MyError_Bar
- \& {
- \& my $args = shift;
- \& my $err = MyError::Bar\->new();
- \& $err\->{\*(AqMyBarText\*(Aq} = $args\->{\*(Aqtext\*(Aq};
- \& return $err;
- \& }
- \&
- \& {
- \& local $Error::ObjectifyCallback = \e&throw_MyError_Bar;
- \&
- \& # Error handling here.
- \& }
- .Ve
- .SH "MESSAGE HANDLERS"
- .IX Header "MESSAGE HANDLERS"
- \&\f(CW\*(C`Error\*(C'\fR also provides handlers to extend the output of the \f(CW\*(C`warn()\*(C'\fR perl
- function, and to handle the printing of a thrown \f(CW\*(C`Error\*(C'\fR that is not caught
- or otherwise handled. These are not installed by default, but are requested
- using the \f(CW\*(C`:warndie\*(C'\fR tag in the \f(CW\*(C`use\*(C'\fR line.
- .PP
- .Vb 1
- \& use Error qw( :warndie );
- .Ve
- .PP
- These new error handlers are installed in \f(CW$SIG{_\|_WARN_\|_}\fR and
- \&\f(CW$SIG{_\|_DIE_\|_}\fR. If these handlers are already defined when the tag is
- imported, the old values are stored, and used during the new code. Thus, to
- arrange for custom handling of warnings and errors, you will need to perform
- something like the following:
- .PP
- .Vb 5
- \& BEGIN {
- \& $SIG{_\|_WARN_\|_} = sub {
- \& print STDERR "My special warning handler: $_[0]"
- \& };
- \& }
- \&
- \& use Error qw( :warndie );
- .Ve
- .PP
- Note that setting \f(CW$SIG{_\|_WARN_\|_}\fR after the \f(CW\*(C`:warndie\*(C'\fR tag has been
- imported will overwrite the handler that \f(CW\*(C`Error\*(C'\fR provides. If this cannot be
- avoided, then the tag can be explicitly \f(CW\*(C`import\*(C'\fRed later
- .PP
- .Vb 1
- \& use Error;
- \&
- \& $SIG{_\|_WARN_\|_} = ...;
- \&
- \& import Error qw( :warndie );
- .Ve
- .SS "\s-1EXAMPLE\s0"
- .IX Subsection "EXAMPLE"
- The \f(CW\*(C`_\|_DIE_\|_\*(C'\fR handler turns messages such as
- .PP
- .Vb 1
- \& Can\*(Aqt call method "foo" on an undefined value at examples/warndie.pl line 16.
- .Ve
- .PP
- into
- .PP
- .Vb 1
- \& Unhandled perl error caught at toplevel:
- \&
- \& Can\*(Aqt call method "foo" on an undefined value
- \&
- \& Thrown from: examples/warndie.pl:16
- \&
- \& Full stack trace:
- \&
- \& main::inner(\*(Aqundef\*(Aq) called at examples/warndie.pl line 20
- \& main::outer(\*(Aqundef\*(Aq) called at examples/warndie.pl line 23
- .Ve
- .SH "SEE ALSO"
- .IX Header "SEE ALSO"
- See Exception::Class for a different module providing Object-Oriented
- exception handling, along with a convenient syntax for declaring hierarchies
- for them. It doesn't provide Error's syntactic sugar of \f(CW\*(C`try { ... }\*(C'\fR,
- \&\f(CW\*(C`catch { ... }\*(C'\fR, etc. which may be a good thing or a bad thing based
- on what you want. (Because Error's syntactic sugar tends to break.)
- .PP
- Error::Exception aims to combine Error and Exception::Class
- \&\*(L"with correct stringification\*(R".
- .PP
- TryCatch and Try::Tiny are similar in concept to Error.pm only providing
- a syntax that hopefully breaks less.
- .SH "KNOWN BUGS"
- .IX Header "KNOWN BUGS"
- None, but that does not mean there are not any.
- .SH "AUTHORS"
- .IX Header "AUTHORS"
- Graham Barr <gbarr@pobox.com>
- .PP
- The code that inspired me to write this was originally written by
- Peter Seibel <peter@weblogic.com> and adapted by Jesse Glick
- <jglick@sig.bsh.com>.
- .PP
- \&\f(CW\*(C`:warndie\*(C'\fR handlers added by Paul Evans <leonerd@leonerd.org.uk>
- .SH "MAINTAINER"
- .IX Header "MAINTAINER"
- Shlomi Fish <shlomif@iglu.org.il>
- .SH "PAST MAINTAINERS"
- .IX Header "PAST MAINTAINERS"
- Arun Kumar U <u_arunkumar@yahoo.com>
- .SH "COPYRIGHT"
- .IX Header "COPYRIGHT"
- Copyright (c) 1997\-8 Graham Barr. All rights reserved.
- This program is free software; you can redistribute it and/or modify it
- under the same terms as Perl itself.