cond.skb 5.96 KB
Newer Older
eg's avatar
eg committed
1
;; ======================================================================
2
;;
eg's avatar
eg committed
3 4 5 6 7 8
;; 			STklos Reference Manual
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2 of the License, or
;; (at your option) any later version.
9
;;
eg's avatar
eg committed
10 11 12 13
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
14
;;
eg's avatar
eg committed
15 16
;; You should have received a copy of the GNU General Public License
;; along with this program; if not, write to the Free Software
17
;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
eg's avatar
eg committed
18 19 20
;; USA.
;;           Author: Erick Gallesio [eg@unice.fr]
;;    Creation date: 26-Nov-2000 18:19 (eg)
Erick Gallesio's avatar
Erick Gallesio committed
21
;; Last file update:  6-Jun-2007 19:19 (eg)
eg's avatar
eg committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
;;
;; ======================================================================

;; ======================================================================
;;
;;			EXCEPTIONS AND CONDITIONS
;;
;; ======================================================================
(chapter :title "Exceptions and Conditions"
(index "exception")
(index "condition")

(section :title "Exceptions"

(p [The following text is extracted from ,(link-srfi 34), from which ,(stklos)
exceptions are derived.])

(p [Exception handlers are one-argument procedures that determine the
action the program takes when an exceptional situation is
signalled. The system implicitly maintains a current exception
handler.])

(p [The program raises an exception by invoking the current exception
handler, passing to it an object encapsulating information about the
exception. Any procedure accepting one argument may serve as an
exception handler and any object may be used to represent an
exception.])

(p [The system maintains the current exception handler as part of the
dynamic environment of the program, akin to the current input or
output port, or the context for dynamic-wind. The dynamic environment
can be thought of as that part of a continuation that does not specify
the destination of any returned values. It includes the current input
and output ports, the dynamic-wind context, and this SRFI's current
exception handler.])

(insertdoc 'with-handler)
(insertdoc 'with-exception-handler)
(insertdoc 'raise)
Erick Gallesio's avatar
Erick Gallesio committed
61 62
(insertdoc 'guard)
(insertdoc 'current-exception-handler))
63 64


eg's avatar
eg committed
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
(section :title "Conditions"

(p [The following text is extracted from ,(link-srfi 35), from which ,(stklos)
conditions are derived.])

(p [Conditions are values that communicate information about exceptional
situations between parts of a program. Code that detects an exception
may be in a different part of the program than the code that handles
it. In fact, the former may have been written independently from the
latter. Consequently, to facilitate effective handling of exceptions,
conditions must communicate as much information as possible as
accurately as possible, and still allow effective handling by code
that did not precisely anticipate the nature of the exception that
occurred.])

(p [Conditions available in ,(stklos) are derived from ,(srfi 35) and in this
SRFI two mechanisms to enable this kind of communication are provided:])

(itemize
    (item [subtyping among condition types allows handling code to
determine the general nature of an exception even though it does
not anticipate its exact nature,])
    (item [compound conditions allow an exceptional situation to be
described in multiple ways.]))

(p [Conditions are structures with named slots. Each condition belongs to
one condition type (a condition type can be made from several
condition types). Each condition type specifies a set of
slot names. A condition belonging to a condition type includes a
value for each of the type's slot names. These values can be
extracted from the condition by using the appropriate slot name.])

(index "&condition")
(p [There is a tree of condition types with the distinguished ,(code "&condition")
as its root. All other condition types have a parent condition type.])

(p [Conditions are implemented with ,(stklos) structures (with a special bit
indicating that there are conditions). Of course, condition types are
implemented with structure types. As a consequence, functions on
structures or structures types are available on conditions or
conditions types (the contrary is not true). For instance, if C is a
condition, the expression])

(fontified-code [(struct->list C)])

(p [is a simple way to see it's slots and their associated value.])



(insertdoc 'make-condition-type)
(insertdoc 'condition-type?)
(insertdoc 'make-compound-condition-type)

(insertdoc 'make-condition)
(insertdoc 'condition?)
(insertdoc 'condition-has-type?)
(insertdoc 'condition-ref)
Erick Gallesio's avatar
Erick Gallesio committed
122
(insertdoc 'condition-set!)
eg's avatar
eg committed
123 124 125 126 127 128 129 130
(insertdoc 'make-compound-condition)
(insertdoc 'extract-condition))


(section :title "Predefined Conditions"
(index "SRFI-35")
(index "SRFI-36")

131 132 133
(p [,(stklos) implements all the conditions types which are defined in
,(link-srfi 35) and ,(link-srfi 36).
However, the access functions which are (implicitely) defined
eg's avatar
eg committed
134 135 136 137 138 139 140 141 142
in those SRFIs are only available if the file |"full-conditions.stk"| is
loaded. This can be done with the following call])

(fontified-code [(require "full-conditions")])


(p [The following hierarchy of conditions is predefined:])

(raw-code [
143
&condition
eg's avatar
eg committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
   &message (has "message" slot)
   &serious
   &error
      &error-message (has "message", "location" and "backtrace" slots)
      &i/o-error
         &i/o-port-error (has a "port" slot)
            &i/o-read-error
            &i/o-write-error
            &i/o-closed-error
        &i/o-filename-error (has a "filename" slots)
            &i/o-malformed-filename-error
            &i/o-file-protection-error
                &i/o-file-is-read-only-error
            &i/o-file-already-exists-error
            &i/o-no-such-file-error
     &read-error (has the "line", "column", "position" and "span" slots)
]))
)