Forth 200x: The optional Exception word set

The THROW values {-255...-1} shall be used only as assigned by this standard. The values {-4095...-256} shall be used only as assigned by a system.

9.3.2 Exception frame

9.3.3 Exception stack

9.3.4 Possible actions on an ambiguous condition

A system choosing to execute THROW when detecting one of the ambiguous conditions listed in table 9.1 shall use the throw code listed there.

Table 9.1: THROW code assignments

Code Reserved for

-1	ABORT
-2	ABORT"
-3	stack overflow
-4	stack underflow
-5	return stack overflow
-6	return stack underflow
-7	do-loops nested too deeply during execution
-8	dictionary overflow
-9	invalid memory address
-10	division by zero
-11	result out of range
-12	argument type mismatch
-13	undefined word
-14	interpreting a compile-only word
-15	invalid FORGET
-16	attempt to use zero-length string as a name
-17	pictured numeric output string overflow
-18	parsed string overflow
-19	definition name too long
-20	write to a read-only location
-21	unsupported operation
	(e.g., AT-XY on a too-dumb terminal)
-22	control structure mismatch
-23	address alignment exception
-24	invalid numeric argument
-25	return stack imbalance
-26	loop parameters unavailable
-27	invalid recursion
-28	user interrupt
-29	compiler nesting
-30	obsolescent feature
-31	>BODY used on non-CREATEd definition
-32	invalid name argument (e.g., TO name)
-33	block read exception
-34	block write exception
-35	invalid block number
-36	invalid file position
-37	file I/O exception
-38	non-existent file
-39	unexpected end of file

-40	invalid BASE for floating point conversion
-41	loss of precision
-42	floating-point divide by zero
-43	floating-point result out of range
-44	floating-point stack overflow
-45	floating-point stack underflow
-46	floating-point invalid argument
-47	compilation word list deleted
-48	invalid POSTPONE
-49	search-order overflow
-50	search-order underflow
-51	compilation word list changed
-52	control-flow stack overflow
-53	exception stack overflow
-54	floating-point underflow
-55	floating-point unidentified fault
-56	QUIT
-57	exception in sending or receiving a character
-58	[IF], [ELSE], or [THEN] exception
-59	ALLOCATE
-60	FREE
-61	RESIZE
-62	CLOSE-FILE
-63	CREATE-FILE
-64	DELETE-FILE
-65	FILE-POSITION
-66	FILE-SIZE
-67	FILE-STATUS
-68	FLUSH-FILE
-69	OPEN-FILE
-70	READ-FILE
-71	READ-LINE
-72	RENAME-FILE
-73	REPOSITION-FILE
-74	RESIZE-FILE
-75	WRITE-FILE
-76	WRITE-LINE
-77	Malformed xchar
-78	SUBSTITUTE
-79	REPLACES

9.3.5 Exception handling

When a THROW returns control to a CATCH, the system shall un-nest not only definitions, but also, if present, locals and input source specifications, to return the system to its proper state for continued execution past the CATCH.

9.4 Additional documentation requirements

9.4.1 System documentation

9.4.1.1 Implementation-defined options

9.4.1.2 Ambiguous conditions

9.4.1.3 Other system documentation

9.4.2 Program documentation

9.5 Compliance and labeling

9.5.1 Forth-2012 systems

The phrase "Providing name(s) from the Exception Extensions word set" shall be appended to the label of any Standard System that provides portions of the Exception Extensions word set.

The phrase "Providing the Exception Extensions word set" shall be appended to the label of any Standard System that provides all of the Exception and Exception Extensions word sets.

9.5.2 Forth-2012 programs

The phrase "Requiring name(s) from the Exception Extensions word set" shall be appended to the label of Standard Programs that require the system to provide portions of the Exception Extensions word set.

The phrase "Requiring the Exception Extensions word set" shall be appended to the label of Standard Programs that require the system to provide all of the Exception and Exception Extensions word sets.

9.6 Glossary

9.6.1 Exception words

( i×x xt -- j×x 0 | i×x n )

Push an exception frame on the exception stack and then execute the execution token xt (as with EXECUTE) in such a way that control can be transferred to a point just after CATCH if THROW is executed during the execution of xt.

If the execution of xt completes normally (i.e., the exception frame pushed by this CATCH is not popped by an execution of THROW) pop the exception frame and return zero on top of the data stack, above whatever stack items would have been returned by xt EXECUTE. Otherwise, the remainder of the execution semantics are given by THROW.

See

A.9.6.1.2275 THROW.

Implementation

This sample implementation of CATCH 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 DEPTH, are possible if such words are not available.

SP@: ( -- addr )
returns the address corresponding to the top of data stack.
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@.
RP@: ( -- addr )
returns the address corresponding to the top of return stack.
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@.

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
;

In a multi-tasking system, the HANDLER variable should be in the per-task variable area (i.e., a user variable).

This sample implementation does not explicitly handle the case in which CATCH has never been called (i.e., the ABORT behavior). One solution would be to execute a CATCH within QUIT, so that there is always an "exception handler of last resort" present, as shown in E.6.1.2050 QUIT.

Testing

See F.9.6.1.2275 THROW.

( k×x n -- k×x | i×x n )

If any bits of n are non-zero, pop the topmost exception frame from the exception stack, along with everything on the return stack above that frame. Then restore the input source specification in use before the corresponding CATCH and adjust the depths of all stacks defined by this standard so that they are the same as the depths saved in the exception frame (i is the same number as the i in the input arguments to the corresponding CATCH), put n on top of the data stack, and transfer control to a point just after the CATCH that pushed that exception frame.

If the top of the stack is non zero and there is no exception frame on the exception stack, the behavior is as follows:

If n is minus-one (-1), perform the function of 6.1.0670 ABORT (the version of ABORT in the Core word set), displaying no message.

If n is minus-two, perform the function of 6.1.0680 ABORT" (the version of ABORT" in the Core word set), displaying the characters ccc associated with the ABORT" that generated the THROW.

Otherwise, the system may display an implementation-dependent message giving information about the condition associated with the THROW code n. Subsequently, the system shall perform the function of 6.1.0670 ABORT (the version of ABORT in the Core word set).

See

A.9.6.1.2275 THROW.

Rationale

If THROW is executed with a non zero argument, the effect is as if the corresponding CATCH 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 DROP them to return to a predictable stack state.

Typical use:

: 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
;

Implementation

This is the counter part to E.9.6.1.0875 CATCH.

: 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
;

Testing

DECIMAL

: t1 9 ;
: c1 1 2 3 ['] t1 CATCH ;
T{ c1 -> 1 2 3 9 0 }T \ No THROW executed

: t2 8 0 THROW ;
: c2 1 2 ['] t2 CATCH ;
T{ c2 -> 1 2 8 0 }T \ 0 THROW does nothing

: t3 7 8 9 99 THROW ;
: c3 1 2 ['] t3 CATCH ;
T{ c3 -> 1 2 99 }T \ Restores stack to CATCH depth

: t4 1- DUP 0> IF RECURSE ELSE 999 THROW -222 THEN ;
: c4 3 4 5 10 ['] t4 CATCH -111 ;
T{ c4 -> 3 4 5 0 999 -111 }T \ Test return stack unwinding

: t5 2DROP 2DROP 9999 THROW ;
: c5 1 2 3 4 ['] t5 CATCH \ Test depth restored correctly
DEPTH >R DROP 2DROP 2DROP R> ; \ after stack has been emptied
T{ c5 -> 5 }T

9.6.2 Exception extension words

Extend the semantics of 6.1.0670 ABORT to be: ( i×x -- ) ( R: j×x -- )

Perform the function of -1 THROW.

See

6.1.0670 ABORT.

Implementation

: ABORT -1 THROW ;

Testing

See F.9.6.2.0680 ABORT".

Extend the semantics of 6.1.0680 ABORT" to be:

Interpretation

Interpretation semantics for this word are undefined.

Compilation

( "ccc<quote>" -- )

Parse ccc delimited by a " (double-quote). Append the run-time semantics given below to the current definition.

Run-time

( i×x x₁ -- | i×x ) ( R: j×x -- | j×x )

Remove x₁ from the stack. If any bit of x₁ is not zero, perform the function of -2 THROW, displaying ccc if there is no exception frame on the exception stack.

See

3.4.1 Parsing, 6.1.0680 ABORT".

Testing

DECIMAL
-1 CONSTANT exc_abort
-2 CONSTANT exc_abort"
-13 CONSTANT exc_undef
: t6 ABORT ;

The 77 in t10 is necessary for the second ABORT" test as the data stack is restored to a depth of 2 when THROW is executed. The 77 ensures the top of stack value is known for the results check.

: t10 77 SWAP ABORT" This should not be displayed" ;
: c6 CATCH
   CASE exc_abort OF 11 ENDOF
        exc_abort" OF 12 ENDOF
        exc_undef OF 13 ENDOF
   ENDCASE
;

T{ 1 2 '  t6 c6 -> 1 2 11 }T    \ Test that ABORT is caught
T{ 3 0 ' t10 c6 -> 3 77    }T    \ ABORT" does nothing
T{ 4 5 ' t10 c6 -> 4 77 12 }T    \ ABORT" caught, no message

9 The optional Exception word set

9.1 Introduction

9.2 Additional terms and notation

9.3 Additional usage requirements

9.3.1 THROW values

9.3.2 Exception frame

9.3.3 Exception stack

9.3.4 Possible actions on an ambiguous condition

9.3.5 Exception handling

9.4 Additional documentation requirements

9.4.1 System documentation

9.4.1.1 Implementation-defined options

9.4.1.2 Ambiguous conditions

9.4.1.3 Other system documentation

9.4.2 Program documentation

9.5 Compliance and labeling

9.5.1 Forth-2012 systems

9.5.2 Forth-2012 programs

9.6 Glossary

9.6.1 Exception words

9.6.2 Exception extension words