SVN::Web::X(3pm)

✨ SVN::Web::X ✨ — exceptions for SVN::Web 💖

okay bestie, welcome to the SVN::Web::X page (that's section 3pm of the perl manual, iykyk) 🫶 this is the part where SVN::Web gets to feel its feelings and throw an exception about it.

---

🌸 SYNOPSIS 🌸

use SVN::Web::X;

...

SVN::Web::X->throw(error => '(error message %1)',
                   vars => [$var_to_interpolate]);

---

🦋 DESCRIPTION 🦋

So SVN::Web::X implements exceptions for SVN::Web, periodt. It's derived from Exception::Class, and what it gives you is a whole little mechanism: throw exceptions, catch them, and then make sure a friendly, localised error message gets generated and shipped straight to the user's browser. It's giving customer service, honestly 💅

---

🎀 USAGE IN SVN::Web ACTIONS 🎀

If an SVN::Web action that you're writing needs to stop processing and raise an error — like, the whole thing needs to halt, no cap — you throw an SVN::Web::X exception.

throw() takes a hash with two mandatory keys.

• error — a string describing the error. This string should be short, and it's the key to a longer internationalised message.

This string may contain placeholders: %1, %2, %3, and so on. Those get replaced by the values of the variables you pass in the vars key.

By convention this string should be enclosed in parentheses, ( and ). Why? Because it helps them stand out in the interface, in case some of the localised versions of the error message haven't been written yet. Iconic little visual cue honestly.

• vars — an array reference. The first entry in the array replaces the %1 placeholder in error, the second entry replaces the %2 placeholder, and so on.

If there are no placeholders, then pass a reference to an empty array. Yes, an empty array. It's fine. It's required. Don't skip it 🙈

---

🔥 EXAMPLES 🔥

🍓 A simple exception, with no placeholders.

In the action:

sub run {
    ...
    if(! frob_repo()) {
        SVN::Web::X->throw(error => '(frob failed)',
                           vars  => []);
    }
    ...
}

In the en.po file for the localised text:

msgid "(frob failed)"
msgstr "There was a problem trying to frob the repository.  This "
"probably indicates a permissions problem."

🧚 An exception with placeholders

In the action:

sub run {
    ...
    # $path is a repo path, $rev is a repo revision
    my $root = $fs->revision_root($rev);
    my $kind = $root->check_path($path);

    if($kind == $SVN::Node::none) {
        SVN::Web::X->throw(error => '(path %1 does not exist in rev %2)',
                           vars  => [$path, $rev]);
    }
}

In the en.po file for the localised text:

msgid "(path %1 does not exist in rev %2)"
msgstr "The path <tt>%1</tt> could not be found in the repository "
"at revision %2.  This may be a typo in the path or the revision "
"number.  SVN::Web should never normally generate a link like this. "
"If you followed a link from SVN::Web (rather than from an e-mail, "
"or similar) please report this as a bug."

As you can see, the localised text can be much friendlier and more informative to the user than the error message. It's literally the glow-up of error messages 🌈

---

👑 COPYRIGHT 👑

Copyright 2003-2004 by Chia-liang Kao "<clkao@clkao.org>".

Copyright 2005-2007 by Nik Clayton "<nik@FreeBSD.org>".

Copyright 2012 by Dean Hamstead "<dean@fragfest.com.au>".

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>

---

and that's the whole thing bestie, you ate 💅 made with perl v5.40.1, dated 2025-04-09, and stamped SVN::Web::X(3pm) on the way out 🫶✨