3.1 Condition objects

Conceptually, there are two different kinds of condition objects: simple conditions and compound conditions. An object that is either a simple condition or a compound condition is simply a condition. Compound conditions form a type disjoint from the base types. A simple condition describes a single aspect of an exceptional situation. A compound condition represents multiple aspects of an exceptional situation as a list of simple conditions, its components. Most of the operations described in this section treat a simple condition identically to a compound condition with itself as its own sole component.

Condition Kind: &condition

Simple conditions are formal subtypes of the &condition kind. The &condition kind has no fields.

Function: condition condition1 …

Return a condition object with the components of the conditions as its components, in the same order, i.e., with the components of condition1 appearing first in the same order as in condition1, then with the components of condition2, and so on. The returned condition is compound if the total number of components is zero or greater than one. Otherwise, it may be compound or simple.

Function: simple-conditions condition

The simple-conditions procedure returns a list of the components of condition, in the same order as they appeared in the construction of condition. The returned list is immutable. If the returned list is modified, the effect on condition is unspecified.

NOTE Because condition decomposes its arguments into simple conditions, simple-conditions always returns a “flattened” list of simple conditions.

Function: condition? obj

Return #t if obj is a (simple or compound) condition, otherwise return #f.

Function: condition-kinds obj

The argument obj must be a condition object, either simple or compound. Return a list of symbols representing the condition kinds in obj; the list may contain duplicates.

(condition-kinds
  (condition (make-error)
             (make-who-condition 'me)
             (make-message-condition "the message")
             (make-irritants-condition '(1 2 3))))
⇒ (&error &serious &condition
    &who &condition
    &message &condition
    &irritants &condition)

Syntax: define-condition-type ?condition-kind ?supertype ?constructor ?predicate ?field-spec1 …

?condition-kind, ?supertype, ?constructor, and ?predicate must all be identifiers. Each ?field-spec must be of the form

(?field ?accessor)

where both ?field and ?accessor must be identifiers.

The define-condition-type form expands into a group of definitions for the constructor, predicate and field accessors for a new condition kind ?condition-kind. The identifiers will be bound as follows:

• ?constructor is bound to a default constructor for the kind: it accepts one argument for each of the record kind’s complete set of fields (including parent kinds, with the fields of the parent coming before those of the extension in the arguments) and returns a condition object initialised to those arguments. The returned object is a compound that contains the kind ?condition-kind, the kind ?supertype and all the parent kinds of ?supertype.
• ?predicate is bound to a predicate that identifies conditions of type ?condition-kind or any of its subtypes.
• Each ?accessor is bound to a procedure that extracts the corresponding field from a condition of type ?condition-kind. The fields of a condition kind are its properties as defined by the module (chicken condition).

Some usage examples:

(define-condition-type &c &condition
  make-c c?
  (x c-x))

(define-condition-type &c1 &c
  make-c1 c1?
  (a c1-a))

(define-condition-type &c2 &c
  make-c2 c2?
  (b c2-b))

(define v1 (make-c1 "V1" "a1"))

(c? v1)        ⇒ #t
(c1? v1)       ⇒ #t
(c2? v1)       ⇒ #f
(c-x v1)       ⇒ "V1"
(c1-a v1)      ⇒ "a1"

(define v2 (make-c2 "V2" "b2"))

(c? v2)        ⇒ #t
(c1? v2)       ⇒ #f
(c2? v2)       ⇒ #t
(c-x v2)       ⇒ "V2"
(c2-b v2)      ⇒ "b2"

(define v3 (condition
             (make-c1 "V3/1" "a3")
             (make-c2 "V3/2" "b3")))

(c? v3)        ⇒ #t
(c1? v3)       ⇒ #t
(c2? v3)       ⇒ #t
(c-x v3)       ⇒ "V3/1"
(c1-a v3)      ⇒ "a3"
(c2-b v3)      ⇒ "b3"

(define v4 (condition v1 v2))

(c? v4)        ⇒ #t
(c1? v4)       ⇒ #t
(c2? v4)       ⇒ #t
(c-x v4)       ⇒ "V1"
(c1-a v4)      ⇒ "a1"
(c2-b v4)      ⇒ "b2"

(define v5 (condition v2 v3))

(c? v5)        ⇒ #t
(c1? v5)       ⇒ #t
(c2? v5)       ⇒ #t
(c-x v5)       ⇒ "V2"
(c1-a v5)      ⇒ "a3"
(c2-b v5)      ⇒ "b2"

This document describes version 0.1.0-devel.1 of MMCK Exceptional Conditions.