r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

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