exceptions.texinfo (4632B)
1 @node Exceptions 2 @section Exceptions 3 4 This section describes Scheme's exception-handling and 5 exception-raising procedures. For the concept of Scheme exceptions, 6 see @ref{Error situations and unspecified behavior}. See also 7 @ref{Exception handling} for the @code{guard} syntax. 8 9 @define{Exception handlers} are one-argument procedures that determine 10 the action the program takes when an exceptional situation is 11 signaled. The system implicitly maintains a current exception handler 12 in the dynamic environment. 13 14 @cindex current exception handler 15 16 The program raises an exception by invoking the current exception 17 handler, passing it an object encapsulating information about the 18 exception. Any procedure accepting one argument can serve as an 19 exception handler and any object can be used to represent an exception. 20 21 @deffn procedure with-exception-handler handler thunk 22 23 It is an error if @var{handler} does not accept one argument. It is 24 also an error if @var{thunk} does not accept zero arguments. 25 26 The @code{with-exception-handler} procedure returns the results of 27 invoking @var{thunk}. @var{Handler} is installed as the current 28 exception handler in the dynamic environment used for the invocation 29 of @var{thunk}. 30 31 @lisp 32 (call-with-current-continuation 33 (lambda (k) 34 (with-exception-handler 35 (lambda (x) 36 (display "condition: ") 37 (write x) 38 (newline) 39 (k 'exception)) 40 (lambda () 41 (+ 1 (raise 'an-error)))))) 42 @result{} @r{exception} 43 @print{} condition: an-error 44 45 (with-exception-handler 46 (lambda (x) 47 (display "something went wrong\n")) 48 (lambda () 49 (+ 1 (raise 'an-error)))) 50 @print{} something went wrong 51 @end lisp 52 53 After printing,the second example then raises another exception. 54 55 @end deffn 56 57 @deffn procedure raise obj 58 59 Raises an exception by invoking the current exception handler on 60 @var{obj}. The handler is called with the same dynamic environment as 61 that of the call to @code{raise}, except that the current exception 62 handler is the one that was in place when the handler being called was 63 installed. If the handler returns, a secondary exception is raised 64 in the same dynamic environment as the handler. The relationship 65 between @var{obj} and the object raised by the secondary exception 66 is unspecified. 67 68 @end deffn 69 70 @deffn procedure raise-continuable obj 71 72 Raises an exception by invoking the current exception handler on 73 @var{obj}. The handler is called with the same dynamic environment 74 as the call to @code{raise-continuable}, except that: (1) the current 75 exception handler is the one that was in place when the handler being 76 called was installed, and (2) if the handler being called returns, 77 then it will again become the current exception handler. If the 78 handler returns, the values it returns become the values returned by 79 the call to @code{raise-continuable}. 80 81 @lisp 82 (with-exception-handler 83 (lambda (con) 84 (cond 85 ((string? con) 86 (display con)) 87 (else 88 (display "a warning has been issued"))) 89 42) 90 (lambda () 91 (+ (raise-continuable "should be a number") 92 23))) 93 @print{} should be a number 94 @result{} 65 95 @end lisp 96 97 @end deffn 98 99 @deffn procedure error message obj@dots{} 100 101 @var{Message} should be a string. 102 103 Raises an exception as if by calling @code{raise} on a newly 104 allocated implementation-defined object which encapsulates the 105 information provided by @var{message}, as well as any @var{obj}s, 106 known as the @define{irritants}. The procedure @code{error-object?} 107 must return @code{#t} on such objects. 108 109 @lisp 110 (define (null-list? l) 111 (cond ((pair? l) #f) 112 ((null? l) #t) 113 (else 114 (error 115 "null-list?: argument out of domain" 116 l)))) 117 @end lisp 118 @end deffn 119 120 @deffn procedure error-object? obj 121 122 Returns @code{#t} if @var{obj} is an object created by @code{error} 123 or one of an implementation-defined set of objects. Otherwise, it 124 returns @code{#f}. The objects used to signal errors, including those 125 which satisfy the predicates @code{file-error?} and @code{read-error?}, 126 may or may not satisfy @code{error-object?}. 127 128 @end deffn 129 130 @deffn procedure error-object-message error-object 131 132 Returns the message encapsulated by @var{error-object}. 133 134 @end deffn 135 136 @deffn procedure error-object-irritants error-object 137 138 Returns a list of the irritants encapsulated by @var{error-object}. 139 140 @end deffn 141 142 @deffn procedure read-error? obj 143 @deffnx procedure file-error? obj 144 145 Error type predicates. Returns @code{#t} if @var{obj} is an object 146 raised by the @code{read} procedure or by the inability to open an 147 input or output port on a file, respectively. Otherwise, it returns 148 @code{#f}. 149 150 @end deffn