STklos Reference Manual : (version 2.10)

7. Exceptions and Conditions

7.1. Exceptions

The following text is extracted from SRFI-34 (Exception Handling for Programs), from which STklos exceptions are derived. Note that exceptions are now part of R⁷RS.

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.

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.

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.

STklos syntax

(with-handler <handler> <expr₁> … <expr_n>)

Evaluates the sequences of expressions <expr₁> to <expr_n>. <handler> must be a procedure that accepts one argument. It is installed as the current exception handler for the dynamic extent (as determined by dynamic-wind) of the evaluations of the expressions

(with-handler (lambda (c)
                (display "Catch an error\n"))
   (display "One ... ")
   (+ "will yield" "an error")
   (display "... Two"))
       |- "One ... Catch an error"

R⁷RS procedure

(with-exception-handler <handler> <thunk>)

This form is similar to with-handler. It uses a thunk instead of a sequence of expressions. It is conform to SRFI-34 (Exception Handling for Programs). In fact,

(with-handler <handler> <expr1> ... <exprn>)

is equivalent to

(with-exception-handler <handler>
  (lambda () <expr1> ... <exprn>))

R⁷RS procedure

(raise obj)

Invokes the current exception handler on obj. The handler is called in the dynamic environment of the call to raise, except that the current exception handler is that in place for the call to with-handler that installed the handler being called.

(with-handler (lambda (c)
             (format "value ~A was raised" c))
   (raise 'foo)
   (format #t "never printed\n"))
          => "value foo was raised"

R⁷RS procedure

(raise-continuable obj)

Raises an exception by invoking the current exception handler on obj. The handler is called with the same dynamic environment as the call to raise-continuable, except that: (1) the current exception handler is the one that was in place when the handler being called was installed, and (2) if the handler being called returns, then it will again become the current exception handler. If the handler returns, the values it returns become the values returned by the call to raise-continuable.

(with-exception-handler
  (lambda (con)
    (cond
      ((string? con)
       (display con))
      (else
       (display "a warning has been issued")))
    42)
  (lambda ()
    (+ (raise-continuable "should be a number")
       23)))
  ;; prints should be a number
                => 65

R⁷RS procedure

(guard (<var> <clause1 > <clause2 > …) <body>)

Evaluating a guard form evaluates <body> with an exception handler that binds the raised object to <var> and within the scope of that binding evaluates the clauses as if they were the clauses of a cond expression. That implicit cond expression is evaluated with the continuation and dynamic environment of the guard expression. If every <clause>s test evaluates to false and there is no else clause, then raise is re-invoked on the raised object within the dynamic environment of the original call to raise except that the current exception handler is that of the guard expression.

(guard (condition
         ((assq 'a condition) => cdr)
         ((assq 'b condition)))
  (raise (list (cons 'a 42))))
         => 42

(guard (condition
         ((assq 'a condition) => cdr)
         ((assq 'b condition)))
  (raise (list (cons 'b 23))))
         => (b . 23)

(with-handler (lambda (c) (format "value ~A was raised" c))
  (guard (condition
       ((assq 'a condition) => cdr)
       ((assq 'b condition)))
      (raise (list (cons 'x 0)))))
         => "value ((x . 0)) was raised"

STklos procedure

(current-exception-handler)

Returns the current exception handler. This procedure is defined in ,(link-srfi 18).

7.2. Conditions

The following text is extracted from SRFI-35 (Conditions), from which STklos conditions are derived.

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.

Conditions available in STklos are derived from SRFI-35 and in this SRFI two mechanisms to enable this kind of communication are provided:

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

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.

There is a tree of condition types with the distinguished &condition as its root. All other condition types have a parent condition type.

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

(struct->list C)

is a simple way to see it’s slots and their associated value.

STklos procedure

(make-condition-type id parent slot-names)

Make-condition-type returns a new condition type. Id must be a symbol that serves as a symbolic name for the condition type. Parent must itself be a condition type. Slot-names must be a list of symbols. It identifies the slots of the conditions associated with the condition type.

STklos procedure

(condition-type? obj)

Returns #t if obj is a condition type, and #f otherwise

STklos procedure

(make-compound-condition-type id ct₁ …)

Make-compound-condition-type returns a new condition type, built from the condition types ct₁, … Id must be a symbol that serves as a symbolic name for the condition type. The slots names of the new condition type is the union of the slots of conditions ct₁ …

This function is not defined in SRFI-34 (Exception Handling for Programs).

STklos procedure

(make-condition type slot-name value …)

Make-condition creates a condition value belonging condition type type. The following arguments must be, in turn, a slot name and an arbitrary value. There must be such a pair for each slot of type and its direct and indirect supertypes. Make-condition returns the condition value, with the argument values associated with their respective slots.

(let* ((ct (make-condition-type 'ct1 &condition '(a b)))
       (c  (make-condition ct 'b 2 'a 1)))
  (struct->list c))
     => ((a . 1) (b . 2))

STklos procedure

(condition? obj)

Returns #t if obj is a condition, and #f otherwise

STklos procedure

(condition-has-type? condition condition-type)

Condition-has-type? tests if condition belongs to condition-type. It returns #t if any of condition 's types includes condition-type either directly or as an ancestor and #f otherwise.

 (let* ((ct1 (make-condition-type 'ct1 &condition '(a b)))
        (ct2 (make-condition-type 'ct2 ct1 '(c)))
        (ct3 (make-condition-type 'ct3 &condition '(x y z)))
        (c   (make-condition ct2 'a 1 'b 2 'c 3)))
  (list (condition-has-type? c ct1)
     (condition-has-type? c ct2)
     (condition-has-type? c ct3)))
    => (#t #t #f)

STklos procedure

(condition-ref condition slot-name)

Condition must be a condition, and slot-name a symbol. Moreover, condition must belong to a condition type which has a slot name called slot-name, or one of its (direct or indirect) supertypes must have the slot. Condition-ref returns the value associated with slot-name.

(let* ((ct (make-condition-type 'ct1 &condition '(a b)))
       (c  (make-condition ct 'b 2 'a 1)))
  (condition-ref c 'b))
     => 2

STklos procedure

(condition-set! condition slot-name obj)

Condition must be a condition, and slot-name a symbol. Moreover, condition must belong to a condition type which has a slot name called slot-name, or one of its (direct or indirect) supertypes must have the slot. Condition-set! change the value associated with slot-name to obj.

Whereas condition-ref is defined in ,(srfi 35), confition-set! is not.

STklos procedure

(make-compound-condition condition₀ condition₁ …)

Make-compound-condition returns a compound condition belonging to all condition types that the condition_i belong to.

Condition-ref, when applied to a compound condition will return the value from the first of the conditioni that has such a slot.

STklos procedure

(extract-condition condition condition-type)

Condition must be a condition belonging to condition-type. Extract-condition returns a condition of condition-type with the slot values specified by condition. The new condition is always allocated.

(let* ((ct1 (make-condition-type 'ct1 &condition '(a b)))
       (ct2 (make-condition-type 'ct2 ct1 '(c)))
       (c2  (make-condition ct2 'a 1 ' b 2 'c 3))
       (c1  (extract-condition c2 ct1)))
  (list (condition-has-type? c1 ct2)
     (condition-has-type? c1 ct1)))
      => (#f #t)

7.3. Predefined Conditions

STklos implements all the conditions types which are defined in SRFI-35 (Conditions) and SRFI-36 (I/O Conditions). However, the access functions which are (implicitely) defined in those SRFIs are only available if the file "conditions" is required. This can be done with the call:

(require "conditions")

Another way to have access to the hierarchy of the SRFI-35 (Conditions) and SRFI-36 (I/O Conditions) condition:

(require-extension conditions)

The following hierarchy of conditions is predefined:

&condition
   &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)

1. Documentation about hygienic macros has been stolen in the SLIB manual

1. In fact define-module on a given name defines a new module only the first time it is invoked on this name. By this way, interactively reloading a module does not define a new entity, and the other modules which use it are not altered.

2. This transcript uses the default toplevel loop which displays the name of the current module in the evaluator prompt.

1. Under Unix, you can simply connect to a listening socket with the telnet of netcat command. For the given example, this can be achieved with netcat localhost 12345

2. Port 13, if open, can be used for testing: making a connection to it permits to know the distant system’s idea of the time of day.

1. The "pattern matching compiler" has been written by Jean-Marie Geffroy and is part of the Manuel Serrano’s Bigloo compiler since several years [Bigloo]