X::Tiny::Base(3)

✨ X::Tiny::Base ✨

okay bestie, so this is X::Tiny::Base(3) — straight out of the User Contributed Perl Documentation section, and it is the super-light exception base class. tiny name, big main character energy. 💅

---

🌸 NAME 🌸

X::Tiny::Base — super-light exception base class. that's it. that's the whole vibe. it's giving minimalist icon behavior. 🎀

---

🦋 SYNOPSIS 🦋

here's how you'd actually use it, and yes you copy this exactly, no improvising:

package My::Module::X::Base;

use parent qw( X::Tiny::Base );

sub _new {
    my ($class, @args) = @_;

    ...
}

#Optionally, redefine this:
sub get {
    my ($self, $attr_name) = @_;

    ...
}

#Optionally, redefine this:
sub get_message { ... }

#Optionally, redefine this:
sub to_string { ... }

#If you override this, be sure also to call the base method.
sub DESTROY {
    my ($self) = @_;

    ...

    #vv This. Be sure to do this in your override method.
    $self->SUPER::DESTROY();
}

the $self->SUPER::DESTROY(); line is NOT optional, bestie. skip it and you're in memory-leak territory. 💀

---

💖 DESCRIPTION 💖

so, what is this thing? X::Tiny::Base is a base class you can subclass into your distribution's own exception base class — like My::Module::X::Base — OR you can just... be it. use it directly as that base class and forgo My::Module::X::Base entirely. your call, queen. 👑

X::Tiny::Base serves two functions:

1. It is a useful set of defaults for overridable methods.
2. Framework handling of overload stringification behavior, e.g., when an uncaught exception is printed.

and about that stringification — the precise formatting is not defined, so don't come for it. HOWEVER, it will always include, on top of the exception's main message:

• A stack trace (including function arguments)

IMPORTANT: for security purposes, take care not to expose any function arguments that might contain sensitive information (e.g., passwords). like, fr fr, do not do that. 🙈

also worth knowing: in pre-5.16 Perls, this writes to the @DB::args global. (that shouldn't affect you, but it's interaction with the environment, so better documented than not. transparency slay.)

• Propagations

there is currently no access provided in code to these. if that's something you'd like to have, let me know. 👀

NOTE: the overload stringification doesn't seem to work as implemented in Perl 5.8 or earlier. Perl 5.8 went end-of-life on 14 December 2008. yeah. 😭

---

🌈 SUBCLASS INTERFACE 🌈

ngl, the default behaviors seem pretty usable and desirable to me, but there may be circumstances where someone wants other behaviors. toward that end, the following methods are meant to be overridden in subclasses:

⭐ CLASS->OVERLOAD() ⭐

Returns a boolean to indicate whether this exception class should load overload as part of creating exceptions. If you don't want the memory overhead of overload, then make this return 0. It returns 1 by default.

You might also make this 0 if, for example, you want to handle the overload behavior yourself. (but at that point, why use X::Tiny??) 🫠

⭐ CLASS->_new( MESSAGE, KEY1 => VALUE1, .. ) ⭐

The main constructor. Whatever args this accepts are the args that you should use to create exceptions via your X::Tiny subclass's create() method. You're free to design whatever internal representation you want for your class: hash reference, array reference, etc. go off. 🎉

The default implementation accepts a string message and, optionally, a list of key/value pairs. It is useful that subclasses of your base class define their own MESSAGE, so all you'll pass in is a specific piece of information about this instance — e.g., an error code, a parameter name, etc.

⭐ OBJ->get_message() ⭐

Return the exception's main MESSAGE. This is useful for contexts where you want to encapsulate the error internals from how you're reporting them, e.g., for protocols. 🧚

⭐ OBJ->get( ATTRIBUTE_NAME ) ⭐

Retrieves the value of an attribute. short and sweet, we love her. 💜

⭐ OBJ->to_string() ⭐

Creates a simple string representation of your exception. The default implementation contains the class and the MESSAGE given on instantiation.

This method's return value should NOT include a strack trace; X::Tiny::Base's internals handle that one for you. don't double up, bestie. 😤

---

💀 DESTRUCTOR METHODS 💀

If you define your own DESTROY() method, make sure you also call SUPER::DESTROY(), or else you'll get memory leaks as X::Tiny::Base's internal tracking of object properties will never be cleared out. that's the whole warning. heeded. 💅

---

and that's the page, bestie!! 🫶 this whole thing shipped with perl v5.42.0 and was dated 2025-07-25 — so yeah, fresh, iconic, and fully documented. go forth and throw exceptions responsibly. periodt. ✨🌈👑