From: Chris Hanson Date: Mon, 6 Dec 1993 20:37:56 +0000 (+0000) Subject: Eliminate contents of error-system chapter. X-Git-Tag: 20090517-FFI~7391 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=20092adcfb9e34d6760dfb14821bf57ec70712ef;p=mit-scheme.git Eliminate contents of error-system chapter. --- diff --git a/v7/doc/ref-manual/scheme.texinfo b/v7/doc/ref-manual/scheme.texinfo index 3f3877edd..6f92d33cd 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.40 1993/12/05 16:17:38 adams Exp $ +@comment $Id: scheme.texinfo,v 1.41 1993/12/06 20:37:56 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.37 alpha -@subtitle for Scheme Release 7.2 -@subtitle 12 November 1993 +@subtitle Edition 1.41 beta +@subtitle for Scheme Release 7.3 +@subtitle 6 December 1993 @author by Chris Hanson @author the MIT Scheme Team @author and a cast of thousands @@ -397,17 +397,6 @@ Pathnames * Operations on Pathnames:: * Miscellaneous Pathnames:: -Error System - -* Simple Errors:: -* Error Handler:: -* Error Messages:: -* Condition Types:: -* Condition Instances:: -* Condition Signalling:: -* Condition Handling:: -* Predefined Errors:: - Graphics * Opening and Closing of Graphics Devices:: @@ -13804,655 +13793,7 @@ version components match those of @var{directory}; @code{wild} or @node Error System, Graphics, File-System Interface, Top @chapter Error System -@findex error -The Scheme error system provides a uniform mechanism for the signalling of -errors and other exceptional conditions. For most purposes, the only part -of the error system that is needed is the special form @code{error}, which -is used to signal simple errors, specifying a message and some irritant -objects (@pxref{Simple Errors}). 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 the specification of 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 kind of behavior that is useful 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''. - -The taxonomy of condition types imposes a partial order on the types, -because each type is allowed to have multiple generalizations. This is -allowed because some condition types can be generalized in several -different ways. An example of this is ``floating-point divide by zero'', -which can be generalized to either a ``floating-point overflow'' or a -``divide by zero''. The latter generalization, ``divide by zero'', cannot -be a specialization of the former, because it can also be signalled by -arithmetic on numbers other than floating-point. - -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 Signalling conditions -Conditions 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 conditions -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 Classification of conditions -Each condition has a type, which is 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 as well as -information that describes the state of the computation from which the -condition arose. -@end table - -@menu -* Simple Errors:: -* Error Handler:: -* Error Messages:: -* Condition Types:: -* Condition Instances:: -* Condition Signalling:: -* Condition Handling:: -* Predefined Errors:: -@end menu - -@node Simple Errors, Error Handler, , Error System -@section Simple Errors - -@cindex irritants, of error (defn) -The simplest error-signalling mechanism is the special form -@code{error}. It allows the programmer to signal errors by specifying -an error message and providing a list of some objects (@dfn{irritants}) -that are relevant to the error. - -@deffn {special form+} error message irritant @dots{} -Signals an error. This special form expands into the following code: - -@example -(error-procedure @var{message} (list @var{irritant} @dots{}) (the-environment)) -@end example - -@noindent -@findex the-environment -The use of @code{the-environment} would normally force the environment -in which it appears to be an interpreter environment. However, the -compiler treats @code{error} expressions specially so that errors signalled -from compiled code do not supply the environment argument to -@code{error-procedure}. -@end deffn - -@deffn {procedure+} error-procedure message irritants environment -Signals an error. @var{Message} is normally a short string that -summarizes the error, and @var{irritants} is a list of objects that -contain interesting information about the error. @var{Environment} is -the environment in which the error occurred. - -Normally, the message and irritants are used to build a condition whose -type is @code{error-type:vanilla}, @var{environment} is attached to that -condition, and then the condition is signalled. However, if -@var{message} is a @code{condition-type} object, then that object is -used (instead of @code{error-type:vanilla}) to build the condition. - -The argument @var{environment} is used by the standard error handler. -Currently there is no mechanism to retrieve this information. -@end deffn - -@defvr {condition type+} error-type:vanilla -This is the error type used by @code{error-procedure} when it signals -anonymous errors. Do not use this type for signalling new errors, as some -of the system code expects to find the message in a special place for -errors of this type. This object is made public solely so that condition -handlers can be bound to it. -@end defvr - -@deffn {procedure+} warn message irritant @dots{} -This procedure takes arguments just like @code{error}, formats and prints a -message in the usual way, but does not signal an exception. The output -goes to the output-port of the nearest @code{cmdl} object. In the future -this may be made customizable in some ways, such as allowing conditional -error signalling based on a flag. -@end deffn - -@node Error Handler, Error Messages, Simple Errors, Error System -@section Error Handler - -@cindex standard error handler -@cindex error handler, standard -In the absence of more specific handling, errors invoke the -@dfn{standard error handler}. This handler normally prints an error -message and enters a new @sc{rep} loop. - -@deffn {procedure+} standard-error-handler condition -This procedure is used to handle error conditions that are not otherwise -taken care of. It can be useful when building custom error -handlers. -@end deffn - -While the standard error handler is executing, the following procedures -provide useful information. - -@deffn {procedure+} error-condition -This procedure returns the condition that was passed to the standard -error handler as its argument. If the standard error handler is not -executing, this procedure returns @code{#f}. -@end deffn - -@deffn {procedure+} error-message -@deffnx {procedure+} error-irritants -@deffnx {procedure+} error-continuation -These procedures extract standard components from @code{(error-condition)}. -@code{error-continuation} returns @code{#f} if @code{error-condition} -does. -@end deffn - -@node Error Messages, Condition Types, Error Handler, 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, which is 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 - -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 - -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} must be a string, @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 - -@deffn {procedure+} error-irritant/noise? object -Returns @code{#t} if @var{object} was created by -@code{error-irritant/noise}; otherwise returns @code{#f}. -@end deffn - -@deffn {procedure+} error-irritant/noise-value noise -Returns the value of the noise object @var{noise}. This is the object that -was passed to @code{error-irritant/noise} as an argument when @var{noise} -was created. -@end deffn - -@deffn {procedure+} error-irritants/sans-noise -@findex error-irritants -This returns the value of @code{error-irritants} with the noise objects -removed. It could have been written: - -@example -@group -(define (error-irritants/sans-noise) - (list-transform-negative (error-irritants) - error-irritant/noise?)) -@end group -@end example -@end deffn - -@node Condition Types, Condition Instances, Error Messages, 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 -inheritance relationships between types. - -Condition types are defined by the following operations. Any argument -called @var{condition-type} is assumed to be a condition type -object. - -@deffn {procedure+} make-condition-type generalizations reporter -This procedure creates and returns a new condition type. -@var{Generalizations} must be a list of condition types; the resulting -condition type will be a specialization of each of these types. -@var{Reporter} is a procedure of two arguments, a condition instance and -an output port, which will write a concise description of the condition -on the output port. As a special option, @var{reporter} may be a -string, in which case a standard error message will be printed using -that string. -@end deffn - -@deffn {procedure+} condition-type? object -@cindex type predicate, for condition type -Returns @code{#t} if @var{object} is a condition type; otherwise returns -@code{#f}. -@end deffn - -@deffn {procedure+} guarantee-condition-type object -Signals an error if @var{object} is not a condition type. Returns -@var{object} as its value otherwise. -@end deffn - -@deffn {procedure+} condition-type/generalizations condition-type -Returns the generalizations of @var{condition-type}. This is the reflexive -and transitive closure of the @var{generalizations} argument to -@code{make-condition-type}, i.e.@: all of the members of -@var{generalizations} plus all of their generalizations as well. This list -always contains @var{condition-type}. -@end deffn - -@deffn {procedure+} condition-type/reporter condition-type -Returns the report procedure for @var{condition-type}. -@end deffn - -@deffn {procedure+} condition-type/properties condition-type -Each condition type contains a 1D table for associating arbitrary -properties with the condition type. This operation returns the table -associated with @var{condition-type}. -@end deffn - -@deffn {procedure+} condition-type/error? condition-type -@cindex error type (defn) -@cindex type, of error (defn) -This predicate is true only of condition types that are considered to be -errors. Condition types satisfying this predicate are treated specially -under certain cirumstances, and are sometimes referred to as @dfn{error -types}. - -The following two expressions are equivalent (as predicates): - -@example -@group -(condition-type/error? x) -(memq condition-type:error (condition-type/generalizations x)) -@end group -@end example -@end deffn - -@defvr {condition type+} condition-type:error -The value of this variable a condition type with no generalizations that -is used to mark condition types as being errors. -@end defvr - -@deffn {procedure+} make-error-type generalizations reporter -@findex make-condition-type -This operation is like @code{make-condition-type}, except that if none of -@var{generalizations} satisfies @code{condition-type/error?}, it adds -@code{condition-type:error} to the set of generalizations. -@end deffn - -@deffn {procedure+} error-type? object -@cindex type predicate, for error type -Returns @code{#t} if @var{object} is a condition type that satisfies -@code{condition-type/error?}; otherwise returns @code{#f}. -@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 when condition handlers want to restart the -computation in some way, or sometimes for analyzing the computation to -learn more about the context in which the condition occurred. - -The following operations define the condition datatype. Any argument -called @var{condition} is assumed to be a condition object. - -@deffn {procedure+} make-condition condition-type irritants continuation -Makes a new condition instance, with a type of @var{condition-type}. -@var{Irritants} is a list of arbitrary objects, and @var{continuation} -must be a continuation, normally the continuation of the computation -which caused the condition. -@end deffn - -@deffn {procedure+} condition? object -@cindex type predicate, for condition instance -Returns true iff @var{object} is a condition instance. -@end deffn - -@deffn {procedure+} error? object -@cindex type predicate, for error instance -@findex condition-type/error? -Returns @code{#t} if @var{object} is a condition instance that satisfies -@code{condition/error?}; otherwise returns @code{#f}. -@end deffn - -@deffn {procedure+} guarantee-condition object -Signals an error if @var{object} is not a condition instance. Returns -@var{object} otherwise. -@end deffn - -@deffn {procedure+} condition/type condition -Returns the condition type associated with @var{condition}. -@end deffn - -@deffn {procedure+} condition/irritants condition -Returns the irritants associated with @var{condition}. -@end deffn - -@deffn {procedure+} condition/continuation condition -Returns the continuation associated with @var{condition}. -@end deffn - -@deffn {procedure+} condition/write-report condition [output-port] -Writes a concise description of @var{condition} to @var{output-port}, -which defaults to the current output port. -@end deffn - -@deffn {procedure+} condition/report-string condition -Returns a newly allocated string that is a concise description of -@var{condition}. -@end deffn - -@deffn {procedure+} condition/properties condition -Each condition instance contains a 1D table for associating arbitrary -properties with the condition. This procedure returns the table -associated with @var{condition}. -@end deffn - -@deffn {procedure+} condition/internal? condition -This predicate is true of certain conditions that normally should not be -handled by user code. Condition handlers that handle ``all'' conditions -should ignore conditions satisfying this predicate, unless the handler's -writer has a good understanding of internal conditions. -@end deffn - -@deffn {procedure+} condition/generalizations condition -@deffnx {procedure+} condition/error? condition -@deffnx {procedure+} condition/reporter condition -These operations access the corresponding components in the type of -@var{condition}. For example, the following expressions are -equivalent: - -@example -(condition/generalizations condition) -(condition-type/generalizations (condition/type condition)) -@end example - -@cindex error condition (defn) -@cindex condition, error (defn) -Note that condition instances satisfying the predicate -@code{condition/error?} are sometimes referred to as @dfn{error -conditions}, or even @dfn{errors}. -@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}, 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. - -There is a single procedure responsible for signalling conditions. All -other signalling mechanisms go through this procedure: - -@deffn {procedure+} signal-condition condition [default-handler] -Signals @var{condition}. @var{Default-handler}, if given, must be a -procedure of one argument. The signalling procedure attempts to find a -handler for the condition, using the following rules: - -@itemize @bullet -@item -The set of condition handlers is searched, until it finds one that will -handle any of the condition types specified by the generalizations of -@var{condition}. Each handler specifies, at the time it is bound, a set of -condition types it will handle; if the intersection of that set and -@var{condition}'s generalizations is not empty, the handler is -selected. -@cindex condition handler -@cindex handler, of condition - -If a handler is found, it is invoked on @var{condition}. If it returns -@code{#f}, that means the handler has declined to handle the condition -and the search continues. Otherwise the handler's value is returned as -the value of @code{signal-condition}. - -@item -If no condition handler is found, and the argument @var{default-handler} is -supplied, it is invoked on @var{condition}; its value is returned as the -value of @code{signal-condition}. - -@item -Otherwise, @code{#f} is returned, indicating that no handler could be -found. -@end itemize -@end deffn - -@deffn {procedure+} signal-error condition -@findex standard-error-handler -Signals @var{condition}, which must be a condition instance. If this -condition is not otherwise handled, the standard error handler is -invoked. Equivalent to @code{(signal-condition @var{condition} -standard-error-handler)}. -@end deffn - -@node Condition Handling, Predefined Errors, Condition Signalling, Error System -@section Condition Handling - -@cindex condition handling (defn) -@cindex handling, of condition (defn) -@dfn{Condition handling} refers to the act of defining the behavior of a -signalled condition. This is controlled by the binding of -@dfn{condition handlers}. - -@cindex condition handler (defn) -@cindex handler, of condition (defn) -@findex signal-condition -A @dfn{condition handler} is a procedure of one argument. When a handler -is invoked by @code{signal-condition}, a condition is supplied to -the handler as its argument. The handler may return a value: if the value -is @code{#f}, this indicates that the handler has decided not to handle -this particular condition. In that case, @code{signal-condition} continues -its search for another handler. Otherwise the value returned by the -handler is returned as the value of @code{signal-condition}. - -@cindex resignalling, of condition (defn) -Often, though, the handler will not return a value. Usually a condition -handler will exit by invoking some continuation. Sometimes it will -signal a different condition instead, or signal the same condition -again. This latter action, @dfn{resignalling} the same condition, is -equivalent to returning @code{#f} from the handler. This is because -when the handler is invoked, the set of condition-handler bindings is -unwound to the point at which the handler was bound. In other words, -when a condition handler is bound, the set of condition handlers that is -in effect at the time of binding is the set that will be in effect when -the handler is invoked. - -@cindex binding, of condition handler (defn) -@cindex condition handler, binding (defn) -A condition handler is @dfn{bound} by specifying that it will handle a -condition whose generalizations intersect a given set of condition types. -Condition handlers are bound using a mechanism very similar to fluid -binding of variables. A condition handler binding has a dynamic extent -rather than a lexical scope, that is, it is effective for a specified time -segment rather than for a specified code segment. - -The order in which the bindings are searched (by @code{signal-condition}) -is the opposite from the order in which they are bound. Thus, more -recently bound handlers appear earlier in the search order. - -@deffn {procedure+} bind-condition-handler condition-types handler thunk -@findex condition/internal? -Executes @var{thunk}, handling any condition whose generalizations -intersect @var{condition-types} by passing it to @var{handler}. -@var{Condition-types} must be a list of condition-type objects. If -@var{condition-types} is the empty list, it means @var{handler} should -handle @emph{all} conditions, regardless of their type; such handlers -should ignore conditions satisfying the predicate -@code{condition/internal?}. -@end deffn - -@node Predefined Errors, , Condition Handling, Error System -@section Predefined Errors - -@defvr {condition type+} error-type:wrong-type-argument -Signalled when the argument to a procedure is determined to have an -incorrect type. For example, this error is signalled by @code{car} if -its argument is not a pair. This is a specialization of -@code{error-type:illegal-argument}. -@end defvr - -@deffn {procedure+} error:illegal-datum object [procedure-name] -Signals @code{error-type:wrong-type-argument}. @var{Object} is the -argument in question, and @code{procedure-name}, if supplied, is the -name of the procedure that determined the argument's incorrectness. -@end deffn - -@defvr {condition type+} error-type:bad-range-argument -Signalled when the argument to a procedure is determined to have the -correct type but is not in the acceptable range. For example, this -error is signalled by @code{vector-ref} if its second argument is an -exact negative integer. This is a specialization of -@code{error-type:illegal-argument}. -@end defvr - -@deffn {procedure+} error:datum-out-of-range object [procedure-name] -Signals @code{error-type:bad-range-argument}. @var{Object} is the -argument in question, and @code{procedure-name}, if supplied, is the -name of the procedure that determined the argument's incorrectness. -@end deffn - -@defvr {condition type+} error-type:illegal-argument -This type is not signalled -- one of its specializations is signalled -when the argument to a procedure is determined to be incorrect in some -fashion. -@end defvr - -@defvr {condition type+} error-type:open-file -Signalled if an error occurs while trying to open a file for input or -output. -@end defvr - -@defvr {condition type+} error-type:file -This type is not signalled -- one of its specializations is signalled -when any @sc{i/o} error occurs. The name of this type is a misnomer; it -can be signalled by any @sc{i/o} operation, whether or not it involves -files. -@end defvr +This chapter is being rewritten and is not yet finished. @node Graphics, Win32 Package Reference, Error System, Top @chapter Graphics