Files
LithosAnanke/docs/reference/standards/ans94/dpansa9.htm
T
Claude 3de8427827 docs: the FORTH standards v4 is held to -- FORTH-79, FORTH-83, ANS Forth 1994 (#189)
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
2026-11-14 03:16:13 +00:00

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>