StrongForth Exception Glossary


(ABORT") ( SINGLE CCONST -> CHARACTER UNSIGNED -- )

If any bit of SINGLE is not zero, store CCONST -> CHARACTER in ERROR-ADDR, store UNSIGNED in ERROR-COUNT, and then perform the function of -2 THROW.

(ABORT") is an internal definition compiled by ABORT".


(CATCH) ( TOKEN INTEGER -- SIGNED )

Push an exception frame onto the return stack and then execute the execution token TOKEN in such a way that control can be transferred to a point just after CATCH if THROW is executed during the execution of TOKEN. INTEGER is the difference of the data stack depth (in cells) before and after normal execution of TOKEN. INTEGER is positive if executing TOKEN decreases the data stack size, negative if executing TOKEN increases the data stack size, and zero if executing TOKEN does not change the data stack size.

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

Note: (CATCH) is a low-level word that is executed or compiled by CATCH.


?SIZE ( DATA-TYPE -- UNSIGNED )

UNSIGNED is the size in cells of data type DATA-TYPE. An exception is thrown if the size of DATA-TYPE cannot be determined.


ABORT ( -- )

Perform the function of -1 THROW.


ABORT" ( "ccc" -- )

Extend the semantics of ABORT" as follows.

Interpretation:
An exception is thrown if ABORT" is interpreted.

Compilation:
Parse ccc delimited by " (double-quote). Append the runtime semantics given below to the current definition.

Runtime: ( SINGLE -- )
Remove SINGLE from the stack. If any bit of SINGLE is not zero, store the character string ccc in ERROR-ADDR and ERROR-COUNT, and then perform the function of -2 THROW.

ABORT" is an immediate word.


CATCH ( -- )

Interpretation: ( TOKEN -- SIGNED )
An exception is thrown if TOKEN is not a qualified token, or if the stack diagram associated with the qualified token contains one or more parameters of data type TUPLE or its direct or indirect subtypes. Push an exception frame onto the return stack and then execute the execution token TOKEN in such a way that control can be transferred to a point just after CATCH if THROW is executed during the execution of TOKEN. Adjust the interpreter data type heap according to the stack diagram associated with TOKEN.

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

Compilation:
An exception is thrown if the top of the compiler data type heap does not contain a qualified token, or if the stack diagram associated with the qualified token contains one or more parameters of data type TUPLE or its direct or indirect subtypes. Adjust the compiler data type heap according to the stack diagram associated with the qualified token. Append the runtime semantics given below to the current definition.

Runtime: ( TOKEN -- SIGNED )
Push an exception frame onto the return stack and then execute the execution token TOKEN in such a way that control can be transferred to a point just after CATCH if THROW is executed during the execution of TOKEN.

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

CATCH is an immediate word.


DEPTH-SP ( -- UNSIGNED )

UNSIGNED is the depth of the data stack in cells, calculated from the contents of the data type heap. In interpretation state, the interpreter data type heap is used. In compilation state, the compiler data type heap is used. An exception is thrown if the depth of the data stack cannot be determined.

Note: In interpretation state, UNSIGNED includes the output parameters of the word that is currently being interpreted. UNSIGNED equals the actual number of cells on the data stack only if the data stack and the interpreter data type heap are aligned.

Note: In compilation state, UNSIGNED is zero if the compiler data type heap is locked.


ERROR ( SIGNED -- )

If SIGNED is not equal to zero, display an error message depending on the value of SIGNED. Then perform the function of ABORT.

If SIGNED is -1, display no message at all.

If SIGNED is -2, display the error message that is specified by the contents of system variables ERROR-ADDR and ERROR-COUNT.

If SIGNED is neither -1 nor -2, display the current line of the input source up to and including the most recently parsed word, plus an error message associated with the error code SIGNED. Display the data types of the items currently on the data stack on a second line.


ERROR-ADDR ( -- DATA -> CCONST -> CHARACTER )

DATA -> CCONST -> CHARACTER is the address of a cell that contains the address of the character string, which is to be displayed by ERROR if the error code is -2.


ERROR-COUNT ( -- DATA -> UNSIGNED )

DATA -> UNSIGNED is the address of a cell that contains the number of characters to be displayed by ERROR if the error code is -2.


HANDLER ( -- DATA -> DATA )

A variable that contains a pointer to the location of the innermost exception frame on the return stack. HANDLER contains a null pointer if no exception frame is available.


QUIT ( -- )

Empty the return stack. Store a null address in system variable HANDLER. Make the user input device the input source. Enter interpretation state and re-initialize the local name space. Do not display a message. Repeat the following until the end of the input source:

After the end of the input source has exceeded, terminate StrongForth and return control to the operating system.


THROW ( SIGNED -- )

If SIGNED is non-zero, pop the latest exception frame along with everything on the return stack above that frame. Then restore the input source specification in use before the CATCH that pushed that exception frame. Adjust the depth of the data stack so that it is the same as if the corresponding CATCH were executed normally, i. e., without THROW. Put SIGNED on top of the data stack, and transfer control to a point just after the corresponding CATCH.

If no exception frame is present, execute ERROR with SIGNED on top of the data stack.

Other than in ANS Forth, the depth of the data stack immediately after CATCH does not depend on whether THROW was executed or not. The data stack pointer always has the value it would have if the execution token provided to CATCH were executed normally.

THROW is a deferred definition.


Dr. Stephan Becher - January 9th, 2008