From: Chris Hanson Date: Fri, 12 Aug 1994 07:56:47 +0000 (+0000) Subject: Insert new error system documentation. X-Git-Tag: 20090517-FFI~7138 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=b600f98136f736cf7d0a1a5f715559356948c363;p=mit-scheme.git Insert new error system documentation. --- diff --git a/v7/doc/ref-manual/scheme.texinfo b/v7/doc/ref-manual/scheme.texinfo index 85d532a37..0c05f5e95 100644 --- a/v7/doc/ref-manual/scheme.texinfo +++ b/v7/doc/ref-manual/scheme.texinfo @@ -2,7 +2,7 @@ @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 @@ -108,9 +108,9 @@ literature without prior written consent from MIT in each case. @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 @@ -397,6 +397,29 @@ Pathnames * 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:: @@ -13793,7 +13816,1575 @@ version components match those of @var{directory}; @code{wild} or @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