Skip to content
This repository
Newer
Older
100644 195 lines (132 sloc) 5.034 kb
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
1
2 =encoding utf8
3
04840a3a »
2009-06-26 [Spec] treat all authors equally
4 =head1 TITLE
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
5
6 DRAFT: Synopsis 32: Setting Library - Exception
7
04840a3a »
2009-06-26 [Spec] treat all authors equally
8 =head1 AUTHORS
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
9
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
10 Moritz Lenz <moritz@faui2k.org>
11
12 Authors of previous versions of this document:
13
04840a3a »
2009-06-26 [Spec] treat all authors equally
14 Tim Nelson <wayland@wayland.id.au>
15 Larry Wall <larry@wall.org>
16
17 =head1 VERSION
18
19 Created: 26 Feb 2009
20
12c8b58f »
2011-12-19 [S32::Exceptions] briefly describe the default exception printer
21 Last Modified: 19 December 2011
22 Version: 5
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
23
24 The document is a draft.
25
cf529a7b »
2010-11-20 Update provenance blurbs to point at GitHub
26 If you read the HTML version, it is generated from the Pod in the specs
27 repository under
28 L<https://github.com/perl6/specs/blob/master/S32-setting-library/Exception.pod>
29 so edit it there in the git repository if you would like to make changes.
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
30
12c8b58f »
2011-12-19 [S32::Exceptions] briefly describe the default exception printer
31 =head1 Roles and Classes
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
32
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
33 All built-in exceptions live in the C<X::> namespace.
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
34
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
35 =head2 X::Base
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
36
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
37 All built-in exceptions inherit from C<X::Base>, which provides some basic
a29e3879 »
2011-05-04 [S32/Exceptions] move %.payload into a separate class, based on feedb…
38 behavior: storing a backtrace and providing stringification.
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
39
40 class X::Base {
41 has $.backtrace;
42 has $.message;
a29e3879 »
2011-05-04 [S32/Exceptions] move %.payload into a separate class, based on feedb…
43 method Str {
44 # munge $.message
45 }
46 method ID { ... } # an actual stub that should be
47 # supplied by derived classes or
48 # mixed-in roles
6e859b2e »
2009-07-05 P6 Synopsis : ws changes - all tabs to spaces
49 }
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
50
a29e3879 »
2011-05-04 [S32/Exceptions] move %.payload into a separate class, based on feedb…
51 If C<$.message> contains substrings of the form C<< $<attrib> >>, the
52 C<Str> method of the error message looks those attributes up in C<self>
53 and interpolates them.
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
54
7c80322d »
2011-04-29 Name exception roles more consistently
55 =head2 X::OS
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
56
7c80322d »
2011-04-29 Name exception roles more consistently
57 role X::OS { has $.os-error }
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
58
59 for all errors that are triggered by some error reported by the operating
60 system (failed IO, system calls, fork, memory allocation).
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
61
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
62 =head2 X::IO
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
63
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
64 role X::IO { }
65
66 For IO related errors
67
68 =head2 X::NYI
69
f82124f6 »
2011-06-09 [Excpeptions] X::NYI stores the NYI feature
70 role X::NYI {
71 has $.feature;
72 }
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
73
74 For errors that stem from incomplete implementations of the Perl 6 language.
75 A full Perl 6.0 implementation should not throw such errors.
76
7c80322d »
2011-04-29 Name exception roles more consistently
77 =head2 X::Comp
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
78
7c80322d »
2011-04-29 Name exception roles more consistently
79 role X::Comp {
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
80 has $.filename;
81 has $.line;
82 has $.column;
83 }
bba26cbd »
2009-02-26 Numeric.pod: Added some notes on what needs to be documented here
84
8f8d30e7 »
2011-04-29 [S32::Exception] start to rewrite the exception spec
85 For errors that arise from compiling code. Note that in this case the
86 backtrace shows how the
87 compilation was triggered (through C<use SomeModule;>, C<eval>s etc.).
88 The actual location of the error does not appear in the backtrace, but
89 rather in the attributes defined in this role.
a29e3879 »
2011-05-04 [S32/Exceptions] move %.payload into a separate class, based on feedb…
90
15b1a49e »
2011-05-08 [S32/Exceptions] add a few syntax errors
91 =head3 X::Syntax
92
93 role X::Syntax does X::Comp { }
94
95 Common role for all syntax errors.
96
97 =head4 X::Syntax::Obsolete
98
99 role X::Syntax::Obsolete does X::Syntax {
100 has $.ID;
101 has $.old;
102 has $.new;
103 has $.when = 'in Perl 6'
104 }
105
106 Message defaults to C<< Unsupported use of $<old>;$<when> please use $<new> >>.
107
108 =head4 X::Syntax::BadInfix
109
110 role X::Syntax::BadInfx does X::Syntax {
111 has $.bad;
112 }
113
114 Message defaults to C<< Preceding context expects a term, but found infix
115 $<bad> instead >>.
116
a29e3879 »
2011-05-04 [S32/Exceptions] move %.payload into a separate class, based on feedb…
117 =head2 X::AdHoc
118
119 class X::AdHoc is X::Base {
120 has %.payload;
121 method ID() { %.payload<ID> }
122 }
123
124 L<X::AdHoc> is meant for those too lazy to write their own exception
125 classes, but who still want to benefit from structured exceptions.
126
127 The C<Str> method in C<X::AdHoc> lets attribute lookup fall back to items
128 in C<%.payload>, ie if there's no C<$.foo> accessor for a name
129 C<< $<foo> >>, C<< %.payload<foo> >> is used instead.
b52825bf »
2011-05-22 [Exceptions] stub out Failure and Backtrace
130
131 =head1 Related types
132
133 =head2 Failure
134
135 class Failure is Mu {
136 has Bool $.handled is rw;
137 has $.X; # the actual exception object
138 }
139
140 An unthrown exception, usually produce by C<fail()>.
141
142 (Conjecture: S04 implies that all exceptions have a C<$.handled> attribute.
143 Do we actually need that?)
144
d91760b2 »
2011-08-23 [S32] backtrace renames, as suggested by masak++, jnthn++ and pmichaud++
145 =head2 Backtrace
b52825bf »
2011-05-22 [Exceptions] stub out Failure and Backtrace
146
d91760b2 »
2011-08-23 [S32] backtrace renames, as suggested by masak++, jnthn++ and pmichaud++
147 class Backtrace does Positional[Backtrace::Frame] {
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
148 method Stringy() { ... }
149 method full() { ... }
150 }
d91760b2 »
2011-08-23 [S32] backtrace renames, as suggested by masak++, jnthn++ and pmichaud++
151 class Backtrace::Frame {
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
152 has $.file;
153 has $.line;
154 has $.code;
155 has $.subname;
156
157 method is-hidden () { ... }
158 method is-routine() { ... }
159 method is-setting() { ... }
b52825bf »
2011-05-22 [Exceptions] stub out Failure and Backtrace
160 }
161
162 Backtrace information, typically used (but not limited to) in exceptions.
163 Stringifies to
164
165 in '$<routine>' at line $<line>:$<filename>
166 in '$<routine>' at line $<line>:$<filename>
167 ...
168
169 with two leading spaces on each line.
170
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
171 The default stringification includes blocks and routines from user-space
172 code, but from the setting only routines are shown [conjectural]. Routines
173 can be hidden from the default backtrace stringification by apply the
174 C<hidden_from_backtrace> trait:
175
176 sub my-die(*@msg) is hidden_from_backtrace { }
177
d91760b2 »
2011-08-23 [S32] backtrace renames, as suggested by masak++, jnthn++ and pmichaud++
178 the C<is-hidden> method in C<Backtrace::Frame> returns C<Bool::True> for routines
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
179 with that trait.
180
d91760b2 »
2011-08-23 [S32] backtrace renames, as suggested by masak++, jnthn++ and pmichaud++
181 The C<full> method in C<Backtrace> provides a string representation of the
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
182 backtrace that includes all available code objects, including hidden ones.
183
184 If a code object does not have a name, C<< <anon> >> is used instead of the
b52825bf »
2011-05-22 [Exceptions] stub out Failure and Backtrace
185 routine name.
a7cfe020 »
2011-08-23 [S32] backtraces overhaul
186
12c8b58f »
2011-12-19 [S32::Exceptions] briefly describe the default exception printer
187 =head1 The Default Exception Printer
188
189 In case an exception does not get caught by any C<CATCH> or C<CONTROL> block,
190 it is caught by a default handler in the setting.
191
192 This handler calls the C<.gist> method on the exception, prints the result,
193 and termintates the program. The exit code is determined as
194 C<$exception.?exit-code // 1>.
Something went wrong with that request. Please try again.