.\" 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 "Exception::Class 3pm"
.TH Exception::Class 3pm "2014-05-05" "perl v5.18.2" "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 \- A module that allows you to declare real exception classes in Perl
.SH "VERSION"
.IX Header "VERSION"
version 1.38
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Exception::Class (
\&      \*(AqMyException\*(Aq,
\&
\&      \*(AqAnotherException\*(Aq => { isa => \*(AqMyException\*(Aq },
\&
\&      \*(AqYetAnotherException\*(Aq => {
\&          isa         => \*(AqAnotherException\*(Aq,
\&          description => \*(AqThese exceptions are related to IPC\*(Aq
\&      },
\&
\&      \*(AqExceptionWithFields\*(Aq => {
\&          isa    => \*(AqYetAnotherException\*(Aq,
\&          fields => [ \*(Aqgrandiosity\*(Aq, \*(Aqquixotic\*(Aq ],
\&          alias  => \*(Aqthrow_fields\*(Aq,
\&      },
\&  );
\&  use Scalar::Util qw( blessed );
\&  use Try::Tiny;
\&
\&  try {
\&      MyException\->throw( error => \*(AqI feel funny.\*(Aq );
\&  }
\&  catch {
\&      die $_ unless blessed $_ && $_\->can(\*(Aqrethrow\*(Aq);
\&
\&      if ( $_\->isa(\*(AqException::Class\*(Aq) ) {
\&          warn $_\->error, "\en", $_\->trace\->as_string, "\en";
\&          warn join \*(Aq \*(Aq, $_\->euid, $_\->egid, $_\->uid, $_\->gid, $_\->pid, $_\->time;
\&
\&          exit;
\&      }
\&      elsif ( $_\->isa(\*(AqExceptionWithFields\*(Aq) ) {
\&          if ( $_\->quixotic ) {
\&              handle_quixotic_exception();
\&          }
\&          else {
\&              handle_non_quixotic_exception();
\&          }
\&      }
\&      else {
\&          $_\->rethrow;
\&      }
\&  };
\&
\&  # without Try::Tiny
\&
\&  eval { ... };
\&  if ( my $e = Exception::Class\->caught() ) { ... }
\&
\&  # use an alias \- without parens subroutine name is checked at
\&  # compile time
\&  throw_fields error => "No strawberry", grandiosity => "quite a bit";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1RECOMMENDATION 1\s0\fR: If you are writing modern Perl code with Moose or
Moo I highly recommend using Throwable instead of this module.
.PP
\&\fB\s-1RECOMMENDATION 2\s0\fR: Whether or not you use Throwable, you should use
Try::Tiny.
.PP
Exception::Class allows you to declare exception hierarchies in your
modules in a \*(L"Java-esque\*(R" manner.
.PP
It features a simple interface allowing programmers to 'declare'
exception classes at compile time.  It also has a base exception
class, Exception::Class::Base, that can be easily extended.
.PP
It is designed to make structured exception handling simpler and
better by encouraging people to use hierarchies of exceptions in their
applications, as opposed to a single catch-all exception class.
.PP
This module does not implement any try/catch syntax.  Please see the
\&\*(L"\s-1OTHER EXCEPTION MODULES \s0(try/catch syntax)\*(R" section for more
information on how to get this syntax.
.PP
You will also want to look at the documentation for
Exception::Class::Base, which is the default base class for all
exception objects created by this module.
.SH "DECLARING EXCEPTION CLASSES"
.IX Header "DECLARING EXCEPTION CLASSES"
Importing \f(CW\*(C`Exception::Class\*(C'\fR allows you to automagically create
Exception::Class::Base subclasses.  You can also create subclasses
via the traditional means of defining your own subclass with \f(CW@ISA\fR.
These two methods may be easily combined, so that you could subclass
an exception class defined via the automagic import, if you desired
this.
.PP
The syntax for the magic declarations is as follows:
.PP
\&'\s-1MANDATORY CLASS NAME\s0' => \e%optional_hashref
.PP
The hashref may contain the following options:
.IP "\(bu" 4
isa
.Sp
This is the class's parent class.  If this isn't provided then the
class name in \f(CW$Exception::Class::BASE_EXC_CLASS\fR is assumed to be
the parent (see below).
.Sp
This parameter lets you create arbitrarily deep class hierarchies.
This can be any other Exception::Class::Base subclass in your
declaration \fIor\fR a subclass loaded from a module.
.Sp
To change the default exception class you will need to change the
value of \f(CW$Exception::Class::BASE_EXC_CLASS\fR \fIbefore\fR calling
\&\f(CW\*(C`import()\*(C'\fR.  To do this simply do something like this:
.Sp
.Vb 1
\&  BEGIN { $Exception::Class::BASE_EXC_CLASS = \*(AqSomeExceptionClass\*(Aq; }
.Ve
.Sp
If anyone can come up with a more elegant way to do this please let me
know.
.Sp
\&\s-1CAVEAT:\s0 If you want to automagically subclass an
Exception::Class::Base subclass loaded from a file, then you
\&\fImust\fR compile the class (via use or require or some other magic)
\&\fIbefore\fR you import \f(CW\*(C`Exception::Class\*(C'\fR or you'll get a compile time
error.
.IP "\(bu" 4
fields
.Sp
This allows you to define additional attributes for your exception
class.  Any field you define can be passed to the \f(CW\*(C`throw()\*(C'\fR or
\&\f(CW\*(C`new()\*(C'\fR methods as additional parameters for the constructor.  In
addition, your exception object will have an accessor method for the
fields you define.
.Sp
This parameter can be either a scalar (for a single field) or an array
reference if you need to define multiple fields.
.Sp
Fields will be inherited by subclasses.
.IP "\(bu" 4
alias
.Sp
Specifying an alias causes this class to create a subroutine of the
specified name in the \fIcaller's\fR namespace.  Calling this subroutine
is equivalent to calling \f(CW\*(C`<class>\->throw(@_)\*(C'\fR for the given
exception class.
.Sp
Besides convenience, using aliases also allows for additional compile
time checking.  If the alias is called \fIwithout parentheses\fR, as in
\&\f(CW\*(C`throw_fields "an error occurred"\*(C'\fR, then Perl checks for the
existence of the \f(CW\*(C`throw_fields()\*(C'\fR subroutine at compile time.  If
instead you do \f(CW\*(C`ExceptionWithFields\->throw(...)\*(C'\fR, then Perl
checks the class name at runtime, meaning that typos may sneak
through.
.IP "\(bu" 4
description
.Sp
Each exception class has a description method that returns a fixed
string.  This should describe the exception \fIclass\fR (as opposed to
any particular exception object).  This may be useful for debugging if
you start catching exceptions you weren't expecting (particularly if
someone forgot to document them) and you don't understand the error
messages.
.PP
The \f(CW\*(C`Exception::Class\*(C'\fR magic attempts to detect circular class
hierarchies and will die if it finds one.  It also detects missing
links in a chain, for example if you declare Bar to be a subclass of
Foo and never declare Foo.
.SH "Try::Tiny"
.IX Header "Try::Tiny"
If you are interested in adding try/catch/finally syntactic sugar to your code
then I recommend you check out Try::Tiny. This is a great module that helps
you ignore some of the weirdness with \f(CW\*(C`eval\*(C'\fR and \f(CW$@\fR. Here's an example of
how the two modules work together:
.PP
.Vb 3
\&  use Exception::Class ( \*(AqMy::Exception\*(Aq );
\&  use Scalar::Util qw( blessed );
\&  use Try::Tiny;
\&
\&  try {
\&      might_throw();
\&  }
\&  catch {
\&      if ( blessed $_ && $_\->isa(\*(AqMy::Exception\*(Aq) ) {
\&          handle_it();
\&      }
\&      else {
\&          die $_;
\&      }
\&  };
.Ve
.PP
Note that you \fBcannot\fR use \f(CW\*(C`Exception::Class\->caught()\*(C'\fR with
Try::Tiny.
.SH "Catching Exceptions Without Try::Tiny"
.IX Header "Catching Exceptions Without Try::Tiny"
\&\f(CW\*(C`Exception::Class\*(C'\fR provides some syntactic sugar for catching
exceptions in a safe manner:
.PP
.Vb 1
\&  eval {...};
\&
\&  if ( my $e = Exception::Class\->caught(\*(AqMy::Error\*(Aq) ) {
\&      cleanup();
\&      do_something_with_exception($e);
\&  }
.Ve
.PP
The \f(CW\*(C`caught()\*(C'\fR method takes a class name and returns an exception
object if the last thrown exception is of the given class, or a
subclass of that class.  If it is not given any arguments, it simply
returns \f(CW$@\fR.
.PP
You should \fBalways\fR make a copy of the exception object, rather than
using \f(CW$@\fR directly.  This is necessary because if your \f(CW\*(C`cleanup()\*(C'\fR
function uses \f(CW\*(C`eval\*(C'\fR, or calls something which uses it, then \f(CW$@\fR is
overwritten.  Copying the exception preserves it for the call to
\&\f(CW\*(C`do_something_with_exception()\*(C'\fR.
.PP
Exception objects also provide a caught method so you can write:
.PP
.Vb 4
\&  if ( my $e = My::Error\->caught() ) {
\&      cleanup();
\&      do_something_with_exception($e);
\&  }
.Ve
.SS "Uncatchable Exceptions"
.IX Subsection "Uncatchable Exceptions"
Internally, the \f(CW\*(C`caught()\*(C'\fR method will call \f(CW\*(C`isa()\*(C'\fR on the exception
object.  You could make an exception \*(L"uncatchable\*(R" by overriding
\&\f(CW\*(C`isa()\*(C'\fR in that class like this:
.PP
.Vb 1
\& package Exception::Uncatchable;
\&
\& sub isa { shift\->rethrow }
.Ve
.PP
Of course, this only works if you always call \f(CW\*(C`Exception::Class\->caught()\*(C'\fR after an \f(CW\*(C`eval\*(C'\fR.
.SH "USAGE RECOMMENDATION"
.IX Header "USAGE RECOMMENDATION"
If you're creating a complex system that throws lots of different
types of exceptions, consider putting all the exception declarations
in one place.  For an app called Foo you might make a
\&\f(CW\*(C`Foo::Exceptions\*(C'\fR module and use that in all your code.  This module
could just contain the code to make \f(CW\*(C`Exception::Class\*(C'\fR do its
automagic class creation.  Doing this allows you to more easily see
what exceptions you have, and makes it easier to keep track of them.
.PP
This might look something like this:
.PP
.Vb 1
\&  package Foo::Bar::Exceptions;
\&
\&  use Exception::Class (
\&      Foo::Bar::Exception::Senses =>
\&          { description => \*(Aqsense\-related exception\*(Aq },
\&
\&      Foo::Bar::Exception::Smell => {
\&          isa         => \*(AqFoo::Bar::Exception::Senses\*(Aq,
\&          fields      => \*(Aqodor\*(Aq,
\&          description => \*(Aqstinky!\*(Aq
\&      },
\&
\&      Foo::Bar::Exception::Taste => {
\&          isa         => \*(AqFoo::Bar::Exception::Senses\*(Aq,
\&          fields      => [ \*(Aqtaste\*(Aq, \*(Aqbitterness\*(Aq ],
\&          description => \*(Aqlike, gag me with a spoon!\*(Aq
\&      },
\&
\&      ...
\&  );
.Ve
.PP
You may want to create a real module to subclass
Exception::Class::Base as well, particularly if you want your
exceptions to have more methods.
.SS "Subclassing Exception::Class::Base"
.IX Subsection "Subclassing Exception::Class::Base"
As part of your usage of \f(CW\*(C`Exception::Class\*(C'\fR, you may want to create
your own base exception class which subclasses
Exception::Class::Base.  You should feel free to subclass any of
the methods documented above.  For example, you may want to subclass
\&\f(CW\*(C`new()\*(C'\fR to add additional information to your exception objects.
.SH "Exception::Class FUNCTIONS"
.IX Header "Exception::Class FUNCTIONS"
The \f(CW\*(C`Exception::Class\*(C'\fR method offers one function, \f(CW\*(C`Classes()\*(C'\fR,
which is not exported.  This method returns a list of the classes that
have been created by calling the \f(CW\*(C`Exception::Class\*(C'\fR \fIimport()\fR method.
Note that this is \fIall\fR the subclasses that have been created, so it
may include subclasses created by things like \s-1CPAN\s0 modules, etc.  Also
note that if you simply define a subclass via the normal Perl method
of setting \f(CW@ISA\fR or \f(CW\*(C`use base\*(C'\fR, then your subclass will not be
included.
.SH "SUPPORT"
.IX Header "SUPPORT"
Please submit bugs to the \s-1CPAN RT\s0 system at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Exception%3A%3AClass or
via email at bug\-exception\-class@rt.cpan.org.
.SH "DONATIONS"
.IX Header "DONATIONS"
If you'd like to thank me for the work I've done on this module,
please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of
free time creating free software, and would appreciate any support
you'd care to offer.
.PP
Please note that \fBI am not suggesting that you must do this\fR in order
for me to continue working on this particular software. I will
continue to do so, inasmuch as I have in the past, for as long as it
interests me.
.PP
Similarly, a donation made in this way will probably not make me work
on this software much more, unless I get so many donations that I can
consider working on free software full time, which seems unlikely at
best.
.PP
To donate, log into PayPal and send money to autarch@urth.org or use
the button on this page:
<http://www.urth.org/~autarch/fs\-donation.html>
.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.