This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home.

Source for wiki ConditionsCowan version 2

author

cowan

comment

ipnr

74.68.121.27

name

ConditionsCowan

readonly

text

== Conditions ==

This is a WG2 proposal for condition objects. A condition object encapsulates information about an
exceptional situation. Typically the rest of the system is notified about a condition using the `raise` and `raise-continuable` predicates and their relatives. Conditions are logically independent of the exception system, however: conditions may be used for any purpose, and any object may be passed to the exception system.

The design of this condition system attempts to assume as little as possible about any existing implementation-specific condition system. In particular, there is no specified relationship between conditions and records, as there is in R6RS, nor is there any notion of subtyping required by the system. There are condition types for convenience in dispatching, but they are just symbols and in general entail nothing about what information is encapsulated, as different implementations will provide different kinds of information when creating an implementation-specified condition.

Within the above constraints, I have attempted to make the names as compatible as possible with [http://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-8.html#node_sec_7.2 the R6RS condition system] and its predecessors [http://srfi.schemers.org/srfi-35/srfi-35.html SRFI 35] and [http://srfi.schemers.org/srfi-36/srfi-36.html SRFI 36], and with [http://srfi.schemers.org/srfi-12/srfi-12.html SRFI 12].

A condition is said to be "belong to type ''sym''" if (a) it was created by a call to `make-condition` that was passed the symbol `sym` as one of its condition types, or (b) it belongs to an implementation-defined set (possibly empty) of conditions of type ''sym''. This allows implementation-dependent condition objects to participate in this condition system.

== Constructor ==

`(make-condition `''symlist'' ( ''sym'' ''obj'' ) ...`)`

Returns a newly allocated condition which belongs to the types whose names are given in `symlist`. The remainder of the arguments are alternating property names (which are symbols) and values (which can be any object) that specify the information encapsulated by this condition. It is an error if the value associated with the property name `message` is not a string; it is also an error if the value associated with the property name `irritants` is not a list.

== Predicates ==

`(condition? `''obj''`)`

Returns `#t` if ''obj'' is a condition of any type, and `#f` otherwise.

`(condition-of-type? `''obj'' ''sym''`)`

Returns `#t` if ''obj'' is a condition belonging to type ''sym'', and `#f` otherwise.

== Accessors ==

`(condition-types `''condition''`)`

Returns the list of types to which ''condition'' belongs. It is an error to attempt to mutate this list.

`(condition-properties `''condition''`)`

Returns the list of property names associated with this condition. It is an error to attempt to mutate this list.

`(condition-ref `''condition sym'' [ ''default'' ] `)`

Returns the property value associated with the property named ''sym'' of ''condition''. If there is no such property, returns ''default''. If ''default'' is not specified, returns `#f`.

== Meta ==

`(condition-predicate `''sym''`)`

Returns a predicate which will return `#t` if applied to a condition belonging to type ''sym'', and `#f` otherwise.

`(condition-accessor `''sym'' [ ''default'' ] `)`

Returns an accessor which will return the value of ''sym'' if applied to a condition object and ''default'' otherwise. If ''default'' is not specified, the accessor will return `#f`.

== Specific predicates ==

`(error-object? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `simple`, and `#f` otherwise. Such conditions are normally created only by user code. ''Part of the small language, but shown here for completeness.''

`(file-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `file`, and `#f` otherwise. Such conditions may be created by the implementation if there is an error related to file operations; in particular, the inability to open a file for input. ''Part of the small language, but shown here for completeness.''

`(read-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `read`, and `#f` otherwise. Such conditions may be created by the implementation if there is an error related to `read`, such as a lexical syntax error in the input. ''Part of the small language, but shown here for completeness.''

`(syntax-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `syntax`, and `#f` otherwise. Such conditions may be created by the implementation if program code is syntactically ill-formed. When such a condition is raised, it may or may not be possible for the exception system to catch it. ''Part of the small language, but shown here for completeness.''

`(domain-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `domain`, and `#f` otherwise. Such conditions may be created by the implementation if a procedure is passed an argument that is not in its domain, either because it is of the wrong type or because it has an unacceptable value, as well as in analogous situations.

`(mismatch-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `mismatch`, and `#f` otherwise. Such conditions may be created by the implementation if a procedure is passed too many or too few arguments, as well as in analogous situations.

`(immutability-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `immutability`, and `#f` otherwise. Such conditions may be created by the implementation on an attempt to modify immutable data, as well as in analogous situations.

`(undefined-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `undefined`, and `#f` otherwise. Such conditions may be created by the implementation if an attempt is made to get the value of a variable that has not been defined, as well as in analogous situations.

`(non-continuable-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition of type `non-continuable`, and `#f` otherwise. Such conditions may be created by the implementation if an attempt is made to continue from an exception raised by `raise`, as well as in analogous situations.

`(input-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `input`, and `#f` otherwise. Such conditions may be created by the implementation if an input error occurs, as well as in analogous situations.

`(output-error? `''obj''`)`

Returns `#t` if ''obj'' is a condition belonging to type `output`, and `#f` otherwise. Such conditions may be created by the implementation if an output error occurs, as well as in analogous situations.

`(implementation-restriction? `''obj''`)`

Returns `#t` if ''obj'' is a condition of type `implementation-restriction`, and `#f` otherwise. Such conditions may be created by the implementation if an implementation restriction occurs such as running out of memory or exceeding the maximum representable size of an exact number, as well as in analogous situations.

== Specific accessors ==

`(condition-message `''condition''`)`

Returns the value of the `message` property associated with ''condition'', or `#f` if there is none. This value should be a string.

`(condition-irritants `''condition''`)`

Returns the value of the `irritants` property associated with ''condition'', or `#f` if there is none. This value should be a list.

time

2012-12-23 01:18:31