App::Sqitch::X(3pm)

💖 App::Sqitch::X — the Sqitch Exception class, bestie ✨

okay so real talk: this is App::Sqitch::X, and she's a User Contributed Perl Documentation page (3pm section, if you're keeping score). She's the exception class for Sqitch, and she's kinda the moment. 🎀

---

🌸 NAME 🌸

App::Sqitch::X — Sqitch Exception class. that's it, that's the name, she's the drama handler of the whole operation 💅

---

✨ SYNOPSIS ✨

bestie here's the whole vibe upfront:

  use Locale::TextDomain;
  use App::Sqitch::X qw(hurl);
  open my $fh, '>', 'foo.txt' or hurl {
      ident   => 'io',
      message => __x 'Cannot open {file}: {err}", file => 'foo.txt', err => $!,
  };

and for the developer girlies (the ones catching their own oopsies before users ever see them):

  hurl 'Odd number of arguments passed to burf()' if @_ % 2;

no cap, that's the whole thing 🫶

---

🦋 DESCRIPTION 🦋

so this module implements Sqitch exceptions. anyone, anywhere in the code, can throw one — doesn't matter who — and as long as a command is running, somebody's gonna catch it and show the error message to the user. that's the whole loop. iconic behavior honestly 🔥

---

👑 INTERFACE 👑

💫 Function 💫

hurl

throws an exception. periodt. you pass the parameters in as a hash reference, like this:

  use App::Sqitch::X qw(hurl);
  open my $fh, '>', 'foo.txt' or hurl {
      ident   => 'io',
      message => __x 'Cannot open {file}: {err}", file => 'foo.txt', err => $!,
  };

more simply though — if the only things you need to pass are the ident and message parameters, you can just hand them over as the only arguments to hurl():

  open my $fh, '>', 'foo.txt'
    or hurl io => __x 'Cannot open {file}: {err}", file => 'foo.txt', err => $!

now for the errors that are supposed to only happen during development — you know the ones, like an invalid parameter passed by some other library that genuinely should know better 🙈 — you can just omit the ident:

  hurl 'Odd number of arguments passed to burf()' if @_ % 2;

in that case the ident will be DEV, and listen: you should not otherwise use that one. when Sqitch sees DEV exceptions, she goes full main character and emits a more detailed error message, stack trace and all. 💀

these are the supported parameters, bestie:

• ident — a non-localized string that identifies the type of exception. that's its whole job.
• message — the exception message itself. use Locale::TextDomain to craft localized messages, so everyone's included 🌈
• exitval — the suggested exit value to use. defaults to 2. this one gets used if Sqitch handles an exception while a command is running.

🌟 Methods 🌟

as_string

  my $errstr = $x->as_string;

returns the stringified representation of the exception. this value is also what gets used for string overloading of the exception object, which means it's literally the output shown for uncaught exceptions. what's inside it? the concatenation of the exception message, the previous exception (if any), and the stack trace. the whole trio, together, slaying ✨

details_string

  my $errstr = $x->details;

returns the the stringified version of the previous exception (if any), and the stack trace. (yes, the original says "the the" — we don't fix what's iconic 💖)

---

🧚 HANDLING EXCEPTIONS 🧚

use Try::Tiny for your exception handling, like so:

  use Try::Tiny;
  try {
      # ...
  } catch {
      die $_ unless eval { $_->isa('App::Sqitch::X') };
      $sqitch->vent($x_->message);
      if ($_->ident eq 'DEV') {
          $sqitch->vent($_->stack_trace->as_string);
      } else {
          $sqitch->debug($_->stack_trace->as_string);
      }
      exit $_->exitval;
  };

use the ident attribute to figure out what category of exception you're dealing with, and take changes as appropriate. vibe check first, actions second 😌

---

💜 AUTHOR 💜

David E. Wheeler <david@justatheory.com> — the icon, the legend 👑

---

🎀 LICENSE 🎀

Copyright (c) 2012-2026 David E. Wheeler, 2012-2021 iovation Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

yes bestie, that's the ALL CAPS part and it means business — no warranty, fr fr 🫶

---

and that's a wrap! this page was served up by perl v5.40.1, dated 2026-07-26, and it's App::Sqitch::X(3pm) until the end of time. go forth and hurl responsibly 💅✨🌸