oracular (3) ExtUtils::XSpp::Exception.3pm.gz

NAME

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

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 "croak()".

       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 %exception directive in your XS++ (or better yet, in the XS++ typemap):

         // 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};

       If you know a function or method may throw "MyOutOfBoundsException"s, you can annotate the declaration in
       your XS++ as follows:

         double get_from_array(unsigned int index)
           %catch{outOfBounds};

       When "get_from_array" now throws an "OutOfBoundsException", the user gets a Perl croak with the message
       "Caught exception of type 'OutOfBoundsException': You accessed me out of bounds, fool!".  There may be
       any number of %catch directives per method.

       Note: Why do we assign another name ("outOfBounds") to the existing "OutOfBoundsException"?  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 map name, but that may be confusing
       to posterity.

       Instead of adding %catch to methods, you may also specify exceptions that you wish to handle for all
       methods of a class:

         class Foo %catch{SomeException,AnotherException} {
           ...
         };

       The %catch{Foo,Bar,...} syntax is shorthand for "%catch{Foo} %catch{Bar} ...".  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.

       If there are no %catch decorators on a method, exceptions derived from "std::exception" will be caught
       with a generic "stdmessage" handler such as above. Even if there are %catch clauses for the given method,
       all otherwise uncaught exceptions will be caught with a generic error message for safety.

Exception handlers

       There are different cases of Perl exceptions that are implemented as sub-classes of
       "ExtUtils::XSpp::Exception":

       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.

       ExtUtils::XSpp::Exception::stdmessage
         handles C++ exceptions that are derived from "std::exception" and which provide a "char* what()" method
         that will provide an error message.  The Perl-level error message will include the C++ exception type
         name and the exception's "what()" message.

       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 "e". Your user supplied code is expected to
         propagate the exception to Perl by calling croak().

       ExtUtils::XSpp::Exception::object
         maps C++ exceptions to throwing an instance of some Perl exception class.

         Syntax:

           %exception{myClassyException}{CppException}{object}{PerlClass};

         Currently, this means just calling "PerlClass->new()" and then die()ing with that object in $@. There
         is no good way to pass information from the C++ exception object to the Perl object.  Will change in
         future.

       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 "..." (meaning
         anything).

       There is a special exception handler "nothing" which is always available:

         int foo() %catch{nothing};

       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.

METHODS

   new
       Creates a new "ExtUtils::XSpp::Exception".

       Calls the "$self->init(@_)" method after construction.  "init()" must be overridden in subclasses.

   handler_code
       Unimplemented in this base class, but must be implemented in all actual exception classes.

       Generates the "catch(){}" block of code for inclusion in the XS output. First (optional) argument is an
       integer indicating the number of spaces to use for the first indentation level.

   indent_code
       Given a piece of code and a number of spaces to use for global indentation, indents the code and returns
       it.

   cpp_type
       Fetches the C++ type of the exception from the "type" attribute and returns it.

ACCESSORS

   name
       Returns the name of the exception.  This is the "myException" in %exception{myException}{char*}{handler}.

   type
       Returns the ExtUtils::XSpp::Node::Type C++ type that is used for this exception.  This is the "char*" in
       %exception{myException}{char*}{handler}.

CLASS METHODS

   add_exception
       Given an "ExtUtils::XSpp::Exception" object, adds this object to the global registry, potentially
       overwriting an exception map of the same name that was in effect before.

   get_exception_for_name
       Given the XS++ name of the exception map, fetches the corresponding "ExtUtils::XSpp::Exception" object
       from the global registry and returns it. Croaks on error.