@iftex
@finalout
@end iftex
-@comment $Id: scheme.texinfo,v 1.42 1994/08/11 05:09:55 cph Exp $
+@comment $Id: scheme.texinfo,v 1.43 1994/08/12 07:56:47 cph Exp $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename scheme
@settitle MIT Scheme Reference
@titlepage
@title{MIT Scheme Reference Manual}
-@subtitle Edition 1.42 beta
+@subtitle Edition 1.43 beta
@subtitle for Scheme Release 7.3
-@subtitle 11 August 1994
+@subtitle 12 August 1994
@author by Chris Hanson
@author the MIT Scheme Team
@author and a cast of thousands
* Operations on Pathnames::
* Miscellaneous Pathnames::
+Error System
+
+* Condition Types::
+* Condition Instances::
+* Condition Signalling::
+* Condition Handling::
+* Restarts::
+* Error Messages::
+* Taxonomy::
+
+Condition Instances
+
+* Generating operations on conditions::
+* Condition State::
+* Simple Condition Instance Operations::
+
+Restarts
+
+* Establishing Restart Code::
+* Invoking Standard Restart Code::
+* Finding and Invoking General Restart Code::
+* The Named Restart Abstraction::
+
Graphics
* Opening and Closing of Graphics Devices::
@node Error System, Graphics, File-System Interface, Top
@chapter Error System
-This chapter is being rewritten and is not yet finished.
+@findex error
+The MIT Scheme error system provides a uniform mechanism for the signalling
+of errors and other exceptional conditions. For many purposes, the only
+part of the error system that is needed is the procedure @code{error},
+which is used to signal simple errors, specifying a message and some
+irritant objects (@pxref{Condition Signalling}). In addition, an option
+to @code{error} permits users to do simple formatting of their error
+messages (@pxref{Error Messages}).
+
+More demanding applications require more powerful facilities. To give a
+concrete example, suppose you want floating-point division to return a very
+large number whenever the denominator is zero. This behavior can be
+implemented using the error system.
+
+The Scheme arithmetic system can signal many different kinds of errors,
+including floating-point divide by zero. In our example, we would like to
+handle this particular condition specially, allowing the system to handle
+other arithmetic errors in its usual way.
+
+The error system supports this kind of application by providing
+mechanisms for distinguishing different types of error conditions and
+for specifying where control should be transferred should a given
+condition arise. In this example, there is a specific object that
+represents the ``floating-point divide by zero'' condition type, and it
+is possible to dynamically specify an arbitrary Scheme procedure to be
+executed when a condition of that type is signalled. This procedure
+then finds the stack frame containing the call to the division operator,
+and returns the appropriate value from that frame.
+
+Another useful kind of behavior is the ability to specify uniform
+handling for related classes of conditions. For example, it might be
+desirable, when opening a file for input, to gracefully handle a variety of
+different conditions associated with the file system. One such condition
+might be that the file does not exist, in which case the program will try
+some other action, perhaps opening a different file instead. Another
+related condition is that the file exists, but is read protected, so it
+cannot be opened for input. If these or any other related conditions
+occur, the program would like to skip this operation and move on to
+something else.
+
+At the same time, errors unrelated to the file system should be treated in
+their usual way. For example, calling @code{car} on the argument @code{3}
+should signal an error. Or perhaps the name given for the file is
+syntactically incorrect, a condition that probably wants to be handled
+differently from the case of the file not existing.
+
+@cindex taxonomical link, of condition type (defn)
+@cindex specialization, of condition types (defn)
+@cindex generalization, of condition types (defn)
+To facilitate the handling of classes of conditions, the error system
+taxonomically organizes all condition types. The types are related to one
+another by @dfn{taxonomical links}, which specify that one type is a ``kind
+of'' another type. If two types are linked this way, one is considered to
+be a @dfn{specialization} of the other; or vice-versa, the second is a
+@dfn{generalization} of the first. In our example, all of the errors
+associated with opening an input file would be specializations of the
+condition type ``cannot open input file''.
+
+@vindex condition-type:simple-condition
+@vindex condition-type:warning
+@vindex condition-type:breakpoint
+@vindex condition-type:serious-condition
+The taxonomy of condition types permits any condition type to have no
+more than one immediate generalization. Thus, the condition types form
+a forest (set of trees). While users can create new trees, the standard
+taxonomy (@pxref{Taxonomy}) is rooted at
+@code{condition-type:simple-condition}, @code{condition-type:warning},
+@code{condition-type:breakpoint}, and
+@code{condition-type:serious-condition}; users are encouraged to add new
+subtypes to these condition types rather than create new trees in the
+forest.
+
+To summarize, the error system provides facilities for the following tasks.
+The sections that follow will describe these facilities in more
+detail.
+
+@table @asis
+@item Classification of conditions
+@cindex condition-type
+@cindex type, condition
+@cindex specialization, of condition types
+@cindex generalization, of condition types
+Each condition has a type, represented by a @code{condition-type}
+object. Each condition type may be a specialization of some other
+condition types. A group of types that share a common generalization
+can be handled uniformly by specifying a handler for the generalization.
+
+@item Packaging condition state
+Each condition is represented by an explicit object. Condition objects
+contain information about the nature of the condition, information that
+describes the state of the computation from which the condition arose,
+and information about the ways the computation can be restarted.
+
+@item Signalling a condition
+@findex signal-condition
+A condition may be signalled in a number of different ways. Simple
+errors may be signalled, without explicitly defining a condition type,
+using @code{error}. The @code{signal-condition} procedure provides the
+most general signalling mechanism.
+
+@item Handling a condition
+@findex bind-condition-handler
+The programmer can dynamically specify handlers for particular condition
+types or for classes of condition types, by means of the
+@code{bind-condition-handler} procedure. Individual handlers have
+complete control over the handling of a condition, and additionally may
+decide not to handle a particular condition, passing it on to previously
+bound handlers.
+
+@item Restarting from a handler
+@findex with-restart
+The @code{with-restart} procedure provides a means for
+condition-signalling code to communicate to condition-handling code what
+must be done to proceed past the condition. Handlers can examine the
+restarts in effect when a condition was signalled, allowing a structured
+way to continue an interrupted computation.
+@end table
+
+@menu
+* Condition Types::
+* Condition Instances::
+* Condition Signalling::
+* Condition Handling::
+* Restarts::
+* Error Messages::
+* Taxonomy::
+@end menu
+
+@node Condition Types, Condition Instances, , Error System
+@section Condition Types
+
+@cindex condition type
+@cindex type, of condition
+Each condition has a @dfn{condition type} object associated with it.
+These objects are used as a means of focusing on related classes of
+conditions, first by concentrating all of the information about a
+specific class of condition in a single place, and second by specifying
+an inheritance relationship between types. This inheritance
+relationship forms the taxonomic structure of the condition hierarchy
+(@pxref{Taxonomy}).
+
+The following procedures consititute the abstraction for condition
+types.
+
+@deffn {procedure+} make-condition-type name generalization field-names reporter
+@cindex generalization, of condition types
+Creates and returns a (new) condition type that is a specialization of
+@var{generalization} (if it is a condition type) or is the root of a new
+tree of condition types (if @var{generalization} is @code{#f}). For
+debugging purposes, the condition type has a @var{name}, and instances
+of this type contain storage for the fields specified by
+@var{field-names} (a list of symbols) in addition to the fields common
+to all conditions.
+
+@var{Reporter} is used to produce a description of a particular
+condition of this type. It may be a string describing the condition, a
+procedure of arity two (the first argument will be a condition of this
+type and the second a port) that will @code{write} the message to the
+given port, or @code{#f} to specify that the reporter should be taken
+from the condition type @var{generalization} (or produce an
+``undocumented condition of type ...'' message if @var{generalization}
+is @code{#f}).
+
+By convention, the report generate by @var{reporter} should consist of
+one or more complete sentences. The usual rules for sentences should be
+followed: the first word of the sentence should be capitalized, and the
+sentence is normally terminated by a period.
+@end deffn
+
+@deffn {procedure+} condition-type/error? condition-type
+@vindex condition-type:error
+@cindex specialization, of condition types
+Returns @code{#t} if the @var{condition-type} is
+@code{condition-type:error} or a specialization of it, @code{#f}
+otherwise.
+@end deffn
+
+@deffn {procedure+} condition-type/field-names condition-type
+@cindex generalization, of condition types
+Returns a list of all of the field names for a condition of type
+@var{condition-type}. This is the set union of the fields specified
+when this @var{condition-type} was created with the
+@code{condition-type/field-names} of the generalization of this
+@var{condition-type}.
+@end deffn
+
+@deffn {procedure+} condition-type/generalizations condition-type
+@cindex generalization, of condition types
+Returns a list of all of the generalizations of @var{condition-type}.
+Notice that every condition-type is considered a generalization of
+itself.
+@end deffn
+
+@deffn {procedure+} condition-type? object
+Returns @code{#f} if and only if @var{object} is not a
+condition-type.
+@end deffn
+
+@node Condition Instances, Condition Signalling, Condition Types, Error System
+@section Condition Instances
+
+@cindex condition (defn)
+@cindex condition instance (defn)
+@cindex instance, of condition (defn)
+A @dfn{condition}, in addition to the information associated with its
+type, usually contains other information that is not shared with other
+conditions of the same type. For example, the condition type associated
+with unbound variable errors does not specify the name of the variable
+that was unbound. The additional information is captured in
+@dfn{condition} objects, also called @dfn{condition instances}.
+
+In addition to information that is specific to a given type of condition
+(such as the variable name for ``unbound variable'' conditions), every
+condition instance also contains a continuation that encapsulates the
+state of the computation in which the condition occurred. This
+continuation is used for analyzing the computation to learn more about
+the context in which the condition occurred. It is @emph{not} intended
+to provide a mechanism for continuing the computation; that mechanism is
+provided by restarts.
+
+@menu
+* Generating operations on conditions::
+* Condition State::
+* Simple Condition Instance Operations::
+@end menu
+
+@node Generating operations on conditions, Condition State, , Condition Instances
+@subsection Generating operations on conditions
+
+@findex condition-constructor
+@findex condition-accessor
+@findex condition-signaller
+@findex condition-predicate
+Scheme provides four procedures that take a condition-type as input and
+produce operations on the corresponding condition object. These are
+reminiscent of the operations on record types that produce record
+operators (@pxref{Records}). Given a condition-type it is possible to
+generate: constructors for instances of the type (using
+@code{condition-constructor}); accessors for the fields in the instance
+(using @code{condition-accessor}); a predicate to test for instances of
+the type (using @code{condition-predicate}); and procedures to create
+and signal an instance of the type (using @code{condition-signaller}).
+
+Notice that the creation of a condition object is distinct from
+signalling an occurrence of the condition. Condition objects are
+first-class; they may be created and never signalled, or they may be
+signalled more than once. Further notice that there are no procedures
+for modifying conditions; once created, a condition cannot be altered.
+
+@deffn {procedure+} condition-constructor condition-type field-names
+@findex condition/restarts
+@cindex bound-restarts
+@cindex restarts, bound
+Returns a constructor procedure that creates condition objects of type
+@var{condition-type}, requiring at the time the instance is constructed
+values for the fields specified in @var{field-names}. The constructor
+procedure returned by @code{condition-constructor} has signature
+
+@example
+(lambda (@var{continuation} @var{restarts} . @var{field-values}) ...)
+@end example
+
+@noindent
+where the @var{field-names} correspond to the @var{field-values}. The
+constructor argument @var{restarts} specifies what restart points are to
+be made available if the condition is signalled. It can be the symbol
+@code{bound-restarts} (meaning all restarts in the dynamic context at
+the time the condition is constructed), another condition object (the
+restarts available from that condition using @code{condition/restarts}),
+or an explicit list of restart objects. Note that passing the symbol
+@code{bound-restarts} as the @var{restarts} argument is equivalent to
+the passing the result of evaluating @code{(bound-restarts)}, but
+faster. Conditions created by the constructor procedure have @code{#f}
+for the values of all fields other than those specified by
+@var{field-names}.
+
+For example, the following procedure @code{make-simple-warning}
+constructs a condition of type @code{condition-type:simple-warning}
+given a continuation (where the condition occurred), a description of
+the restarts to be made available (as above), a warning message, and a
+list of irritants that caused the warning:
+
+@example
+(define make-simple-warning
+ (condition-constructor condition-type:simple-warning
+ '(MESSAGE IRRITANTS)))
+@end example
+@end deffn
+
+@deffn {procedure+} condition-accessor condition-type field-name
+@cindex specialization, of condition types
+Returns a procedure that takes as input a condition object of type
+@var{condition-type} and extracts the contents of the specified
+@var{field-name}. @code{condition-accessor} signals
+@code{error:bad-range-argument} if the @var{field-name} isn't one of the
+named fields of @var{condition-type}; the returned procedure will signal
+@code{error:wrong-type-argument} if passed an object other than a
+condition of type @var{condition-type} or one of its specializations.
+
+@findex access-condition
+If it is known in advance that a particular field of a condition will be
+accessed repeatedly it is worth constructing an accessor for the field
+using @code{condition-accessor} rather than using the (possibly more
+convenient, but slower) @code{access-condition} procedure.
+@end deffn
+
+@deffn {procedure+} condition-predicate condition-type
+@cindex specialization, of condition types
+Returns a predicate procedure for testing whether an object is a
+condition of type @var{condition-type} or one of its specializations
+(there is no predefined way to test for a condition of a given type but
+@emph{not} a specialization of that type).
+@end deffn
+
+@deffn {procedure+} condition-signaller condition-type field-names default-handler
+Returns a signalling procedure with parameters @var{field-names}. When
+the signalling procedure is called it creates and signals a condition of
+type @var{condition-type}. If the condition isn't handled (i.e.@: if no
+handler is invoked that causes an escape from the current continuation)
+the signalling procedure reduces to a call to @var{default-handler} with
+the condition as its argument.
+
+There are several standard procedures that are conventionally used for
+@var{default-handler}. If @var{condition-type} is a specialization of
+@code{condition-type:error}, @var{default-handler} should be the
+procedure @code{standard-error-handler}. If @var{condition-type} is a
+specialization of @code{condition-type:warning}, @var{default-handler}
+should be the procedure @code{standard-warning-handler}. If
+@var{condition-type} is a specialization of
+@code{condition-type:breakpoint}, @var{default-handler} should be the
+procedure @code{standard-breakpoint-handler}.
+@end deffn
+
+@node Condition State, Simple Condition Instance Operations, Generating operations on conditions, Condition Instances
+@subsection Condition Abstraction
+
+@findex condition?
+The condition data type is abstracted through a predicate
+@code{condition?} and a set of accessor procedures.
+
+@deffn {procedure+} condition? object
+Returns @code{#f} if and only if @var{object} is not a condition.
+@end deffn
+
+@deffn {procedure+} condition/continuation condition
+@findex condition/restarts
+Returns the continuation specified when @var{condition} was created.
+This is provided for inspecting the state of the system when the
+condition occurred, @emph{not} for continuing or restarting the
+computation (see @code{condition/restarts}).
+@end deffn
+
+@deffn {procedure+} condition/error? condition
+@vindex condition-type:error
+@cindex specialization, of condition types
+Returns @code{#t} if the @var{condition} is an instance of
+condition-type @code{condition-type:error} or a specialization of it,
+@code{#f} otherwise.
+@end deffn
+
+@deffn {procedure+} condition/report-string condition
+@findex write-condition-report
+Returns a string containing a report of the @var{condition}. This is
+generated by calling @code{write-condition-report} on @var{condition}
+and a string output port, and returning the output collected by the port
+as a string.
+@end deffn
+
+@deffn {procedure+} condition/restarts condition
+Returns the list of restarts specified when @var{condition} was created.
+@end deffn
+
+@deffn {procedure+} condition/type condition
+Returns the condition-type of which @var{condition} is an instance.
+@end deffn
+
+@node Simple Condition Instance Operations, , Condition State, Condition Instances
+@subsection Simple Operations on Condition Instances
+
+The simple procedures described in this section are built on top of the
+more detailed abstraction of condition objects described above. While
+these procedures are sometimes easier to use, they are often less
+efficient.
+
+@deffn {procedure+} make-condition condition-type continuation restarts field-plist
+@findex condition/restarts
+@cindex bound-restarts
+@cindex restarts, bound
+Create a new condition object as an instance of @var{condition-type},
+associated with @var{continuation}. The @var{continuation} is provided
+for inspection purposes only, @emph{not} for restarting the computation.
+@var{Restarts} can be the symbol @code{bound-restarts} (in which case
+all restarts in the current dynamic context will be substituted), a
+condition object (the value of @code{(condition/restarts
+@var{restarts})} will be substituted), or an explicit list of restart
+objects.
+
+The @var{field-plist} is an alternating list of field names and values
+for those fields, where the field names are those that would be returned
+by @code{(condition-type/field-names @var{condition-type})}. It is used
+to provide values for fields in the condition object; fields with no
+value specified are set to @code{#f}. Once a condition object has been
+created there is no way to alter the values of these fields.
+@end deffn
+
+@deffn {procedure+} access-condition condition field-name
+@findex condition-accessor
+Returns the value stored in the field @var{field-name} within
+@var{condition}. @var{Field-name} must be one of the names returned by
+@code{(condition-type/field-names (condition/type @var{condition}))}.
+@code{access-condition} looks up the @var{field-name} at runtime, so it
+is more efficient to use @code{condition-accessor} to create an access
+function if the same field is to be extracted from various instances of
+the same condition-type.
+@end deffn
+
+@deffn {procedure+} write-condition-report condition port
+@findex condition/report-string
+Writes a description of @var{condition} to @var{port}, using the
+reporter function from the condition-type associated with
+@var{condition}. See also @code{condition/report-string}.
+@end deffn
+
+@node Condition Signalling, Condition Handling, Condition Instances, Error System
+@section Condition Signalling
+
+@cindex condition signalling (defn)
+@cindex signalling, of condition (defn)
+@findex make-condition
+Once a condition instance has been created using @code{make-condition}
+(or any condition constructor), it can be @dfn{signalled}. The act of
+signalling a condition is separated from the act of creating the
+condition to allow more flexibility in how conditions are handled. For
+example, a condition instance could be returned as the value of a
+procedure, indicating that something unusual has happened, to allow the
+caller to clean up some state. The caller could then signal the
+condition once it is ready.
+
+A more important reason for having a separate condition signalling
+mechanism is that it allows @emph{resignalling}. When a signalled
+condition has been caught by a particular handler, and the handler decides
+that it doesn't want to process that particular condition, it can signal
+the condition again. This is one way to allow other handlers to get a
+chance to see the condition.
+
+@deffn {procedure+} error reason argument...
+@cindex REP loop
+@findex signal-condition
+@findex warn
+This is simplest and most common way to signal a condition that requires
+intervention before a computation can proceed (when intervention is not
+required, @code{warn} is more appropriate). @code{error} signals a
+condition (using @code{signal-condition}), and if no handler for that
+condition alters the flow of control (by invoking a restart, for
+example) it calls the procedure @code{standard-error-handler}. Under
+normal circumstances @code{error} will not return a value (although an
+interactive debugger can be used to force this to occur).
+
+@findex make-condition
+Precisely what condition is signalled depends on the first argument to
+@code{error}. If @var{reason} is a condition, then that condition is
+signalled and the @var{argument}s are ignored. If @var{reason} is a
+condition-type, then a new instance of this type is generated and
+signalled; the @var{argument}s are used to generate the values of the
+fields for this condition type (they are passed as the @var{field-plist}
+argument to @code{make-condition}).
+
+@vindex condition-type:simple-error
+In the most common case, however, @var{reason} is neither a condition
+nor a condition-type, but rather a string or symbol. In this case a
+condition of type @code{condition-type:simple-error} is created with the
+@code{message} field containing the @var{reason} and the
+@code{irritants} field containing the @var{argument}s.
+@end deffn
+
+@deffn {procedure+} warn datum argument...
+@findex error
+@findex signal-condition
+@vindex condition-type:simple-warning
+When a condition is not severe enough to warrant intervention, it is
+appropriate to signal the condition with @code{warn} rather than
+@code{error}. As with @code{error}, @code{warn} first calls
+@code{signal-condition}; the condition that is signalled is chosen
+exactly as in @code{error} except that a condition of type
+@code{condition-type:simple-warning} is used if @var{datum} is neither a
+condition nor a condition-type. If the condition is not handled,
+@code{warn} calls the procedure @code{standard-warning-handler}.
+
+@findex muffle-warning
+@code{warn} establishes a restart named @code{muffle-warning} before
+calling @code{signal-condition}. This allows a signal handler to
+prevent the generation of the warning message by calling
+@code{muffle-warning}. The value of a call to @code{warn} is
+unspecified.
+@end deffn
+
+@deffn {procedure+} signal-condition condition
+@cindex generalization, of condition types
+@cindex specialization, of condition types
+@findex break-on-signals
+@findex bind-default-condition-handler
+@findex bind-condition-handler
+This is the fundamental operation for signalling a condition. The
+precise operation of @code{signal-condition} depends on the
+condition-type of which @var{condition} is an instance, the condition
+types set by @code{break-on-signals}, and the handlers established by
+@code{bind-condition-handler} and @code{bind-default-condition-handler}.
+
+@cindex REP loop
+If the @var{condition} is an instance of a type that is a specialization
+of any of the types specified by @code{break-on-signals}, then a
+breakpoint @sc{repl} is initiated. Otherwise (or when that @sc{repl}
+returns), the handlers established by @code{bind-condition-handler} are
+checked, most recent first. Each applicable handler is invoked, and the
+search for a handler continues if the handler returns normally. If all
+applicable handlers return, then the applicable handlers established by
+@code{bind-default-condition-handler} are checked, again most recent
+first. Finally, if no handlers apply (or all return in a normal
+manner), @code{signal-condition} returns an unspecified value.
+
+@emph{Note:} unlike many other systems, the MIT Scheme runtime library
+does @emph{not} establish handlers of any kind. (However, the Edwin
+text editor uses condition handlers extensively.) Thus, calls to
+@code{signal-condition} will return to the caller unless there are user
+supplied condition handlers, as the following example shows:
+
+@example
+@group
+(signal-condition
+ (make-condition
+ condition-type:error
+ (call-with-current-continuation (lambda (x) x))
+ '() @r{; no restarts}
+ '())) @r{; no fields}
+@result{} @r{unspecified}
+@end group
+@end example
+@end deffn
+
+@node Condition Handling, Restarts, Condition Signalling, Error System
+@section Condition Handling
+
+@cindex handler, condition (defn)
+@cindex condition handler (defn)
+@findex bind-condition-handler
+@findex bind-default-condition-handler
+The occurrence of a condition is signalled using
+@code{signal-condition}. @code{signal-condition} attempts to locate and
+invoke a @dfn{condition handler} that is prepared to deal with the type
+of condition that has occurred. A condition handler is a procedure of
+one parameter, the condition that is being signalled. A procedure is
+installed as a condition handler by calling
+@code{bind-condition-handler} (to establish a handler that is in effect
+only while a particular thunk is executing) or
+@code{bind-default-condition-handler} (to establish a handler that is in
+effect permanently). As implied by the name, handlers created by
+@code{bind-default-condition-handler} are invoked only after all other
+applicable handlers have been invoked.
+
+A @var{handler} may process a signal in any way it deems appropriate,
+but the common patterns are:
+@table @asis
+@item Ignore the condition.
+By returning from the handler in the usual manner.
+
+@item Handle the condition.
+By doing some processing and then invoking a continuation captured at
+some point prior to the call to @code{signal-condition}.
+
+@item Resignal a condition.
+By doing some processing and calling @code{signal-condition} with either
+the same condition or a newly created one. In order to support this,
+@code{signal-condition} runs @var{handler} in such a way that a
+subsequent call to @code{signal-condition} sees only the handlers that
+were established prior to this one.
+
+@item Invoke a restart.
+@findex abort
+@findex continue
+@findex muffle-warning
+@findex retry
+@findex store-value
+@findex use-value
+@findex find-restart
+@findex invoke-restart
+@findex invoke-restart-interactively
+The condition may include one or more restarts established before it was
+signalled. The @var{handler} can invoke these restarts using the
+standard protocols (implemented by @code{abort}, @code{continue},
+@code{muffle-warning}, @code{retry}, @code{store-value}, and
+@code{use-value}), or use private protocols through the use of
+@code{find-restart}, @code{invoke-restart}, and
+@code{invoke-restart-interactively}.
+@end table
+
+@cindex REP loop
+@findex break-on-signals
+As an aid to debugging condition handlers, Scheme maintains a set of
+condition types that will cause an interactive breakpoint to occur prior
+to normal condition signalling. That is, @code{signal-condition}
+creates a new @sc{repl} prior to its normal operation when its argument
+is a condition that is a specialization of any of these types. The
+procedure @code{break-on-signals} establishes this set of condition
+types.
+
+@deffn {procedure+} bind-condition-handler condition-types handler thunk
+@findex signal-condition
+Invokes @var{thunk} after adding @var{handler} as a condition handler
+for the conditions specified by @var{condition-types}.
+@var{Condition-types} must be a list of condition types, and signalling
+a condition whose type is a specialization of any of these types will
+cause the @var{handler} to be invoked. See @code{signal-condition} for
+a description of the mechanism used to invoke handlers.
+
+By special extension, if @var{condition-types} is the empty list then
+the @var{handler} is called for all conditions.
+@end deffn
+
+@deffn {procedure+} bind-default-condition-handler condition-types handler
+@findex signal-condition
+Installs @var{handler} as a (permanent) condition handler for the
+conditions specified by @var{condition-types}. @var{Condition-types}
+must be a list of condition types, and signalling a condition whose type
+is a specialization of any of these types will cause the @var{handler}
+to be invoked. See @code{signal-condition} for a description of the
+mechanism used to invoke handlers.
+
+By special extension, if @var{condition-types} is the empty list then
+the @var{handler} is called for all conditions.
+@end deffn
+
+@deffn {procedure+} break-on-signals condition-types
+@findex signal-condition
+@cindex REP loop
+Arranges for @code{signal-condition} to create an interactive @sc{repl}
+before it signals a condition that is a specialization of any of the
+types in the list of @var{condition-types}. This can be extremely
+helpful when trying to debug code that uses custom condition handlers.
+In order to create a @sc{repl} when @emph{any} condition type is
+signalled it is best to actually put a breakpoint on entry to
+@code{signal-condition}.
+@end deffn
+
+@deffn {procedure+} ignore-errors thunk
+@findex error
+@vindex condition-type:error
+Execute @var{thunk} with a condition handler that intercepts the
+signalling of any specialization of @code{condition-type:error}
+(including those produced by calls to @code{error}) and immediately
+terminates the execution of @var{thunk} and returns from the call to
+@code{ignore-errors} with the signalled condition as its value. If
+@var{thunk} returns normally, its value is returned from
+@code{ignore-errors}.
+
+Notice that @code{ignore-errors} does not ``turn off signalling'' or
+condition handling. Condition handling takes place in the normal manner
+but conditions specialized from @code{condition-type:error} are trapped
+rather than propogated as they would be by default.
+@end deffn
+
+@deffn {procedure+} standard-error-handler condition
+@findex error
+@findex ignore-error
+@vindex standard-error-hook
+@cindex REP loop
+This is the procedure called internally by @code{error} after it calls
+@code{signal-condition}. It normally creates creates a new @sc{repl}
+with the prompt @code{"error>"} (but see @code{standard-error-hook}).
+In order to simulate the effect of calling @code{error}, code may call
+@code{signal-condition} directly and then call
+@code{standard-error-handler} if @code{signal-condition} returns.
+@end deffn
+
+@defvr {variable+} standard-error-hook
+@findex standard-error-handler
+@cindex fluid binding
+@cindex dynamic binding
+@cindex REP loop
+This variable controls the behavior of the procedure
+@code{standard-error-handler}, and hence @code{error}. It is intended
+to be bound with @code{fluid-let} and is normally @code{#f}. It may be
+changed to a procedure of one argument and will then be invoked (with
+@code{standard-error-hook} rebound to @code{#f}) by
+@code{standard-error-handler} just prior to starting the error
+@sc{repl}. It is passed one argument, the condition being signalled.
+@end defvr
+
+@deffn {procedure+} standard-warning-handler condition
+@vindex standard-warning-hook
+@findex signal-condition
+@findex notification-output-port
+@findex write-condition-report
+This is the procedure called internally by @code{warn} after it calls
+@code{signal-condition}. The normal behavior of
+@code{standard-warning-handler} is to print a message (but see
+@code{standard-warning-hook}). More precisely, the message is printed
+to the port returned by @code{notification-output-port}. The message is
+formed by first printing the string @code{"Warning: "} to this port, and
+then calling @code{write-condition-report} on @var{condition} and the port.
+
+@findex muffle-warning
+In order to simulate the effect of calling @code{warn}, code may call
+@code{signal-condition} directly and then call
+@code{standard-warning-handler} if @code{signal-condition} returns.
+(This is not sufficient to implement the @code{muffle-warning} protocol,
+however. For that purpose an explicit restart must be provided.)
+@end deffn
+
+@defvr {variable+} standard-warning-hook
+@findex standard-warning-handler
+@cindex fluid binding
+@cindex dynamic binding
+This variable controls the behavior of the procedure
+@code{standard-warning-handler}, and hence @code{warn}. It is intended
+to be bound with @code{fluid-let} and is normally @code{#f}. It may be
+changed to a procedure of one argument and will then be invoked (with
+@code{standard-warning-hook} rebound to @code{#f}) by
+@code{standard-warning-handler} in lieu of writing the warning message.
+It is passed one argument, the condition being signalled.
+@end defvr
+
+@node Restarts, Error Messages, Condition Handling, Error System
+@section Restarts
+
+@cindex restart effector (defn)
+@cindex effector, restart (defn)
+@cindex restart (defn)
+@findex with-restart
+@findex with-simple-restart
+The Scheme error system provides a mechanism, known as @dfn{restarts},
+that helps coordinate condition-signalling code with condition-handling
+code. A module of code that detects and signals conditions can provide
+procedures (using @code{with-simple-restart} or @code{with-restart}) to
+be invoked by handlers that wish to continue, abort, or restart the
+computation. These procedures, called @dfn{restart effectors}, are
+encapsulated in restart objects.
+
+@findex find-restart
+@findex invoke-restart
+@findex invoke-restart-interactively
+When a condition object is created, it contains a set of restart
+objects, each of which contains a restart effector. Condition handlers
+can inspect the condition they are handling (using @code{find-restart}
+to find restarts by name, or @code{condition/restarts} to see the entire
+set), and they can invoke the associated effectors (using
+@code{invoke-restart} or @code{invoke-restart-interactively}).
+Effectors can take arguments, and these may be computed directly by the
+condition handling code or by gathering them interactively from the
+user.
+
+@findex abort
+@findex continue
+@findex muffle-warning
+@findex retry
+@findex store-value
+@findex use-value
+@cindex protocol, restart (defn)
+@cindex restart protocol
+The names of restarts can be chosen arbitrarily, but the choice of name
+is significant. These names are used to coordinate between the
+signalling code (which supplies names for restarts) and the handling
+code (which typically chooses a restart effector by the name of its
+restart). Thus, the names specify the @dfn{restart protocol}
+implemented by the signalling code and invoked by the handling code.
+The protocol indicates the number of arguments required by the effector
+code as well as the semantics of the arguments.
+
+Scheme provides a conventional set of names (hence, protocols) for
+common use. By choosing the names of restarts from this set, signalling
+code can indicate that it is able to perform a small set of fairly
+common actions (@code{abort}, @code{continue}, @code{muffle-warning},
+@code{retry}, @code{store-value}, @code{use-value}). In turn, simple
+condition handling code can look for the kind of action it wishes to
+perform and simply invoke it by name. All of Scheme's conventional
+names are symbols, although in general restart names are not restricted
+to any particular data type. In addition, the object @code{#f} is
+reserved to indicate the ``not for automated use'' protocol: these
+restarts should be activated only under human control.
+
+@findex with-simple-restart
+Restarts themselves are first-class objects. They encapsulate their
+name, a procedure (known as the @var{effector}) to be executed if they
+are invoked, and a thunk (known as the @var{reporter}) that can be
+invoked to display a description of the restart (used, for example, by
+the interactive debugger). Invoking a restart is an indication that a
+handler has chosen to accept control for a condition, and the handler
+should not return (since this would indicate that the handler declined
+to handle the condition). Thus, the @var{effector} should call a
+continuation captured before the condition signalling process began.
+The most common pattern of usage by signalling code is encapsulated in
+@code{with-simple-restart}.
+
+@menu
+* Establishing Restart Code::
+* Invoking Standard Restart Code::
+* Finding and Invoking General Restart Code::
+* The Named Restart Abstraction::
+@end menu
+
+@node Establishing Restart Code, Invoking Standard Restart Code, , Restarts
+@subsection Establishing Restart Code
+
+@deffn {procedure+} with-simple-restart name reporter thunk
+Invokes @var{thunk} in a dynamic environment created by adding a restart
+named @var{name} to the existing named restarts. @var{Reporter} may be
+used during the execution of @var{thunk} to produce a description of the
+newly created restart; it must either be a procedure of one argument (a
+port) or a string. By convention, the description generated by
+@var{reporter} should be a short complete sentence, with first word
+capitalized and terminated by a period. The sentence should fit on one
+line with a little room to spare (see the examples below); usually this
+means that the sentence should be 70 characters or less in length.
+
+If the restart created by @code{with-simple-restart} is invoked it
+simply aborts the computation in progress by returning an unspecified
+value from the call to @code{with-simple-restart}. Otherwise
+@code{with-simple-restart} returns the value computed by @var{thunk}.
+
+@example
+@group
+(with-simple-restart 'george "This restart is named george."
+ (lambda () 3)) @result{} 3
+
+(with-simple-restart 'george "This restart is named george."
+ (lambda ()
+ (invoke-restart (find-restart 'george)))) @result{} @code{unspecific}
+
+(with-simple-restart 'george "This restart is named george."
+ (lambda () (car 3)))
+
+;The object 3, passed as the first argument to car, is not the correct type.
+;To continue, call RESTART with an option number:
+; (RESTART 3) => Specify an argument to use in its place.
+; (RESTART 2) => This restart is named george.
+; (RESTART 1) => Return to read-eval-print level 1.
+@end group
+@end example
+@end deffn
+
+@deffn {procedure+} with-restart name reporter effector interactor thunk
+@findex invoke-restart
+Invokes @var{thunk} in a dynamic environment created by adding a restart
+named @var{name} to the existing named restarts. @var{Reporter} may be
+used during the execution of @var{thunk} to produce a description of the
+newly created restart; it must either be a procedure of one argument (a
+port) or a string. @var{Effector} is a procedure which will be called
+when the restart is invoked by @code{invoke-restart}. @var{Interactor}
+specifies the arguments that are to be passed to @var{effector} when it
+is invoked interactively; it may be either a procedure of no arguments,
+or @code{#f}. If @var{interactor} is @code{#f}, this restart is not
+meant to be invoked interactively.
+
+The value returned by @code{with-restart} is the value returned by
+@var{thunk}. Should the restart be invoked by a condition handler,
+however, the @var{effector} will not return back to the handler that
+invoked it. Instead, the @var{effector} should call a continuation
+created before the condition signalling process began, and
+@code{with-restart} will therefore not return in the normal manner.
+
+@example
+@group
+(define (by-george! thunk)
+ @r{; This code handles conditions that arise while executing @var{thunk}}
+ @r{; by invoking the GEORGE restart, passing 1 and 2 to the restart's}
+ @r{; @var{effector} code.}
+ (bind-condition-handler '() ; All conditions
+ (lambda (condition)
+ (invoke-restart (find-restart 'george) 1 2))
+ thunk))
+@end group
+
+@group
+(define (can-george! thunk)
+ @r{; This code provides a way of handling errors: the GEORGE restart.}
+ @r{; In order to GEORGE you must supply two values.}
+ (lambda ()
+ (call-with-current-continuation
+ (lambda (kappa)
+ (with-restart
+ 'george @r{; Name}
+ "This restart is named george." @r{; Reporter}
+ (lambda (a b) @r{; Effector}
+ (kappa (list 'george a b)))
+ values @r{; Interactor}
+ thunk))))) @r{; Thunk}
+@end group
+
+@group
+(by-george! (can-george! (lambda () -3)) @result{} -3
+(by-george! (can-george! (lambda () (car 'x)))) @result{} (george 1 2)
+@end group
+@end example
+@end deffn
+
+@node Invoking Standard Restart Code, Finding and Invoking General Restart Code, Establishing Restart Code, Restarts
+@subsection Invoking Standard Restart Code
+
+@cindex bound-restarts
+Scheme supports six standard protocols for handling conditions, each
+encapsulated using a named restart (for use by signalling code) and a
+simple procedure (for use by signal handling code). All of the
+procedures described here take an optional argument, @var{restarts}.
+When present, it must be either the symbol @code{bound-restarts}
+(indicating all of the currently active restarts), a condition
+(indicating the restarts present in that condition), or an explicit list
+of restarts. If omitted, it is assumed to be @code{bound-restarts}.
+Unless otherwise specified, each of these procedures returns an
+unspecified value if the corresponding named restart is not present in
+@var{restarts}.
+
+@deffn {procedure+} abort [restarts]
+@cindex REP loop
+Abort the computation, using the restart named @code{abort}. The
+corresponding effector takes no arguments and abandons the current line
+of computation. This is the restart provided by Scheme's @sc{repl}.
+
+@vindex condition-type:no-such-restart
+If there is no restart named @code{abort}, this procedure signals an
+error of type @code{condition-type:no-such-restart}.
+@end deffn
+
+@deffn {procedure+} continue [restarts]
+Continue the current computation, using the restart named
+@code{continue}. The corresponding effector takes no arguments and
+continues the computation beyond the point at which the condition was
+signalled.
+@end deffn
+
+@deffn {procedure+} muffle-warning [restarts]
+@findex warn
+Continue the current computation, using the restart named
+@code{muffle-warning}. The corresponding effector takes no arguments
+and continues the computation beyond the point at which any warning
+message resulting from the condition would be presented to the user.
+The procedure @code{warn} establishes a @code{muffle-warning} restart
+for this purpose.
+
+@vindex condition-type:no-such-restart
+If there is no restart named @code{muffle-warning}, this procedure
+signals an error of type @code{condition-type:no-such-restart}.
+@end deffn
+
+@deffn {procedure+} retry [restarts]
+Retry the current computation, using the restart named @code{retry}.
+The corresponding effector takes no arguments and simply retries the
+same computation that triggered the condition. The condition may
+reoccur, of course, if the root cause has not been eliminated. The code
+that signals a ``file does not exist'' error can be expected to supply a
+@code{retry} restart. The restart would be invoked after first creating
+the missing file, since the computation is then likely to succeed if it
+is simply retried.
+@end deffn
+
+@deffn {procedure+} store-value new-value [restarts]
+Retry the current computation, using the restart named
+@code{store-value}, after first storing @var{new-value}. The
+corresponding effector takes one argument, @var{new-value}, and stores
+it away in a restart-dependent location, then retries the same
+computation that triggered the condition. The condition may reoccur, of
+course, if the root cause has not been eliminated. The code that
+signals an ``unassigned variable'' error can be expected to supply a
+@code{store-value} restart; this would store the value in the variable
+and continue the computation.
+@end deffn
+
+@deffn {procedure+} use-value new-value [restarts]
+@findex retry
+@findex store-value
+Retry the current computation, using the restart named @code{use-value},
+but substituting @var{new-value} for a value that previously caused a
+failure. The corresponding effector takes one argument,
+@var{new-value}, and retries the same computation that triggered the
+condition with the new value substituted for the failing value. The
+condition may reoccur, of course, if the new value also induces the
+condition.
+
+The code that signals an ``unassigned variable'' error can be expected
+to supply a @code{use-value} restart; this would simply continue the
+computation with @var{new-value} instead of the value of the variable.
+Contrast this with the @code{retry} and @code{store-value} restarts. If
+the @code{retry} restart is used it will fail because the variable still
+has no value. The @code{start-value} restart could be used, but it
+would alter the value of the variable, so that future references to the
+variable would not be detected.
+@end deffn
+
+@node Finding and Invoking General Restart Code, The Named Restart Abstraction, Invoking Standard Restart Code, Restarts
+@subsection Finding and Invoking General Restart Code
+
+@findex with-restart
+@findex with-simple-restart
+@findex bound-restart
+@findex find-restart
+@findex invoke-restart
+@findex invoke-restart-interactively
+Restarts are a general mechanism for establishing a protocol between
+condition signalling and condition handling code. The Scheme error
+system provides ``packaging'' for a number of common protocols. It also
+provides lower-level hooks that are intended for implementing customized
+protocols. The mechanism used by signalling code (@code{with-restart}
+and @code{with-simple-restart}) is used for both purposes.
+
+Five additional operations are provided for the use of condition
+handling code. Two operations (@code{bound-restarts} and
+@code{find-restart}) allow condition handling code to locate active
+restarts. The other two operations (@code{invoke-restart} and
+@code{invoke-restart-interactively}) allow restart effectors to be
+invoked once the restart object has been located.
+
+In addition, there is a data abstraction that provides access to the
+information encapsulated in restart objects.
+
+@deffn {procedure+} bound-restarts
+Returns a list of all currently active restart objects, most recently
+installed first. @code{bound-restarts} should be used with caution by
+condition handling code, since it reveals all restarts that are active
+at the time it is called, rather than at the time the condition was
+signalled. It is useful, however, for collecting the list of calls for
+inclusion in newly generated condition objects or for inspecting the
+current state of the system.
+@end deffn
+
+@deffn {procedure+} find-restart name [restarts]
+Returns the first restart object named @var{name} in the list of
+@var{restarts}. When present, @var{restarts} must be either the symbol
+@code{bound-restarts} (indicating all of the currently active restarts),
+a condition (indicating the restarts present in that condition), or an
+explicit list of restarts. If omitted, it is assumed to be
+@code{bound-restarts}.
+
+When used in a condition handler, @code{find-restart} is usually passed
+the name of a particular restart @emph{and} the condition object that
+has been signalled. In this way the handler finds only restarts that
+were available when the condition was created (usually the same as when
+it was signalled). If @var{restarts} is omitted, the currently active
+restarts would be used, and these often includes restarts added after
+the condition ocurred.
+@end deffn
+
+@deffn {procedure+} invoke-restart restart argument...
+@findex invoke-restart-interactively
+Calls the restart effector encapsulated in @var{restart}, passing the
+specified @var{argument}s to it. @code{invoke-restart} is intended for
+use by condition handling code that understands the protocol implemented
+by @var{restart}, and can therefore calculate and pass an appropriate
+set of arguments.
+
+If a condition handler needs to interact with a user to gather the
+arguments for an effector (e.g.@: if it does not understand the protocol
+implemented by @var{restart}) @code{invoke-restart-interactively} should
+be used instead of @code{invoke-restart}.
+@end deffn
+
+@deffn {procedure+} invoke-restart-interactively restart
+First calls the @code{interactor} associated with @var{restart} to
+interactively gather the (multiple) values needed for @var{restart}'s
+effector. It then calls the restart effector encapsulated in
+@var{restart}, passing these values to it as arguments.
+
+@findex restart/interactor
+@code{invoke-restart-interactively} is intended for calling interactive
+restarts (those for which @code{restart/interactor} is not @code{#f}).
+For convenience, @code{invoke-restart-interactively} will call the
+restart's effector with no arguments if the restart has no interactor;
+this behavior may change in the future.
+@end deffn
+
+@node The Named Restart Abstraction, , Finding and Invoking General Restart Code, Restarts
+@subsection The Named Restart Abstraction
+
+A restart object is very simple, since it encapsulates only a name,
+effector, interactor, and description.
+
+@deffn {procedure+} restart/effector restart
+@findex invoke-restart
+@findex invoke-restart-interactively
+Returns the effector encapsulated in @var{restart}. Normally this
+procedure is not used since @code{invoke-restart} and
+@code{invoke-restart-interactively} capture the most common invocation
+patterns.
+@end deffn
+
+@deffn {procedure+} restart/interactor restart
+@findex invoke-restart-interactively
+Returns the interactor encapsulated in @var{restart}. This is either a
+procedure of no arguments or the object @code{#f}. Normally this
+procedure is not used since @code{invoke-restart-interactively} captures
+the most common usage. Thus @code{restart/interactor} is most useful as
+a predicate to determine if @var{restart} is intended to be invoked
+interactively.
+@end deffn
+
+@deffn {procedure+} restart/name restart
+@findex eq?
+Returns the name of @var{restart}. While the Scheme error system uses
+only symbols and the object @code{#f} for its predefined names, programs
+may use arbitrary objects (name equivalence is tested using @code{eq?}).
+@end deffn
+
+@deffn {procedure+} restart? object
+Returns @code{#f} if and only if @var{object} is not a restart.
+@end deffn
+
+@deffn {procedure+} write-restart-report restart port
+Writes a description of @var{restart} to @var{port}. This works by
+either displaying (if it is a string) or calling (if it is a procedure)
+the @var{reporter} that was supplied when the restart was created.
+@end deffn
+
+@node Error Messages, Taxonomy, Restarts, Error System
+@section Error Messages
+
+The error system provides a simple formatting language that allows the
+programmer to have some control over the printing of error messages. The
+basic idea is as follows.
+
+@findex display
+@findex write
+Error messages typically consist of a string describing the error,
+followed by some irritant objects. The string is printed using
+@code{display}, and the irritants are printed using @code{write},
+typically with a space between each irritant. To allow simple
+formatting, we introduce a @dfn{noise} object, printed using
+@code{display}. The irritant list may contain ordinary objects
+interspersed with noise objects. Each noise object is printed using
+@code{display}, with no extra whitespace, while each normal object is
+printed using @code{write}, prefixed by a single space character.
+
+Here is an example:
+
+@example
+@group
+(define (error-within-procedure message irritant procedure)
+ (error message
+ irritant
+ (error-irritant/noise #\newline)
+ (error-irritant/noise "within procedure")
+ procedure))
+@end group
+@end example
+
+@noindent
+This would format as follows:
+
+@example
+@group
+(error-within-procedure "bad widget" 'widget-32 'invert-widget) @error{}
+
+bad widget widget-32
+within procedure invert-widget
+@end group
+@end example
+
+@noindent
+Note the use of a separate noise object for the newline. In general, for
+characters such as newline or formfeed (i.e.@: non-graphic characters), this
+is desirable since it makes it easier for the formatter to notice
+formatting characters with special meanings and handle them specially
+should it be necessary.
+
+Here are the operations supporting error messages:
+
+@deffn {procedure+} format-error-message message irritants port
+@var{Message} is typically a string (although this is not required),
+@var{irritants} a list of irritant objects, and @var{port} an output
+port. Formats @var{message} and @var{irritants} to @var{port} in the
+standard way. Note that, during the formatting process, the depth and
+breadth to which lists are printed are each limited to small numbers, to
+guarantee that the output from each irritant is not arbitrarily large.
+@end deffn
+
+@deffn {procedure+} error-irritant/noise value
+Creates and returns a noise object whose value is @var{value}.
+@end deffn
+
+@node Taxonomy, , Error Messages, Error System
+@section Condition-Type Taxonomy
+
+The MIT Scheme error system provides a rich set of predefined condition
+types. These are organized into a forest through taxonomic links
+providing the relationships for @var{specializes} and @var{generalizes}.
+The chart appearing below shows these relationships by indenting all the
+specializations of a given type relative to the type. Note that the
+variables that are bound to these condition types are prefixed by
+@samp{condition-type:}; for example, the type appearing in the following
+table as @samp{simple-error} is stored in the variable
+@code{condition-type:simple-error}. Users are encouraged to add new
+condition types by creating specializations of existing ones.
+
+Following the chart are detailed descriptions of the predefined
+condition types. Some of these types are marked as @dfn{abstract}
+types. Abstract types are not intended to be used directly as the type
+of a condition; they are to be used as generalizations of other types,
+and for binding condition handlers. Types that are not marked as
+abstract are @dfn{concrete}; they are intended to be explicitly used as
+a condition's type.
+
+@page
+@example
+@group
+warning
+ simple-warning
+simple-condition
+serious-condition
+ error
+ simple-error
+ illegal-datum
+ wrong-type-datum
+ wrong-type-argument
+ wrong-number-of-arguments
+ datum-out-of-range
+ bad-range-argument
+ inapplicable-object
+ control-error
+ no-such-restart
+ port-error
+ derived-port-error
+ file-error
+ file-operation-error
+ derived-file-error
+ variable-error
+ unbound-variable
+ unassigned-variable
+ unlinkable-variable
+ arithmetic-error
+ divide-by-zero
+ floating-point-overflow
+ floating-point-underflow
+ primitive-procedure-error
+ system-call-error
+ not-loading
+breakpoint
+@end group
+@end example
+
+@deffn {condition type+} condition-type:warning
+This is an abstract type. All warnings should inherit from this type.
+Warnings are a class of conditions that are usually handled by informing
+the user of the condition and proceeding the computation normally.
+@end deffn
+
+@deffn {condition type+} condition-type:simple-warning message irritants
+This is the condition generated by the @code{warn} procedure. The
+fields @var{message} and @var{irritants} are taken directly from the
+arguments to @code{warn}; @var{message} is any object (usually a string)
+and @var{irritants} is a list of objects. The reporter for this type
+uses @code{format-error-message} to generate its output from
+@var{message} and @var{irritants}.
+@end deffn
+
+@deffn {condition type+} condition-type:simple-condition message irritants
+This is an unspecialized condition that does not fall into any of the
+standard condition classes. The @var{message} field is any object
+(usually a string) and @var{irritants} is a list of objects. The
+reporter for this type uses @code{format-error-message} to generate its
+output from @var{message} and @var{irritants}.
+@end deffn
+
+@deffn {condition type+} condition-type:serious-condition
+This is an abstract type. All serious conditions that require some form
+of intervention should inherit from this type. In particular, all
+errors inherit from this type.
+@end deffn
+
+@deffn {condition type+} condition-type:error
+This is an abstract type. All errors should inherit from this type.
+@end deffn
+
+@deffn {condition type+} condition-type:simple-error message irritants
+This is the condition generate by the @code{error} procedure when its
+first argument is not a condition or condition type. The fields
+@var{message} and @var{irritants} are taken directly from the arguments
+to @code{error}; @var{message} is any object (usually a string) and
+@var{irritants} is a list of objects. The reporter for this type uses
+@code{format-error-message} to generate its output from @var{message}
+and @var{irritants}.
+@end deffn
+
+@deffn {condition type+} condition-type:illegal-datum datum
+This is an abstract type. This type indicates the class of errors in
+which a program discovers a particular object that lacks specific
+required properties. Most commonly, the object is of the wrong type or
+is outside a specific range. The @var{datum} field is the offending
+object.
+@end deffn
+
+@deffn {condition type+} condition-type:wrong-type-datum datum type
+This type indicates the class of errors in which a program discovers a
+particular object that is of the wrong type. The @var{type} field is a
+string describing the type that was expected, and the @var{datum} field
+is the object that is of the wrong type.
+@end deffn
+
+@deffn {procedure+} error:wrong-type-datum datum type
+This procedure signals a condition of type
+@code{condition-type:wrong-type-datum}. The @var{datum} and @var{type}
+fields of the condition are filled in from the corresponding arguments
+to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:wrong-type-argument datum type operator operand
+This type indicates that a procedure was passed an argument of the wrong
+type. The @var{operator} field is the procedure (or a symbol naming the
+procedure), the @var{operand} field indicates which argument position
+was involved (this field is either a symbol, a non-negative integer, or
+@code{#f}), the @var{type} field is a string describing the type that
+was expected, and the @var{datum} field is the offending argument.
+@end deffn
+
+@deffn {procedure+} error:wrong-type-argument datum type operator
+This procedure signals a condition of type
+@code{condition-type:wrong-type-argument}. The @var{datum}, @var{type}
+and @var{operator} fields of the condition are filled in from the
+corresponding arguments to the procedure; the @var{operand} field of the
+condition is set to @code{#f}.
+@end deffn
+
+@deffn {condition type+} condition-type:datum-out-of-range datum
+This type indicates the class of errors in which a program discovers a
+particular object that is of the correct type but is otherwise out of
+range. Most often, this type indicates that an index to some data
+structure is outside of the range of indices for that structure. The
+@var{datum} field is the offending object.
+@end deffn
+
+@deffn {procedure+} error:datum-out-of-range datum
+This procedure signals a condition of type
+@code{condition-type:datum-out-of-range}. The @var{datum} field of the
+condition is filled in from the corresponding argument to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:bad-range-argument datum operator operand
+This type indicates that a procedure was passed an argument that was of
+the correct type but is otherwise out of range. Most often, this type
+indicates that an index to some data structure is outside of the range
+of indices for that structure. The @var{operator} field is the
+procedure (or a symbol naming the procedure), the @var{operand} field
+indicates which argument position was involved (this field is either a
+symbol, a non-negative integer, or @code{#f}), and the @var{datum} field
+is the offending argument.
+@end deffn
+
+@deffn {procedure+} error:bad-range-argument datum operator
+This procedure signals a condition of type
+@code{condition-type:bad-range-argument}. The @var{datum} and
+@var{operator} fields of the condition are filled in from the
+corresponding arguments to the procedure; the @var{operand} field of the
+condition is set to @code{#f}.
+@end deffn
+
+@deffn {condition type+} condition-type:wrong-number-of-arguments datum type operands
+This type indicates that a procedure was called with the wrong number of
+arguments. The @var{datum} field contains the procedure being called,
+the @var{type} field contains the number of arguments that the procedure
+expects, and the @var{operands} field contains a list of the arguments
+that were passed to the procedure.
+@end deffn
+
+@deffn {procedure+} error:wrong-number-of-arguments datum type operands
+This procedure signals a condition of type
+@code{condition-type:wrong-number-of-arguments}. The @var{datum},
+@var{type} and @var{operands} fields of the condition are filled in from
+the corresponding arguments to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:inapplicable-object datum operands
+This type indicates an error in which a program attempted to apply an
+object that is not a procedure. The object being applied is saved in
+the @var{datum} field, and the arguments being passed to the object are
+saved as a list in the @var{operands} field.
+@end deffn
+
+@deffn {condition type+} condition-type:control-error
+This is an abstract type. It describes a class of errors relating to
+program control flow.
+@end deffn
+
+@deffn {condition type+} condition-type:no-such-restart name
+This type indicates that a particular named restart was not active when
+it was expected to be. Conditions of this type are signalled by several
+procedures that look for particular named restarts, for example
+@code{muffle-warning}. The @var{name} field contains the name that was
+being searched for.
+@end deffn
+
+@deffn {procedure+} error:no-such-restart name
+This procedure signals a condition of type
+@code{condition-type:no-such-restart}. The @var{name} field of the
+condition is filled in from the corresponding argument to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:port-error port
+This is an abstract type. It indicates that an error associated with a
+particular I/O port has occurred. For example, writing output to a file
+port can signal an error if the disk containing the file is full; that
+error would be signalled as a port error. The @var{port} field contains
+the associated port.
+@end deffn
+
+@deffn {condition type+} condition-type:derived-port-error port condition
+This is the concrete type that is signalled when port errors occur. The
+@var{port} field contains the port associated with the error, and the
+@var{condition} field contains a condition object that describes the
+error in more detail. Usually the @var{condition} field contains a
+condition of type @code{condition-type:system-call-error}.
+@end deffn
+
+@deffn {procedure+} error:derived-port-error port condition
+This procedure signals a condition of type
+@code{condition-type:derived-port-error}. The @var{port} and
+@var{condition} fields of the condition are filled in from the
+corresponding arguments to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:file-error filename
+This is an abstract type. It indicates that an error associated with a
+particular file has occurred. For example, attempting to delete a
+nonexistent file will signal an error. The @var{filename} field
+contains a filename or pathname associated with the operation that failed.
+@end deffn
+
+@deffn {condition type+} condition-type:file-operation-error filename verb noun reason operator operands
+This is the most common condition type for file system errors. The
+@var{filename} field contains the filename or pathname that was being
+operated on. The @var{verb} field contains a string which is the verb
+or verb phrase describing the operation being performed, and the
+@var{noun} field contains a string which is a noun or noun phrase
+describing the object being operated on. The @var{reason} field
+contains a string describing the error that occurred. The
+@var{operator} field contains the procedure performing the operation (or
+a symbol naming that procedure), and the @var{operands} field contains a
+list of the arguments that were passed to that procedure. For example,
+an attempt to delete a nonexistent file would have the following field
+values:
+
+@example
+@group
+filename "/zu/cph/tmp/no-such-file"
+verb "delete"
+noun "file"
+reason "no such file or directory"
+operator file-remove
+operands ("/zu/cph/tmp/no-such-file")
+@end group
+@end example
+@end deffn
+
+@deffn {procedure+} error:file-operation-error filename verb noun reason operator operands
+This procedure signals a condition of type
+@code{condition-type:file-operation-error}. The fields of the condition
+are filled in from the corresponding arguments to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:derived-file-error filename condition
+This is another kind of file error, which is generated by obscure
+file-system errors that do not fit into the standard categories. The
+@var{filename} field contains the filename or pathname that was being
+operated on, and the @var{condition} field contains a condition
+describing the error in more detail. Usually the @var{condition} field
+contains a condition of type @code{condition-type:system-call-error}.
+@end deffn
+
+@deffn {procedure+} error:derived-file-error filename condition
+This procedure signals a condition of type
+@code{condition-type:derived-file-error}. The @var{filename} and
+@var{condition} fields of the condition are filled in from the
+corresponding arguments to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:variable-error location environment
+This is an abstract type. It indicates that an error associated with a
+particular variable has occurred. The @var{location} field contains the
+name of the variable, and the @var{environment} field contains the
+environment in which the variable was referenced.
+@end deffn
+
+@deffn {condition type+} condition-type:unbound-variable location environment
+This type is generated when a program attempts to access or modify a
+variable that is not bound. The @var{location} field contains the name
+of the variable, and the @var{environment} field contains the
+environment in which the reference occurred.
+@end deffn
+
+@deffn {condition type+} condition-type:unassigned-variable location environment
+This type is generated when a program attempts to access a variable that
+is not assigned. The @var{location} field contains the name of the
+variable, and the @var{environment} field contains the environment in
+which the reference occurred.
+@end deffn
+
+@deffn {condition type+} condition-type:arithmetic-error operator operands
+This is an abstract type. It indicates that a numerical operation was
+unable to complete because of an arithmetic error. (For example,
+division by zero.) The @var{operator} field contains the procedure that
+implements the operation (or a symbol naming the procedure), and the
+@var{operands} field contains a list of the arguments that were passed
+to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:divide-by-zero operator operands
+This type is generated when a program attempts to divide by zero. The
+@var{operator} field contains the procedure that implements the
+operation (or a symbol naming the procedure), and the @var{operands}
+field contains a list of the arguments that were passed to the
+procedure.
+@end deffn
+
+@deffn {procedure+} error:divide-by-zero operator operands
+This procedure signals a condition of type
+@code{condition-type:divide-by-zero}. The @var{operator} and
+@var{operands} fields of the condition are filled in from the
+corresponding arguments to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:floating-point-overflow operator operands
+This type is generated when a program performs an arithmetic operation
+that results in a floating-point overflow. The @var{operator} field
+contains the procedure that implements the operation (or a symbol naming
+the procedure), and the @var{operands} field contains a list of the
+arguments that were passed to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:floating-point-underflow operator operands
+This type is generated when a program performs an arithmetic operation
+that results in a floating-point underflow. The @var{operator} field
+contains the procedure that implements the operation (or a symbol naming
+the procedure), and the @var{operands} field contains a list of the
+arguments that were passed to the procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:primitive-procedure-error operator operands
+This is an abstract type. It indicates that an error was generated by a
+primitive procedure call. Primitive procedures are distinguished from
+ordinary procedures in that they are not written in Scheme but instead
+in the underlying language of the Scheme implementation. The
+@var{operator} field contains the procedure that implements the
+operation (or a symbol naming the procedure), and the @var{operands}
+field contains a list of the arguments that were passed to the
+procedure.
+@end deffn
+
+@deffn {condition type+} condition-type:system-call-error operator operands system-call error-type
+This is the most common condition type generated by primitive
+procedures. A condition of this type indicates that the primitive made
+a system call to the operating system, and that the system call
+signalled an error. The system-call error is reflected back to Scheme
+as a condition of this type, except that many common system-call errors
+are automatically translated by the Scheme implementation into more
+useful forms; for example, a system-call error that occurs while trying
+to delete a file will be translated into a condition of type
+@code{condition-type:file-operation-error}. The @var{operator} field
+contains the procedure that implements the operation (or a symbol naming
+the procedure), and the @var{operands} field contains a list of the
+arguments that were passed to the procedure. The @var{system-call} and
+@var{error-type} fields contain symbols that describe the specific
+system call that was being made and the error that occurred,
+respectively; these symbols are completely operating-system dependent.
+@end deffn
+
+@deffn {condition type+} condition-type:not-loading
+A condition of this type is generated when the procedure
+@code{current-load-pathname} is called from somewhere other than inside
+a file being loaded.
+@end deffn
+
+@deffn {condition type+} condition-type:breakpoint environment message prompt
+A condition of this type is generated by the breakpoint mechanism. The
+contents of its fields are beyond the scope of this document.
+@end deffn
@node Graphics, Win32 Package Reference, Error System, Top
@chapter Graphics
projects / mit-scheme.git / commitdiff