throw ( n -- )

published: 15 March 2022 / updated 2 August 2022

vocabulary: forth

Generates an error if n is not equal to zero.

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.

Example:

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

Legal: site web personnel sans commerce / personal site without seling