6.14.4 Interpreter Directives

These words are usually used in interpret state; typically to control which parts of a source file are processed by the text interpreter. There are only a few Standard Forth Standard words, but Gforth supplements these with a rich set of immediate control structure words to compensate for the fact that the non-immediate versions can only be used in compile state (see Control Structures). Typical usage:

[undefined] \G [if]
  : \G ... ; immediate
[endif]

So if the system does not define \G, compile some replacement code (with possibly reduced functionality).

[IF] ( flag –  ) tools-ext “bracket-if”

If flag is TRUE do nothing (and therefore execute subsequent words as normal). If flag is FALSE, parse and discard words from the parse area (refilling it if necessary using REFILL) including nested instances of [IF].. [ELSE].. [THEN] and [IF].. [THEN] until the balancing [ELSE] or [THEN] has been parsed and discarded. Immediate word.

[ELSE] ( ) tools-ext “bracket-else”

Parse and discard words from the parse area (refilling it if necessary using REFILL) including nested instances of [IF].. [ELSE].. [THEN] and [IF].. [THEN] until the balancing [THEN] has been parsed and discarded. [ELSE] only gets executed if the balancing [IF] was TRUE; if it was FALSE, [IF] would have parsed and discarded the [ELSE], leaving the subsequent words to be executed as normal. Immediate word.

[THEN] ( ) tools-ext “bracket-then”

Do nothing; used as a marker for other words to parse and discard up to. Immediate word.

[ENDIF] ( ) gforth-0.2 “bracket-end-if”

Do nothing; synonym for [THEN]

[defined] ( "<spaces>name" – flag  ) tools-ext “bracket-defined”

returns true if name is found in current search order

[undefined] ( "<spaces>name" – flag  ) tools-ext “bracket-undefined”

returns false if name is found in current search order

[IFDEF] ( "<spaces>name" –  ) gforth-0.2 “bracket-if-def”

If name is found in the current search-order, behave like [IF] with a TRUE flag, otherwise behave like [IF] with a FALSE flag. Immediate word.

[IFUNDEF] ( "<spaces>name" –  ) gforth-0.2 “bracket-if-un-def”

If name is not found in the current search-order, behave like [IF] with a TRUE flag, otherwise behave like [IF] with a FALSE flag. Immediate word.

[?DO] ( n-limit n-index –  ) gforth-0.2 “bracket-question-do”
[DO] ( n-limit n-index –  ) gforth-0.2 “bracket-do”
[LOOP] ( ) gforth-0.2 “bracket-loop”
[+LOOP] ( n –  ) gforth-0.2 “bracket-question-plus-loop”
[FOR] ( n –  ) gforth-0.2 “bracket-for”
[NEXT] ( n –  ) gforth-0.2 “bracket-next”
[I] ( run-time – n  ) gforth-0.2 “bracket-i”

At run-time, [I] pushes the loop index of the text-interpretation-time [do] iteration. If you want to process the index at interpretation time, interpret [I] interpretevely, or use INT-[I].

INT-[I] ( – n  ) gforth-1.0 “int-bracket-i”

Push the loop index of the [do] iteration at text interpretation time.

[BEGIN] ( ) gforth-0.2 “bracket-begin”
[UNTIL] ( flag –  ) gforth-0.2 “bracket-until”
[AGAIN] ( ) gforth-0.2 “bracket-again”
[WHILE] ( flag –  ) gforth-0.2 “bracket-while”
[REPEAT] ( ) gforth-0.2 “bracket-repeat”

You can use #line to change Gforth’s idea about the current source line number and source file. This is useful in cases where the Forth file is generated from some other source code file, and you want to get, e.g. error messages etc. that refer to the original source code; then the Forth-code generator needs to insert #line lines in the Forth code wherever appropriate.

#line ( "u" "["file"]" –  ) gforth-1.0 “#line”

Set the line number to u and (if present) the file name to file. Consumes the rest of the line.