@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
@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
* 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::
@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
projects / mit-scheme.git / commitdiff