ExtUti...ception(3pm)

✨ ExtUti...ception(3pm) — aka ExtUtils::XSpp::Exception ✨

okay bestie, welcome to the ExtUtils::XSpp::Exception page from the User Contributed Perl Documentation corner of the universe 💖 this is where C++ exceptions get a glow-up into Perl exceptions. buckle up, we're going on a vibe check through every single flag and method, no cap 🦋

---

🎀 NAME 🎀

ExtUtils::XSpp::Exception — it maps C++ exceptions to Perl exceptions, and it does it iconically 💅

---

🌸 DESCRIPTION 🌸

so this class is doing double duty, main character energy fr fr 👑

• it's the base class for all the different exception-handling mechanisms
• it's also the container for the global set of exception mappings — mapping from C++ exceptions (denoted by a C++ data type to catch) over to Perl exceptions

and the Perl exceptions? they're implemented via croak(). yes bestie, croak(). slay. 🐸

The whole ~concept~ is that you declare which C++ exception types you wanna handle, and how you wanna handle them, using the %exception directive — either 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};

now say you know a function or method might throw MyOutOfBoundsExceptions 😭 you can annotate the declaration in your XS++ like this:

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

and when get_from_array throws an OutOfBoundsException, the user gets a Perl croak with the message:

Caught exception of type 'OutOfBoundsException': You accessed me out of bounds, fool!

periodt 💀 and you can have any number of %catch directives per method, go off.

Note: why are we out here assigning another name (outOfBounds) to the existing OutOfBoundsException?? because babes, 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 might be confusing to posterity. (posterity said "please don't" 🙈)

instead of adding %catch to methods one by one, you can also specify exceptions you wish to handle for all methods of a class:

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

the %catch{Foo,Bar,...} syntax is just shorthand for %catch{Foo} %catch{Bar} ... — it's giving efficiency ✨

and here's the tea on precedence, bestie: if there are exceptions to be caught both from the class and attached to a method directly, the ones attached to the method only get handled first. No single type of exceptions will be handled more than once, so it is safe to use this precedence to re-order the class-global exception handling for a single method. iconic behavior honestly 👑

if there are no %catch decorators on a method, exceptions derived from std::exception will be caught with a generic stdmessage handler, like the one above. and 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 🦋

so there are several different cases of Perl exceptions, and they're all implemented as sub-classes of ExtUtils::XSpp::Exception 💜

• ExtUtils::XSpp::Exception::simple — implements the most general case: just throwing a generic error message that includes the name of the C++ exception type. simple. classic. no notes.
• ExtUtils::XSpp::Exception::stdmessage — handles C++ exceptions derived from std::exception that provide a char* what() method which 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 — lets you supply custom C/C++/XS code that gets 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(). you're the author now 🫶
• 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. (it's giving "under construction" 🚧😭)

• ExtUtils::XSpp::Exception::unknown — the default exception handler that gets added to the list of handlers automatically during code generation. It simply throws an entirely unspecific error and catches the type ... (meaning anything) 💀

and then!! there's a special exception handler, nothing, which is always available:

int foo() %catch{nothing};

it says 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. squished. gone. bye 👋✨

---

💅 METHODS 💅

🌈 new

Creates a new ExtUtils::XSpp::Exception 💖

Calls the $self->init(@_) method after construction. init() must be overridden in subclasses — no skipping, bestie 📝

🌈 handler_code

Unimplemented in this base class, but it must be implemented in all actual exception classes 👀

Generates the catch(){} block of code for inclusion in the XS output. The 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, it indents the code and returns it. tidy 🧹💖

🌈 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. yikes, but make it fashion 💅

🧚 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 🐸💀

---

and that's the whole page, bestie, you ate it up 🫶✨ this was perl v5.40.1, dated 2026-07-03, straight from the User Contributed Perl Documentation crew. go forth and catch those exceptions, no cap 💖🎀🦋