1ExtUtils::XSpp::ExceptiUosne(r3)Contributed Perl DocumenEtxattUitoinls::XSpp::Exception(3)
2
3
4

NAME

6       ExtUtils::XSpp::Exception - Map C++ exceptions to Perl exceptions
7

DESCRIPTION

9       This class is both the base class for the different exception handling
10       mechanisms and the container for the global set of exception mappings
11       from C++ exceptions (indicated by a C++ data type to catch) to Perl
12       exceptions. The Perl exceptions are implemented via "croak()".
13
14       The basic idea is that you can declare the C++ exception types that you
15       want to handle and how you plan to do so by using the %exception
16       directive in your XS++ (or better yet, in the XS++ typemap):
17
18         // OutOfBoundsException would have been declared
19         // elsewhere as:
20         //
21         // class OutOfBoundsException : public std::exception {
22         // public:
23         //   OutOfBoundsException() {}
24         //   virtual const char* what() const throw() {
25         //     return "You accessed me out of bounds, fool!";
26         //   }
27         // }
28
29         %exception{outOfBounds}{OutOfBoundsException}{stdmessage};
30
31       If you know a function or method may throw "MyOutOfBoundsException"s,
32       you can annotate the declaration in your XS++ as follows:
33
34         double get_from_array(unsigned int index)
35           %catch{outOfBounds};
36
37       When "get_from_array" now throws an "OutOfBoundsException", the user
38       gets a Perl croak with the message "Caught exception of type
39       'OutOfBoundsException': You accessed me out of bounds, fool!".  There
40       may be any number of %catch directives per method.
41
42       Note: Why do we assign another name ("outOfBounds") to the existing
43       "OutOfBoundsException"?  Because you may need to catch exceptions of
44       the same C++ type with different handlers for different methods. You
45       can, in principle, re-use the C++ exception class name for the
46       exception map name, but that may be confusing to posterity.
47
48       Instead of adding %catch to methods, you may also specify exceptions
49       that you wish to handle for all methods of a class:
50
51         class Foo %catch{SomeException,AnotherException} {
52           ...
53         };
54
55       The %catch{Foo,Bar,...} syntax is shorthand for "%catch{Foo}
56       %catch{Bar} ...".  If there are exceptions to be caught both from the
57       class and attached to a method directly, the exceptions that are
58       attached to the method only will be handled first. No single type of
59       exceptions will be handled more than once, therefore it is safe to use
60       this precedence to re-order the class-global exception handling for a
61       single method.
62
63       If there are no %catch decorators on a method, exceptions derived from
64       "std::exception" will be caught with a generic "stdmessage" handler
65       such as above. Even if there are %catch clauses for the given method,
66       all otherwise uncaught exceptions will be caught with a generic error
67       message for safety.
68

Exception handlers

70       There are different cases of Perl exceptions that are implemented as
71       sub-classes of "ExtUtils::XSpp::Exception":
72
73       ExtUtils::XSpp::Exception::simple
74         implements the most general case of simply throwing a generic error
75         message that includes the name of the C++ exception type.
76
77       ExtUtils::XSpp::Exception::stdmessage
78         handles C++ exceptions that are derived from "std::exception" and
79         which provide a "char* what()" method that will provide an error
80         message.  The Perl-level error message will include the C++ exception
81         type name and the exception's "what()" message.
82
83       ExtUtils::XSpp::Exception::code
84         allows the user to supply custom C/C++/XS code that will be included
85         in the exception handler verbatim. The code has access to the
86         exception object as the variable "e". Your user supplied code is
87         expected to propagate the exception to Perl by calling croak().
88
89       ExtUtils::XSpp::Exception::object
90         maps C++ exceptions to throwing an instance of some Perl exception
91         class.
92
93         Syntax:
94
95           %exception{myClassyException}{CppException}{object}{PerlClass};
96
97         Currently, this means just calling "PerlClass->new()" and then
98         die()ing with that object in $@. There is no good way to pass
99         information from the C++ exception object to the Perl object.  Will
100         change in future.
101
102       ExtUtils::XSpp::Exception::unknown
103         is the default exception handler that is added to the list of
104         handlers automatically during code generation. It simply throws an
105         entirely unspecific error and catches the type "..." (meaning
106         anything).
107
108       There is a special exception handler "nothing" which is always
109       available:
110
111         int foo() %catch{nothing};
112
113       It indicates that the given method (or function) is to handle no
114       exceptions. It squishes any exception handlers that might otherwise be
115       inherited from the method's class.
116

METHODS

118   new
119       Creates a new "ExtUtils::XSpp::Exception".
120
121       Calls the "$self->init(@_)" method after construction.  "init()" must
122       be overridden in subclasses.
123
124   handler_code
125       Unimplemented in this base class, but must be implemented in all actual
126       exception classes.
127
128       Generates the "catch(){}" block of code for inclusion in the XS output.
129       First (optional) argument is an integer indicating the number of spaces
130       to use for the first indentation level.
131
132   indent_code
133       Given a piece of code and a number of spaces to use for global
134       indentation, indents the code and returns it.
135
136   cpp_type
137       Fetches the C++ type of the exception from the "type" attribute and
138       returns it.
139

ACCESSORS

141   name
142       Returns the name of the exception.  This is the "myException" in
143       %exception{myException}{char*}{handler}.
144
145   type
146       Returns the ExtUtils::XSpp::Node::Type C++ type that is used for this
147       exception.  This is the "char*" in
148       %exception{myException}{char*}{handler}.
149

CLASS METHODS

151   add_exception
152       Given an "ExtUtils::XSpp::Exception" object, adds this object to the
153       global registry, potentially overwriting an exception map of the same
154       name that was in effect before.
155
156   get_exception_for_name
157       Given the XS++ name of the exception map, fetches the corresponding
158       "ExtUtils::XSpp::Exception" object from the global registry and returns
159       it. Croaks on error.
160
161
162
163perl v5.36.0                      2022-07-22      ExtUtils::XSpp::Exception(3)
Impressum