Current File : //usr/local/share/man/man3/Exception::Class::Base.3

.\" Automatically generated by Pod::Man 2.28 (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 "Exception::Class::Base 3"
.TH Exception::Class::Base 3 "2014-05-05" "perl v5.20.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"
Exception::Class::Base \- A base class for exception objects
.SH "VERSION"
.IX Header "VERSION"
version 1.38
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Exception::Class \*(AqMyException\*(Aq;
\&
\&  eval { MyException\->throw( error => \*(AqI feel funny.\*(Aq ) };
\&
\&  print $@\->error();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is the base class for all exceptions created by
Exception::Class. It provides a number of methods for getting
information about the exception.
.SH "METHODS"
.IX Header "METHODS"
.SS "MyException\->Trace($boolean)"
.IX Subsection "MyException->Trace($boolean)"
Each \f(CW\*(C`Exception::Class::Base\*(C'\fR subclass can be set individually to
include a stacktrace when the \f(CW\*(C`as_string\*(C'\fR method is called.  The
default is to not include a stacktrace.  Calling this method with a
value changes this behavior.  It always returns the current value
(after any change is applied).
.PP
This value is inherited by any subclasses.  However, if this value is
set for a subclass, it will thereafter be independent of the value in
\&\f(CW\*(C`Exception::Class::Base\*(C'\fR.
.PP
Do not call this on the \f(CW\*(C`Exception::Class::Base\*(C'\fR class directly or
you'll change it for all exception classes that use
Exception::Class, including ones created in modules you don't
control.
.PP
This is a class method, not an object method.
.SS "MyException\->NoRefs($boolean)"
.IX Subsection "MyException->NoRefs($boolean)"
When a \f(CW\*(C`Devel::StackTrace\*(C'\fR object is created, it walks through the
stack and stores the arguments which were passed to each subroutine on
the stack.  If any of these arguments are references, then that means
that the \f(CW\*(C`Devel::StackTrace\*(C'\fR ends up increasing the refcount of these
references, delaying their destruction.
.PP
Since \f(CW\*(C`Exception::Class::Base\*(C'\fR uses \f(CW\*(C`Devel::StackTrace\*(C'\fR internally,
this method provides a way to tell \f(CW\*(C`Devel::StackTrace\*(C'\fR not to store
these references.  Instead, \f(CW\*(C`Devel::StackTrace\*(C'\fR replaces references
with their stringified representation.
.PP
This method defaults to true.  As with \f(CW\*(C`Trace()\*(C'\fR, it is inherited by
subclasses but setting it in a subclass makes it independent
thereafter.
.PP
Do not call this on the \f(CW\*(C`Exception::Class::Base\*(C'\fR class directly or
you'll change it for all exception classes that use
Exception::Class, including ones created in modules you don't
control.
.SS "MyException\->RespectOverload($boolean)"
.IX Subsection "MyException->RespectOverload($boolean)"
When a \f(CW\*(C`Devel::StackTrace\*(C'\fR object stringifies, by default it ignores
stringification overloading on any objects being dealt with.
.PP
Since \f(CW\*(C`Exception::Class::Base\*(C'\fR uses \f(CW\*(C`Devel::StackTrace\*(C'\fR internally,
this method provides a way to tell \f(CW\*(C`Devel::StackTrace\*(C'\fR to respect
overloading.
.PP
This method defaults to false.  As with \f(CW\*(C`Trace()\*(C'\fR, it is inherited by
subclasses but setting it in a subclass makes it independent
thereafter.
.PP
Do not call this on the \f(CW\*(C`Exception::Class::Base\*(C'\fR class directly or
you'll change it for all exception classes that use
Exception::Class, including ones created in modules you don't
control.
.SS "MyException\->MaxArgLength($boolean)"
.IX Subsection "MyException->MaxArgLength($boolean)"
When a \f(CW\*(C`Devel::StackTrace\*(C'\fR object stringifies, by default it displays
the full argument for each function. This parameter can be used to
limit the maximum length of each argument.
.PP
Since \f(CW\*(C`Exception::Class::Base\*(C'\fR uses \f(CW\*(C`Devel::StackTrace\*(C'\fR internally,
this method provides a way to tell \f(CW\*(C`Devel::StackTrace\*(C'\fR to limit the
length of arguments.
.PP
This method defaults to 0. As with \f(CW\*(C`Trace()\*(C'\fR, it is inherited by
subclasses but setting it in a subclass makes it independent
thereafter.
.PP
Do not call this on the \f(CW\*(C`Exception::Class::Base\*(C'\fR class directly or
you'll change it for all exception classes that use
Exception::Class, including ones created in modules you don't
control.
.SS "MyException\->Fields"
.IX Subsection "MyException->Fields"
This method returns the extra fields defined for the given class, as
a list.
.PP
Do not call this on the \f(CW\*(C`Exception::Class::Base\*(C'\fR class directly or
you'll change it for all exception classes that use
Exception::Class, including ones created in modules you don't
control.
.ie n .SS "MyException\->throw( $message )"
.el .SS "MyException\->throw( \f(CW$message\fP )"
.IX Subsection "MyException->throw( $message )"
.ie n .SS "MyException\->throw( message => $message )"
.el .SS "MyException\->throw( message => \f(CW$message\fP )"
.IX Subsection "MyException->throw( message => $message )"
.ie n .SS "MyException\->throw( error => $error )"
.el .SS "MyException\->throw( error => \f(CW$error\fP )"
.IX Subsection "MyException->throw( error => $error )"
This method creates a new object with the given error message.  If no
error message is given, this will be an empty string.  It then dies
with this object as its argument.
.PP
This method also takes a \f(CW\*(C`show_trace\*(C'\fR parameter which indicates
whether or not the particular exception object being created should
show a stacktrace when its \f(CW\*(C`as_string()\*(C'\fR method is called.  This
overrides the value of \f(CW\*(C`Trace()\*(C'\fR for this class if it is given.
.PP
The frames included in the trace can be controlled by the \f(CW\*(C`ignore_class\*(C'\fR
and \f(CW\*(C`ignore_package\*(C'\fR parameters. These are passed directly to
Devel::Stacktrace's constructor. See \f(CW\*(C`Devel::Stacktrace\*(C'\fR for more details.
.PP
If only a single value is given to the constructor it is assumed to be
the message parameter.
.PP
Additional keys corresponding to the fields defined for the particular
exception subclass will also be accepted.
.SS "MyException\->new(...)"
.IX Subsection "MyException->new(...)"
This method takes the same parameters as \f(CW\*(C`throw()\*(C'\fR, but instead of
dying simply returns a new exception object.
.PP
This method is always called when constructing a new exception object
via the \f(CW\*(C`throw()\*(C'\fR method.
.SS "MyException\->\fIdescription()\fP"
.IX Subsection "MyException->description()"
Returns the description for the given \f(CW\*(C`Exception::Class::Base\*(C'\fR
subclass.  The \f(CW\*(C`Exception::Class::Base\*(C'\fR class's description is
\&\*(L"Generic exception\*(R" (this may change in the future).  This is also an
object method.
.ie n .SS "$exception\->\fIrethrow()\fP"
.el .SS "\f(CW$exception\fP\->\fIrethrow()\fP"
.IX Subsection "$exception->rethrow()"
Simply dies with the object as its sole argument.  It's just syntactic
sugar.  This does not change any of the object's attribute values.
However, it will cause \f(CW\*(C`caller()\*(C'\fR to report the die as coming from
within the \f(CW\*(C`Exception::Class::Base\*(C'\fR class rather than where rethrow
was called.
.PP
Of course, you always have access to the original stacktrace for the
exception object.
.ie n .SS "$exception\->\fImessage()\fP"
.el .SS "\f(CW$exception\fP\->\fImessage()\fP"
.IX Subsection "$exception->message()"
.ie n .SS "$exception\->\fIerror()\fP"
.el .SS "\f(CW$exception\fP\->\fIerror()\fP"
.IX Subsection "$exception->error()"
Returns the error/message associated with the exception.
.ie n .SS "$exception\->\fIpid()\fP"
.el .SS "\f(CW$exception\fP\->\fIpid()\fP"
.IX Subsection "$exception->pid()"
Returns the pid at the time the exception was thrown.
.ie n .SS "$exception\->\fIuid()\fP"
.el .SS "\f(CW$exception\fP\->\fIuid()\fP"
.IX Subsection "$exception->uid()"
Returns the real user id at the time the exception was thrown.
.ie n .SS "$exception\->\fIgid()\fP"
.el .SS "\f(CW$exception\fP\->\fIgid()\fP"
.IX Subsection "$exception->gid()"
Returns the real group id at the time the exception was thrown.
.ie n .SS "$exception\->\fIeuid()\fP"
.el .SS "\f(CW$exception\fP\->\fIeuid()\fP"
.IX Subsection "$exception->euid()"
Returns the effective user id at the time the exception was thrown.
.ie n .SS "$exception\->\fIegid()\fP"
.el .SS "\f(CW$exception\fP\->\fIegid()\fP"
.IX Subsection "$exception->egid()"
Returns the effective group id at the time the exception was thrown.
.ie n .SS "$exception\->\fItime()\fP"
.el .SS "\f(CW$exception\fP\->\fItime()\fP"
.IX Subsection "$exception->time()"
Returns the time in seconds since the epoch at the time the exception
was thrown.
.ie n .SS "$exception\->\fIpackage()\fP"
.el .SS "\f(CW$exception\fP\->\fIpackage()\fP"
.IX Subsection "$exception->package()"
Returns the package from which the exception was thrown.
.ie n .SS "$exception\->\fIfile()\fP"
.el .SS "\f(CW$exception\fP\->\fIfile()\fP"
.IX Subsection "$exception->file()"
Returns the file within which the exception was thrown.
.ie n .SS "$exception\->\fIline()\fP"
.el .SS "\f(CW$exception\fP\->\fIline()\fP"
.IX Subsection "$exception->line()"
Returns the line where the exception was thrown.
.ie n .SS "$exception\->\fIcontext_hash()\fP"
.el .SS "\f(CW$exception\fP\->\fIcontext_hash()\fP"
.IX Subsection "$exception->context_hash()"
Returns a hash reference with the following keys:
.IP "\(bu" 4
time
.IP "\(bu" 4
pid
.IP "\(bu" 4
uid
.IP "\(bu" 4
euid
.IP "\(bu" 4
gid
.IP "\(bu" 4
egid
.ie n .SS "$exception\->\fIfield_hash()\fP"
.el .SS "\f(CW$exception\fP\->\fIfield_hash()\fP"
.IX Subsection "$exception->field_hash()"
Returns a hash reference where the keys are any fields defined for the
exception class and the values are the values associated with the field in the
given object.
.ie n .SS "$exception\->\fItrace()\fP"
.el .SS "\f(CW$exception\fP\->\fItrace()\fP"
.IX Subsection "$exception->trace()"
Returns the trace object associated with the object.
.ie n .SS "$exception\->show_trace($boolean)"
.el .SS "\f(CW$exception\fP\->show_trace($boolean)"
.IX Subsection "$exception->show_trace($boolean)"
This method can be used to set whether or not a stack trace is
included when the as_string method is called or the object is
stringified.
.ie n .SS "$exception\->\fIas_string()\fP"
.el .SS "\f(CW$exception\fP\->\fIas_string()\fP"
.IX Subsection "$exception->as_string()"
Returns a string form of the error message (something like what you'd
expect from die).  If the class or object is set to show traces then
then the full trace is also included.  The result looks like
\&\f(CW\*(C`Carp::confess()\*(C'\fR.
.ie n .SS "$exception\->\fIfull_message()\fP"
.el .SS "\f(CW$exception\fP\->\fIfull_message()\fP"
.IX Subsection "$exception->full_message()"
Called by the \f(CW\*(C`as_string()\*(C'\fR method to get the message.  By default,
this is the same as calling the \f(CW\*(C`message()\*(C'\fR method, but may be
overridden by a subclass.  See below for details.
.SH "LIGHTWEIGHT EXCEPTIONS"
.IX Header "LIGHTWEIGHT EXCEPTIONS"
A lightweight exception is one which records no information about its context
when it is created. This can be achieved by setting \f(CW\*(C`$class\->NoContextInfo()\*(C'\fR to a true value.
.PP
You can make this the default for a class of exceptions by setting it after
creating the class:
.PP
.Vb 4
\&  use Exception::Class (
\&      \*(AqLightWeight\*(Aq,
\&      \*(AqHeavyWeight\*(Aq,
\&  );
\&
\&  LightWeight\->NoContextInfo(1);
.Ve
.PP
A lightweight exception does have a stack trace object, nor does it record the
time, pid, uid, euid, gid, or egid. It only has a message.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
\&\f(CW\*(C`Exception::Class::Base\*(C'\fR objects are overloaded so that
stringification produces a normal error message.  This just calls the
\&\f(CW\*(C`$exception\->as_string()\*(C'\fR method described above.  This means
that you can just \f(CW\*(C`print $@\*(C'\fR after an \f(CW\*(C`eval\*(C'\fR and not worry about
whether or not its an actual object.  It also means an application or
module could do this:
.PP
.Vb 1
\& $SIG{_\|_DIE_\|_} = sub { Exception::Class::Base\->throw( error => join \*(Aq\*(Aq, @_ ); };
.Ve
.PP
and this would probably not break anything (unless someone was
expecting a different type of exception object from \f(CW\*(C`die()\*(C'\fR).
.SH "OVERRIDING THE as_string METHOD"
.IX Header "OVERRIDING THE as_string METHOD"
By default, the \f(CW\*(C`as_string()\*(C'\fR method simply returns the value
\&\f(CW\*(C`message\*(C'\fR or \f(CW\*(C`error\*(C'\fR param plus a stack trace, if the class's
\&\f(CW\*(C`Trace()\*(C'\fR method returns a true value or \f(CW\*(C`show_trace\*(C'\fR was set when
creating the exception.
.PP
However, once you add new fields to a subclass, you may want to
include those fields in the stringified error.
.PP
Inside the \f(CW\*(C`as_string()\*(C'\fR method, the message (non-stack trace)
portion of the error is generated by calling the \f(CW\*(C`full_message()\*(C'\fR
method.  This can be easily overridden.  For example:
.PP
.Vb 2
\&  sub full_message {
\&      my $self = shift;
\&
\&      my $msg = $self\->message;
\&
\&      $msg .= " and foo was " . $self\->foo;
\&
\&      return $msg;
\&  }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Dave Rolsky.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.