PageRenderTime 11ms CodeModel.GetById 1ms app.highlight 4ms RepoModel.GetById 2ms app.codeStats 0ms

/doc/srfi-error-reporting.texi

http://github.com/marcomaggi/vicare
Unknown | 171 lines | 131 code | 40 blank | 0 comment | 0 complexity | 1b7bb3b718e1e043977951ed65bf73d9 MD5 | raw file
  1@node srfi error-reporting
  2@section @ansrfi{23} error reporting mechanism
  3
  4
  5@cindex @ansrfi{23} error reporting mechanism
  6@cindex @library{srfi :23}, library
  7@cindex @library{srfi :23 error}, library
  8@cindex Library @library{srfi :23}
  9@cindex Library @library{srfi :23 error}
 10
 11
 12The library @library{srfi :23} is by Stephan Houben as the reference
 13implementation for @ansrfi{23}; see:
 14
 15@center @url{http://srfi.schemers.org/srfi-23/srfi-23.html}
 16
 17@noindent
 18for more details.
 19
 20@menu
 21* srfi error-reporting license::   Error-reporting document
 22                                   license.
 23* srfi error-reporting abstract::  Abstract.
 24* srfi error-reporting rationale:: Rationale.
 25* srfi error-reporting spec::      Specification.
 26@end menu
 27
 28@c page
 29@node srfi error-reporting license
 30@subsection Error--reporting document license
 31
 32
 33Copyright @copyright{} 2001 Stephan Houben @email{stephanh@@win.tue.nl}.
 34All Rights Reserved.
 35
 36Permission is hereby granted, free of charge, to any person obtaining a
 37copy of this software and associated documentation files (the
 38``Software''), to deal in the Software without restriction, including
 39without limitation the rights to use, copy, modify, merge, publish,
 40distribute, sublicense, and/or sell copies of the Software, and to
 41permit persons to whom the Software is furnished to do so, subject to
 42the following conditions:
 43
 44The above copyright notice and this permission notice shall be included
 45in all copies or substantial portions of the Software.
 46
 47THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
 48EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 49MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 50IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 51CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 52TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 53SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 54
 55@c page
 56@node srfi error-reporting abstract
 57@subsection Abstract
 58
 59
 60A mechanism is proposed to allow Scheme code to report errors and abort
 61execution.  The proposed mechanism is already implemented in several
 62Scheme systems and can be implemented, albeit imperfectly, in any
 63@rnrs{5} conforming Scheme.
 64
 65@c page
 66@node srfi error-reporting rationale
 67@subsection Rationale
 68
 69
 70@rnrs{5} Scheme requires certain operations to signal an error when they
 71fail.  ``Signalling an error'' means that implementations must detect
 72and report the error.  Moreover, @rnrs{5} encourages, but not requires,
 73implementations to signal an error in many more circumstances.
 74
 75However, there is no direct way for the Scheme application programmer to
 76report an error that occured in his or her own application.  This means
 77that Scheme procedures created by applications or libraries are in this
 78respect not on equal footing with procedures provided by the Scheme
 79system.
 80
 81Many Scheme systems already provide a mechanism that allows application
 82code to report an error.  At least the following implementations support
 83such a mechanism: Bigloo, Guile, @acronym{MIT} Scheme, @acronym{PLT}
 84Scheme, RScheme, Scsh, SCM, all implementations supported by Slib.  Of
 85these implementations, the following have an error mechanism compatible
 86with this @srfi{}: Guile, @acronym{MIT} Scheme, @acronym{PLT} Scheme,
 87RScheme, Scsh.  The implementation in Slib has a different name than the
 88one proposed in this @srfi{}.
 89
 90To summarise, many implementations already have the error reporting
 91mechanism described in this @srfi{} and others are easily made
 92compatible with this @srfi{}.  This shows that the proposed mechanism
 93is considered useful and that it is easy to implement in most major
 94implementations.
 95
 96@c page
 97@node srfi error-reporting spec
 98@subsection Specification
 99
100
101@defun error @var{reason} [@var{arg1} [@var{arg2} ...]])
102The argument @var{reason} should be a string.  The procedure error will
103signal an error, as described in @rnrs{5}, and it will report the
104message @var{reason} and the objects @var{arg1}, @var{arg2}, ...
105
106What exactly constitutes ``signalling'' and ``reporting'' is not
107prescribed, because of the large variation in Scheme systems.  So it is
108left to the implementor to do something reasonable.  To that end, a few
109examples of possible behaviour are given.
110
111@enumerate
112@item
113Display @var{reason} and @var{arg1}... on the screen and terminate the
114Scheme program.  This might be suitable for a Scheme system implemented
115as a batch compiler.
116
117@item
118Display @var{reason} and @var{arg1}... on the screen and go back to the
119read--evaluate--print loop.  This might be suitable for an interactive
120implementation.
121
122@item
123In the case of a multi--threaded system: terminate the current thread,
124but do not terminate the other threads.  Possibly make the arguments to
125error available to other threads in some way.  See the
126@func{thread-join!}  mechanism in @ansrfi{18} on how this could be done.
127
128@item
129Package @var{reason} and @var{arg1}... up into an error object and pass
130this error object to an exception handler.  The default exception
131handler then might do something as described in points 1 to 3.
132
133@item
134In the case of a Scheme system that runs completely unattended and that
135has no way to notify a human, the only reasonable course of action might
136be to do nothing at all.  However, this should be considered a last
137resort.  Clearly, if all implementors would choose this strategy, this
138@srfi{} would not be very useful.
139@end enumerate
140
141An implementation might report more information than just @var{reason}
142and @var{arg1}...  For instance, it might report the procedure name in
143which the error occured or even print a stack trace.  However, this will
144require additional support in the Scheme implementation.
145@end defun
146
147
148@c ------------------------------------------------------------
149
150@subsubheading Why error is a procedure
151
152
153@noindent
154It is conceivable to allow error to be a special form, such as a macro,
155rather than a procedure.  This might make providing information such as
156the source code location easier.  This possibility has been considered,
157but rejected, for two reasons.
158
159@enumerate
160@item
161Since error accepts a variable number of arguments, it could
162occasionally be useful to use apply to call error.  However, this is not
163possible if error was allowed to be a special form.
164
165@item
166Since error is currently a procedure in all Scheme implementations
167mentioned above, it doesn't seem all that worthwhile to allow it to be a
168special form.
169@end enumerate
170
171@c end of file