Captain Bob, 2026-11-14: the standard first, in the order 79, 83, ANS, then v3; the texts in the repository as references. FORTH-79 and FORTH-83 from the University of Vienna's FORTH archive (complang.tuwien.ac.at), ANS Forth's final draft (dpANS) from Taygeta, as fetched, with their sources in docs/reference/standards/README.md. Not pushed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
293 lines
8.4 KiB
HTML
293 lines
8.4 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>DPANS94</TITLE>
|
|
</HEAD>
|
|
|
|
<BODY>
|
|
<table width=100%>
|
|
<tr>
|
|
<td align=left>
|
|
<a href=dpansa8.htm><img src=left.gif
|
|
width=26 height=26 align=ALIGN border=0></a>
|
|
<a href=dpansa10.htm><img src=right.gif
|
|
width=26 height=26 align=ALIGN border=0></a>
|
|
</td>
|
|
<td align=right>
|
|
<a href=dpans.htm#toc><img src=up.gif
|
|
width=26 height=26 align=ALIGN border=0></a>
|
|
<a name=A.9>Table of Contents</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<hr size=4>
|
|
|
|
<H2>A.9 The optional Exception word set</H2>
|
|
|
|
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and
|
|
<a href=dpans9.htm#9.6.1.2275>THROW</a>
|
|
provide a reliable mechanism for handling exceptions,
|
|
without having to propagate exception flags through multiple levels of
|
|
word nesting. It is similar in spirit to the <B>non-local return</B>
|
|
mechanisms of many other languages, such as C's setjmp() and longjmp(),
|
|
and LISP's CATCH and THROW. In the Forth context, THROW may be
|
|
described as a <B>multi-level</b>
|
|
<a href=dpans6.htm#6.1.1380>EXIT</a>,
|
|
with CATCH marking a location to
|
|
which a THROW may return.
|
|
|
|
<P>
|
|
|
|
Several similar Forth <B>multi-level EXIT</B> exception-handling schemes
|
|
have been described and used in past years. It is not possible to
|
|
implement such a scheme using only standard words (other than CATCH and
|
|
THROW), because there is no portable way to <B>unwind</B> the return
|
|
stack to a predetermined place.
|
|
|
|
<P>
|
|
|
|
THROW also provides a convenient implementation technique for the
|
|
standard words
|
|
<a href=dpans6.htm#6.1.0670>ABORT</a> and
|
|
<a href=dpans6.htm#6.1.0680>ABORT"</a>,
|
|
allowing an application to define,
|
|
through the use of CATCH, the behavior in the event of a system ABORT.
|
|
|
|
<P>
|
|
|
|
This sample implementation of CATCH and THROW uses the non-standard
|
|
words described below. They or their equivalents are available in many
|
|
systems. Other implementation strategies, including directly saving the
|
|
value of
|
|
<a href=dpans6.htm#6.1.1200>DEPTH</a>,
|
|
are possible if such words are not available.
|
|
|
|
<P>
|
|
|
|
SP@ ( -- addr ) returns the
|
|
address corresponding to the top of data stack.
|
|
|
|
<P>
|
|
|
|
SP! ( addr -- ) sets the stack pointer to addr, thus restoring the stack
|
|
depth to the same depth that existed just before addr was acquired by
|
|
executing SP@.
|
|
|
|
<P>
|
|
|
|
RP@ ( -- addr ) returns the address corresponding to the top of return
|
|
stack.
|
|
|
|
<P>
|
|
|
|
RP! ( addr -- ) sets the return stack pointer to addr, thus restoring the
|
|
return stack depth to the same depth that existed just before addr was
|
|
acquired by executing RP@.
|
|
|
|
<PRE>
|
|
VARIABLE HANDLER 0 HANDLER ! \ last exception handler
|
|
|
|
: CATCH ( xt -- exception# | 0 ) \ return addr on stack
|
|
SP@ >R ( xt ) \ save data stack pointer
|
|
HANDLER @ >R ( xt ) \ and previous handler
|
|
RP@ HANDLER ! ( xt ) \ set current handler
|
|
EXECUTE ( ) \ execute returns if no THROW
|
|
R> HANDLER ! ( ) \ restore previous handler
|
|
R> DROP ( ) \ discard saved stack ptr
|
|
0 ( 0 ) \ normal completion
|
|
;
|
|
|
|
: THROW ( ??? exception# -- ??? exception# )
|
|
?DUP IF ( exc# ) \ 0 THROW is no-op
|
|
HANDLER @ RP! ( exc# ) \ restore prev return stack
|
|
R> HANDLER ! ( exc# ) \ restore prev handler
|
|
R> SWAP >R ( saved-sp ) \ exc# on return stack
|
|
SP! DROP R> ( exc# ) \ restore stack
|
|
\ Return to the caller of CATCH because return
|
|
\ stack is restored to the state that existed
|
|
\ when CATCH began execution
|
|
THEN
|
|
;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
In a multi-tasking system, the HANDLER variable should be in the
|
|
per-task variable area (i.e., a user variable).
|
|
|
|
<P>
|
|
|
|
This sample implementation does not explicitly handle the case in which
|
|
CATCH has never been called (i.e., the ABORT behavior). One solution is
|
|
to add the following code after the IF in THROW:
|
|
|
|
|
|
<PRE>
|
|
HANDLER @ 0= IF ( empty the stack ) QUIT THEN
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Another solution is to execute CATCH within
|
|
<a href=dpans6.htm#6.1.2050>QUIT</a>, so that there is
|
|
always an <B>exception handler of last resort</B> present. For example:
|
|
|
|
<PRE>
|
|
: QUIT ( empty the return stack and )
|
|
( set the input source to the user input device )
|
|
POSTPONE [
|
|
BEGIN
|
|
REFILL
|
|
WHILE
|
|
['] INTERPRET CATCH
|
|
CASE
|
|
0 OF STATE @ 0= IF ." OK" THEN CR ENDOF
|
|
-1 OF ( Aborted) ENDOF
|
|
-2 OF ( display message from ABORT" ) ENDOF
|
|
( default ) DUP ." Exception # " .
|
|
ENDCASE
|
|
REPEAT BYE
|
|
;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
This example assumes the existance of a system-implementation word
|
|
INTERPRET that embodies the text interpreter semantics described in
|
|
<a href=dpans3.htm#3.4>3.4</a>
|
|
The Forth text interpreter. Note that this implementation of QUIT
|
|
automatically handles the emptying of the stack and return stack, due to
|
|
THROW's inherent restoration of the data and return stacks. Given this
|
|
definition of QUIT, it's easy to define:
|
|
|
|
|
|
<PRE>
|
|
: ABORT -1 THROW ;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
In systems with other stacks in addition to the data and return stacks,
|
|
the implementation of CATCH and THROW must save and restore those stack
|
|
pointers as well. Such an <B>extended version</B> can be built on top
|
|
of this basic implementation. For example, with another stack pointer
|
|
accessed with FP@ and FP! only CATCH needs to be redefined:
|
|
|
|
<PRE>
|
|
: CATCH ( xt -- exception# | 0 )
|
|
FP@ >R CATCH R> OVER IF FP! ELSE DROP THEN ;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
No change to THROW is necessary in this case. Note that, as with all
|
|
redefinitions, the redefined version of CATCH will only be available to
|
|
definitions compiled after the redefinition of CATCH.
|
|
|
|
<P>
|
|
|
|
CATCH and THROW provide a convenient way for an implementation to
|
|
<B>clean up</B> the state of open files if an exception occurs during
|
|
the text interpretation of a file with
|
|
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a>. The implementation
|
|
of INCLUDE-FILE may guard (with CATCH) the word that performs the text
|
|
interpretation, and if CATCH returns an exception code, the file may be
|
|
closed and the exception reTHROWn so that the files being included at an
|
|
outer nesting level may be closed also. Note that the Standard allows,
|
|
but does not require, INCLUDE-FILE to close its open files if an
|
|
exception occurs. However, it does require INCLUDE-FILE to unnest the
|
|
input source specification if an exception is THROWn.
|
|
|
|
<P>
|
|
|
|
<hr>
|
|
<a name=A.9.3>
|
|
<H3>A.9.3 Additional usage requirements</H3>
|
|
</a>
|
|
|
|
One important use of an exception handler is to maintain program control
|
|
under many conditions which
|
|
<a href=dpans6.htm#6.1.0670>ABORT</a>. This is practicable only if a range
|
|
of codes is reserved. Note that an application may overload many
|
|
standard words in such a way as to
|
|
<a href=dpans9.htm#9.6.1.2275>THROW</a> ambiguous conditions not
|
|
normally THROWn by a particular system.
|
|
|
|
<P>
|
|
|
|
<hr>
|
|
<a name=A.9.3.6>
|
|
<H4>A.9.3.6 Exception handling</H4>
|
|
</a>
|
|
|
|
The method of accomplishing this coupling is implementation dependent.
|
|
For example,
|
|
<a href=dpans7.htm#7.6.1.1790>LOAD</a>
|
|
could <B>know</B> about
|
|
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and
|
|
<a href=dpans9.htm#9.6.1.2275>THROW</a> (by using
|
|
CATCH itself, for example), or CATCH and THROW could <B>know</B> about
|
|
LOAD (by maintaining input source nesting information in a data
|
|
structure known to THROW, for example). Under these circumstances it is
|
|
not possible for a Standard Program to define words such as LOAD in a
|
|
completely portable way.
|
|
|
|
<P>
|
|
|
|
<hr>
|
|
<a name=A.9.6>
|
|
<H3>A.9.6 Glossary</H3>
|
|
</a>
|
|
|
|
|
|
<hr>
|
|
<a name=A.9.6.1.2275>A.9.6.1.2275 THROW</A>
|
|
<P>
|
|
|
|
If THROW is executed with a non zero argument, the effect is as if the
|
|
corresponding
|
|
<a href=dpans9.htm#9.6.1.0875>CATCH</a>
|
|
had returned it. In that case, the stack depth is
|
|
the same as it was just before CATCH began execution. The values of the
|
|
i*x stack arguments could have been modified arbitrarily during the
|
|
execution of xt. In general, nothing useful may be done with those
|
|
stack items, but since their number is known (because the stack depth is
|
|
deterministic), the application may
|
|
<a href=dpans6.htm#6.1.1260>DROP</a> them to return to a predictable
|
|
stack state.
|
|
|
|
<P>
|
|
|
|
Typical use:
|
|
|
|
<PRE>
|
|
: could-fail ( -- char )
|
|
KEY DUP [CHAR] Q = IF 1 THROW THEN ;
|
|
|
|
: do-it ( a b -- c) 2DROP could-fail ;
|
|
|
|
: try-it ( --)
|
|
1 2 ['] do-it CATCH IF ( x1 x2 )
|
|
2DROP ." There was an exception" CR
|
|
ELSE ." The character was " EMIT CR
|
|
THEN
|
|
;
|
|
|
|
: retry-it ( -- )
|
|
BEGIN 1 2 ['] do-it CATCH WHILE
|
|
( x1 x2) 2DROP ." Exception, keep trying" CR
|
|
REPEAT ( char )
|
|
." The character was " EMIT CR
|
|
;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<hr>
|
|
<a href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents
|
|
<BR>
|
|
<a href=dpansa10.htm><IMG src="right.gif" ></A>
|
|
Next Section
|
|
<P>
|
|
</BODY>
|
|
</HTML>
|