HTML::...eptions(3pm)

💖 NAME 💖

HTML::Mason::Exceptions — the exception objects that Mason throws, bestie. Like, when stuff goes wrong, this is the drama it throws at you. 🎀

---

✨ SYNOPSIS ✨

  use HTML::Mason::Exceptions ( abbr => [ qw(system_error) ] );

  open FH, 'foo' or system_error "cannot open foo: $!";

look at that tiny little import list, it's giving minimal effort, we love that for you 💅

---

🌸 DESCRIPTION 🌸

Okay so this module is the one that builds the whole hierarchy of exception objects Mason uses, no cap. And it also hands them some extra methods on top of whatever Exception::Class already gives them — so it's Exception::Class plus a little extra sprinkle. 🦋

---

🎀 IMPORT 🎀

When you import this module, you can pass a list of abbreviated function names — these are the lil shortcuts you wanna use to throw exceptions. In the SYNOPSIS up there, we're using the system_error function to throw a HTML::Mason::Exception::System exception. ✨

heads up tho: these abbreviated functions are strictly for the message. You cannot set additional fields on the exception through them. Message only. That's it. Periodt. 💀

---

👑 EXCEPTIONS 👑

HTML::Mason::Exception

This is the parent class — the mother of all Mason exceptions, literally. Mason sometimes throws exceptions in this class when it couldn't find a better category for the message, i.e. the "we didn't know where else to put you" pile. 🙈

Abbreviated as error.

HTML::Mason::Exception::Abort

The $m->abort method got called. That's the whole story.

Exceptions in this class contain the field aborted_value.

HTML::Mason::Exception::Decline

The $m->decline method got called. Same energy, different verb.

Exceptions in this class contain the field declined_value.

HTML::Mason::Exception::Compilation

An exception happened while trying to eval an existing object file. Ruh roh. 😭

Exceptions in this class have the field filename, which tells you which file contained the code that caused the error. Very demure, very helpful.

Abbreviated as compilation_error.

HTML::Mason::Exception::Compiler

The compiler threw an exception because it got incorrect input. For example — and this is the example, fr fr — it'd be thrown if the lexer told the compiler to initialize compilation while it was in the middle of compiling another component. Messy. Chaos. Love that for us. 💀

Abbreviated as compiler_error.

HTML::Mason::Exception::Compilation::IncompatibleCompiler

A component was compiled by a compiler or lexer with incompatible options. This one exists to tell Mason "hey bestie, recompile this component". 🔁

Abbreviated as wrong_compiler_error.

HTML::Mason::Exception::Params

Invalid parameters got passed to a method or function. Wrong vibes, wrong args. 🚫

Abbreviated as param_error.

HTML::Mason::Exception::Syntax

This exception means a component contained invalid syntax.

Exceptions in this class have the fields source_line — which is the actual source where the error was found — plus comp_name, and line_number.

Abbreviated as syntax_error.

HTML::Mason::Exception::System

A system call of some sort failed. Like a file open. The classic. 🫠

Abbreviated as system_error.

HTML::Mason::Exception::TopLevelNotFound

The requested top level component could not be found. It's not here, bestie, it never was. 💔

Abbreviated as top_level_not_found_error.

HTML::Mason::VirtualMethod

Some piece of code tried to call a virtual method that was not overridden. Bold of it. 😤

Abbreviated as virtual_error

---

🌈 FIELDS 🌈

Some of the exceptions above have extra fields, and you get to them via accessors. For example, to grab the line number of an HTML::Mason::Exception::Syntax exception, you call the line_number method on the exception object. Easy. Slay. ✨

---

💜 EXCEPTION METHODS 💜

All the Mason exceptions implement these methods, every single one:

• as_brief — just returns the exception message. No trace info, no extras, clean and simple. 🤍
• as_line — returns the exception message plus its trace information, all on a single line, with tabs between the message and each frame of the stack trace.
• as_text — returns the exception message and stack information, with each frame on its own separate line.
• as_html — returns the exception message and stack as a whole HTML page. 🖥️

Each of these methods corresponds to a valid error_format parameter for the Request object, like text or html. iykyk.

And here's the fun part: you can create your own method in the HTML::Mason::Exception namespace — say, as_you_wish — and then you could set this parameter to you_wish. Main character energy. 👑

That method will receive a single argument, the exception object, and it's expected to return some sort of string containing the formatted error message.

---

🧚 EXCEPTION CLASS CHECKING 🧚

This module also exports the isa_mason_exception function. It takes the exception object, plus an optional string parameter saying which subclass to check for. 🕵️

So you can call it either like:

  if ( isa_mason_exception($@) ) { ... }

or like:

  if ( isa_mason_exception($@, 'Syntax') ) { ... }

important: when you're specifying a subclass, do NOT include the leading HTML::Mason::Exception:: part of the class name. Just the lil tail end. Don't do the extra, bestie. 🙅♀️

---

and that's the whole page, you're officially a Mason exceptions expert now 🫶 this was perl v5.38.2, dated 2024-03-05, and it lives in the User Contributed Perl Documentation — mwah, go forth and catch your exceptions 💖✨