source: project/wiki/eggref/4/simple-exceptions @ 33537

Last change on this file since 33537 was 33537, checked in by Mario Domenech Goulart, 4 years ago

simple-exceptions (wiki): typo fix (s/easyly/easily/)

File size: 6.2 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Exceptions made easy
5
6Chicken's condition system is versatile and flexible, but apart from the
7two high level exception handlers, handle-exceptions and condition-case,
8not very user friendly. In particular the low-level exception handler,
9with-exception-handler, must be used with extreme care to avoid
10non-terminating loops. Moreover creating and inspecting condition-objects
11is cumbersome.
12
13So this library introduces some procedures and macros to facilitate
14matters. Exceptions are introduced as special conditions, to be more
15precise, [composite] conditions of kind exn, which all have properties
16message, location and arguments, which can easily be accessed by
17procedures of that very name. They are constructed by separating the
18general property, message, and the general kinds, from the special
19properties, location and arguments, the latter being considered as
20parameters of an exception.
21
22In other words, one can define a global exception-variable of a special
23kind, e.g.
24
25<enscript highlight=scheme>
26(define assert-exn (make-exception "assertion violated" 'assert))
27</enscript>
28
29which can then be used within the definition of a procedure, foo say, as
30follows
31
32<enscript highlight=scheme>
33(raise (assert-exn 'foo 'xpr))
34</enscript>
35
36Here, raise is a version of abort with improved error messages.
37
38The exception raised can now be handled in the usual way, preferably
39
40<enscript highlight=scheme>
41(condition-case (foo arg) ((exn assert) ...))
42</enscript>
43
44or
45
46<enscript highlight=scheme>
47(handle-exceptions exn (if ((exception-of? 'assert) exn) ...) (foo arg))
48</enscript>
49
50but other handlers are provided as well, in particular, guard of R6RS
51and R7RS, and with-exn-handler, which has the same syntax as Chicken's
52with-exception-handler, but avoids its subtleties. For example, the
53follwing code does what you expect, it returns 0.
54
55<enscript highlight=scheme>
56(with-exn-handler (lambda (exn) 0) (lambda () (car '())))
57</enscript>
58
59without looping forewer, what with-exception-handler would have done.
60
61Another useful macro is assert* which -- contrary to assert -- allows
62many expressions to be tested and demands a location argument, which is
63used to produce a meaningful error-message.
64
65=== The interface
66
67==== current-exception-handler
68<parameter>(current-exception-handler [new-handler])</parameter>
69chicken's handler parameter reexported.
70
71==== exceptions
72<procedure>(exceptions [sym])</procedure>
73documentation procedure.
74
75==== exception?
76<procedure>(exception? xpr)</procedure>
77type predicate. Note, that each exception is a condition of kind exn.
78
79==== exception-of?
80<procedure>(exception-of? kind-key)</procedure>
81returns a unary predicate, which checks, if its argument expression is
82an exception of kind kind-key, a symbol.
83
84==== make-exception
85<procedure>(make-exception msg . kind-keys)</procedure>
86Returns a procedure of at least one argument, a symbol describing the
87location of its call, and an optional other argument, a list of
88arguments, which creates an exception of kinds kind-keys, message msg,
89as well as the given location and arguments.
90
91==== location
92<procedure>(location exn)</procedure>
93returns the location property of its exception argument.
94
95==== message
96<procedure>(message exn)</procedure>
97returns the message property of its exception argument.
98
99==== arguments
100<procedure>(arguments exn)</procedure>
101returns the arguments property of its exception argument.
102
103==== raise
104<procedure>(raise exn)</procedure>
105raises its argument, i.e. calls (current-exception-handler) with exn.
106In essence chicken's abort.
107
108==== with-exn-handler
109<procedure>(with-exn-handler handler thunk)</procedure>
110A save version of chicken's low-level with-exception-handler.
111Sets the current-exception-handler to handler for the dynamic extent of
112its call and executes thunk in this context.
113
114==== condition-case
115<macro>(condition-case xpr ([var] (kind ...) body) . other-clauses)))</macro>
116chicken's highest level exception-handler reexported.
117
118==== handle-exceptions
119<macro>(handle-exceptions exn handle-xpr xpr . xprs)</macro>
120chicken's high level exception handler reexported.
121
122==== guard
123<macro>(guard (exn cond-clause . cond-clauses) xpr . xprs)</macro>
124The high level exception handler of R6RS and R7RS.
125Sets the current-exception-handler to an exception-handler created from
126exn und the supplied cond-clauses for the dynamic extent of its call and
127executes the body xpr . xprs in this context.
128
129==== assert*
130<macro>(assert* loc xpr . xprs)</macro>
131checks the expressions xpr . xprs in sequence and raises an exception
132for the first failing expression with location property loc and
133arguments property the failing expression quoted.
134
135== Last update
136
137Jan 24, 2016
138
139== Author
140
141[[/users/juergen-lorenz|Juergen Lorenz]]
142
143== License
144
145 Copyright (c) 2014-2016, Juergen Lorenz
146 All rights reserved.
147
148 Redistribution and use in source and binary forms, with or without
149 modification, are permitted provided that the following conditions are
150 met:
151 
152 Redistributions of source code must retain the above copyright
153 notice, this list of conditions and the following disclaimer.
154 
155 Redistributions in binary form must reproduce the above copyright
156 notice, this list of conditions and the following disclaimer in the
157 documentation and/or other materials provided with the distribution.
158 Neither the name of the author nor the names of its contributors may be
159 used to endorse or promote products derived from this software without
160 specific prior written permission.
161   
162 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
163 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
164 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
165 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
166 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
167 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
168 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
169 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
170 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
171 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
172 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
173
174== Version History
175
176; 0.2 : with-handler renamed with-exn-handler
177; 0.1 : initial import
178
179
Note: See TracBrowser for help on using the repository browser.