TITLE

DRAFT: Synopsis 32: Setting Library - Exception

AUTHORS

    Moritz Lenz <moritz@faui2k.org>

Authors of previous versions of this document:

    Tim Nelson <wayland@wayland.id.au>
    Larry Wall <larry@wall.org>

VERSION

    Created: 26 Feb 2009

    Last Modified: 19 December 2011
    Version: 5

The document is a draft.

If you read the HTML version, it is generated from the Pod in the specs repository under https://github.com/perl6/specs/blob/master/S32-setting-library/Exception.pod so edit it there in the git repository if you would like to make changes.

Roles and Classes

All built-in exceptions live in the X:: namespace.

X::Base

All built-in exceptions inherit from X::Base, which provides some basic behavior: storing a backtrace and providing stringification.

    class X::Base {
        has $.backtrace;
        has $.message;
        method Str {
            # munge $.message
        }
        method ID { ... } # an actual stub that should be
                          # supplied by derived classes or
                          # mixed-in roles
    }

If $.message contains substrings of the form $<attrib>, the Str method of the error message looks those attributes up in self and interpolates them.

X::OS

    role X::OS { has $.os-error }

for all errors that are triggered by some error reported by the operating system (failed IO, system calls, fork, memory allocation).

X::IO

    role X::IO { }

For IO related errors

X::NYI

    role X::NYI {
        has $.feature;
    }

For errors that stem from incomplete implementations of the Perl 6 language. A full Perl 6.0 implementation should not throw such errors.

X::Comp

    role X::Comp {
        has $.filename;
        has $.line;
        has $.column;
    }

For errors that arise from compiling code. Note that in this case the backtrace shows how the compilation was triggered (through use SomeModule;, evals etc.). The actual location of the error does not appear in the backtrace, but rather in the attributes defined in this role.

X::Syntax

    role X::Syntax does X::Comp { }

Common role for all syntax errors.

X::Syntax::Obsolete

    role X::Syntax::Obsolete does X::Syntax {
        has $.ID;
        has $.old;
        has $.new;
        has $.when = 'in Perl 6'
    }

Message defaults to Unsupported use of $<old>;$<when> please use $<new>.

X::Syntax::BadInfix

    role X::Syntax::BadInfx does X::Syntax {
        has $.bad;
    }

Message defaults to Preceding context expects a term, but found infix $<bad> instead.

X::AdHoc

    class X::AdHoc is X::Base {
        has %.payload;
        method ID() { %.payload<ID> }
    }

X::AdHoc is meant for those too lazy to write their own exception classes, but who still want to benefit from structured exceptions.

The Str method in X::AdHoc lets attribute lookup fall back to items in %.payload, ie if there's no $.foo accessor for a name $<foo>, %.payload<foo> is used instead.

Related types

Failure

    class Failure is Mu {
        has Bool $.handled is rw;
        has $.X;            # the actual exception object
    }

An unthrown exception, usually produce by fail().

(Conjecture: S04 implies that all exceptions have a $.handled attribute. Do we actually need that?)

Backtrace

    class Backtrace does Positional[Backtrace::Frame] {
        method Stringy() { ... }
        method full() { ... }
    }
    class Backtrace::Frame {
        has $.file;
        has $.line;
        has $.code;
        has $.subname;

        method is-hidden () { ... }
        method is-routine() { ... }
        method is-setting() { ... }
    }

Backtrace information, typically used (but not limited to) in exceptions. Stringifies to

    in '$<routine>' at line $<line>:$<filename>
    in '$<routine>' at line $<line>:$<filename>
    ...

with two leading spaces on each line.

The default stringification includes blocks and routines from user-space code, but from the setting only routines are shown [conjectural]. Routines can be hidden from the default backtrace stringification by apply the hidden_from_backtrace trait:

    sub my-die(*@msg) is hidden_from_backtrace { }

the is-hidden method in Backtrace::Frame returns Bool::True for routines with that trait.

The full method in Backtrace provides a string representation of the backtrace that includes all available code objects, including hidden ones.

If a code object does not have a name, <anon> is used instead of the routine name.

The Default Exception Printer

In case an exception does not get caught by any CATCH or CONTROL block, it is caught by a default handler in the setting.

This handler calls the .gist method on the exception, prints the result, and termintates the program. The exit code is determined as $exception.?exit-code // 1.