.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "ExtUtils::XSpp::Exception 3pm"
.TH ExtUtils::XSpp::Exception 3pm "2020-12-29" "perl v5.32.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"
ExtUtils::XSpp::Exception \- Map C++ exceptions to Perl exceptions
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is both the base class for the different exception handling
mechanisms and the container for the global set of exception
mappings from \*(C+ exceptions (indicated by a \*(C+ data type to catch)
to Perl exceptions. The Perl exceptions are implemented via \f(CW\*(C`croak()\*(C'\fR.
.PP
The basic idea is that you can declare the \*(C+ exception types that
you want to handle and how you plan to do so by using the \f(CW%exception\fR
directive in your \s-1XS++\s0 (or better yet, in the \s-1XS++\s0 typemap):
.PP
.Vb 10
\&  // OutOfBoundsException would have been declared
\&  // elsewhere as:
\&  //
\&  // class OutOfBoundsException : public std::exception {
\&  // public:
\&  //   OutOfBoundsException() {}
\&  //   virtual const char* what() const throw() {
\&  //     return "You accessed me out of bounds, fool!";
\&  //   }
\&  // }
\&  
\&  %exception{outOfBounds}{OutOfBoundsException}{stdmessage};
.Ve
.PP
If you know a function or method may throw \f(CW\*(C`MyOutOfBoundsException\*(C'\fRs, you
can annotate the declaration in your \s-1XS++\s0 as follows:
.PP
.Vb 2
\&  double get_from_array(unsigned int index)
\&    %catch{outOfBounds};
.Ve
.PP
When \f(CW\*(C`get_from_array\*(C'\fR now throws an \f(CW\*(C`OutOfBoundsException\*(C'\fR, the user
gets a Perl croak with the message
\&\f(CW"Caught exception of type \*(AqOutOfBoundsException\*(Aq: You accessed me out of bounds, fool!"\fR.
There may be any number of \f(CW%catch\fR directives per method.
.PP
\&\fINote:\fR Why do we assign another name (\f(CW\*(C`outOfBounds\*(C'\fR) to the
existing \f(CW\*(C`OutOfBoundsException\*(C'\fR?
Because you may need to catch exceptions of the same \*(C+ type with different
handlers for different methods. You can, in principle, re-use the \*(C+ exception
class name for the exception \fImap\fR name, but that may be confusing to posterity.
.PP
Instead of adding \f(CW%catch\fR to methods, you may also specify exceptions that
you wish to handle for all methods of a class:
.PP
.Vb 3
\&  class Foo %catch{SomeException,AnotherException} {
\&    ...
\&  };
.Ve
.PP
The \f(CW%catch{Foo,Bar,...}\fR syntax is shorthand for \f(CW\*(C`%catch{Foo} %catch{Bar} ...\*(C'\fR.
If there are exceptions to be caught both from the class and attached
to a method directly, the exceptions that are attached to the method only will
be handled first. No single type of exceptions will be handled more than once,
therefore it is safe to use this precedence to re-order the class-global
exception handling for a single method.
.PP
If there are no \f(CW%catch\fR decorators on a method, exceptions derived
from \f(CW\*(C`std::exception\*(C'\fR will be caught with a generic \f(CW\*(C`stdmessage\*(C'\fR
handler such as above. Even if there are \f(CW%catch\fR clauses for the given method,
all otherwise uncaught exceptions will be caught with a generic error message
for safety.
.SH "Exception handlers"
.IX Header "Exception handlers"
There are different cases of Perl exceptions that are implemented
as sub-classes of \f(CW\*(C`ExtUtils::XSpp::Exception\*(C'\fR:
.IP "ExtUtils::XSpp::Exception::simple" 2
.IX Item "ExtUtils::XSpp::Exception::simple"
implements the most general case of simply throwing a
generic error message that includes the name of the
\&\*(C+ exception type.
.IP "ExtUtils::XSpp::Exception::stdmessage" 2
.IX Item "ExtUtils::XSpp::Exception::stdmessage"
handles \*(C+ exceptions that are derived from \f(CW\*(C`std::exception\*(C'\fR and
which provide a \f(CW\*(C`char* what()\*(C'\fR method that will provide an error message.
The Perl-level error message will include the \*(C+ exception type name
and the exception's \f(CW\*(C`what()\*(C'\fR message.
.IP "ExtUtils::XSpp::Exception::code" 2
.IX Item "ExtUtils::XSpp::Exception::code"
allows the user to supply custom C/\*(C+/XS code that will be included in
the exception handler verbatim. The code has access to the exception
object as the variable \f(CW\*(C`e\*(C'\fR. Your user supplied code
is expected to propagate the exception to Perl by calling \fBcroak()\fR.
.IP "ExtUtils::XSpp::Exception::object" 2
.IX Item "ExtUtils::XSpp::Exception::object"
maps \*(C+ exceptions to throwing an instance of some Perl exception class.
.Sp
Syntax:
.Sp
.Vb 1
\&  %exception{myClassyException}{CppException}{object}{PerlClass};
.Ve
.Sp
Currently, this means just calling \f(CW\*(C`PerlClass\->new()\*(C'\fR and
then \fBdie()\fRing with that object in \f(CW$@\fR. There is no good way to pass
information from the \*(C+ exception object to the Perl object.
Will change in future.
.IP "ExtUtils::XSpp::Exception::unknown" 2
.IX Item "ExtUtils::XSpp::Exception::unknown"
is the default exception handler that is added to the list of handlers
automatically during code generation. It simply throws an entirely
unspecific error and catches the type \f(CW\*(C`...\*(C'\fR (meaning \fIanything\fR).
.PP
There is a special exception handler \f(CW\*(C`nothing\*(C'\fR which is always
available:
.PP
.Vb 1
\&  int foo() %catch{nothing};
.Ve
.PP
It indicates that the given method (or function) is to handle no
exceptions. It squishes any exception handlers that might otherwise
be inherited from the method's class.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Creates a new \f(CW\*(C`ExtUtils::XSpp::Exception\*(C'\fR.
.PP
Calls the \f(CW\*(C`$self\->init(@_)\*(C'\fR method after construction.
\&\f(CW\*(C`init()\*(C'\fR must be overridden in subclasses.
.SS "handler_code"
.IX Subsection "handler_code"
Unimplemented in this base class, but must be implemented
in all actual exception classes.
.PP
Generates the \f(CW\*(C`catch(){}\*(C'\fR block of code for inclusion
in the \s-1XS\s0 output. First (optional) argument is an integer indicating
the number of spaces to use for the first indentation level.
.SS "indent_code"
.IX Subsection "indent_code"
Given a piece of code and a number of spaces to use for
global indentation, indents the code and returns it.
.SS "cpp_type"
.IX Subsection "cpp_type"
Fetches the \*(C+ type of the exception from the \f(CW\*(C`type\*(C'\fR attribute and returns it.
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.SS "name"
.IX Subsection "name"
Returns the name of the exception.
This is the \f(CW\*(C`myException\*(C'\fR in \f(CW%exception{myException}{char*}{handler}\fR.
.SS "type"
.IX Subsection "type"
Returns the ExtUtils::XSpp::Node::Type \*(C+ type that is used for this exception.
This is the \f(CW\*(C`char*\*(C'\fR in \f(CW%exception{myException}{char*}{handler}\fR.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "add_exception"
.IX Subsection "add_exception"
Given an \f(CW\*(C`ExtUtils::XSpp::Exception\*(C'\fR object,
adds this object to the global registry, potentially
overwriting an exception map of the same name that was
in effect before.
.SS "get_exception_for_name"
.IX Subsection "get_exception_for_name"
Given the \s-1XS++\s0 name of the exception map, fetches
the corresponding \f(CW\*(C`ExtUtils::XSpp::Exception\*(C'\fR object
from the global registry and returns it. Croaks on error.