Demo of an immediate IMMEDIATE #197

ebblake · 2025-08-08T16:25:48Z

ebblake
Aug 8, 2025

My introduction to Forth was Jonesforth, which includes this gem:

	Typical usage is:

	: MYIMMEDWORD IMMEDIATE
		...definition...
	;

	but some FORTH programmers write this instead:

	: MYIMMEDWORD
		...definition...
	; IMMEDIATE

	The two usages are equivalent, to a first approximation.

But reading the standard, portable programs MUST use the latter spelling, where the notion of whether a word will be immediate can be rather distant from the name of the word itself. And I'm not the only one wondering why you can't portably use immediate closer to the word name: JennyBrien observed "I used to do that very thing many years ago, on the basis of 'say what you are doing as soon as you can'. It's a nice thing to have, and I'm not sure why iForth doesn't allow it."

Further inspired by a demo on how to implement a ?: that avoids redefining a word if it already exists (by swapping over to a :NONAME then using negative ALLOT during ; to undo the extra definition, but which also must special-case IMMEDIATE since that word is ambiguous after a :NONAME), I wanted to see if I could solve the ambiguity in a different way.

With that introduction, here's my attempt.

\ This file is in the public domain. NO WARRANTY.

\ Originally designed by Eric Blake, August 2025.

\ Enhance IMMEDIATE to be usable inline within a colon definition for
\ (eventually) marking the definition underway as immediate.

\ The goal of this file is to permit the following:
\   : name IMMEDIATE ... ;
\ as syntax sugar for
\   : name ... ; IMMEDIATE
\ to satisfy the mantra "say what you are doing as soon as you can":
\ https://forth-standard.org/standard/core/IMMEDIATE#reply-313

\ Note that the goal of recognizing IMMEDIATE right after : name thus
\ requires IMMEDIATE to be immediate.  However, this is not trivial.

\ First, even without being immediate, there is an ambiguity that is
\ observable between implementations on the following code:
\    : foo ." foo " ;
\    : bar [ immediate ] ." bar " ;
\ where some implementations (gforth, SwitfForth, VFX) mark bar as
\ immediate, and others (iForth) mark foo as immediate.
\ https://forth-standard.org/standard/core/IMMEDIATE#contribution-112

\ Forth-2012 16.3.3 basically states that it is ambiguous if a program
\ modifies the compilation word list during compilation, but the purpose
\ of IMMEDIATE is to change the compilation list by making the latest
\ definition immediate.  So, regardless of whether : is required to make
\ the latest definition be the ongoing compilation, actually executing
\ IMMEDIATE before ; triggered ambiguous behavior.

\ At the same time, the standard requires this test to pass:
\   T{ : IW9 CREATE , DOES> @ 2 + IMMEDIATE ; -> }T
\   : FIND-IW BL WORD FIND NIP ;  ( -- 0 | 1 | -1 )
\   T{ 222 IW9 IW10 FIND-IW IW10 -> -1 }T   \ IW10 is not immediate
\   T{ IW10 FIND-IW IW10 -> 224 1 }T        \ IW10 becomes immediate
\ Basically, once the DOES> body is installed into iw10, then any future
\ execution of iw10 invokes IMMEDIATE on whatever happens to be the most
\ recently compiled word.  Furthermore, while not explicitly shown in
\ the test, it is worth noting that IW9 was not marked immediate; any
\ immediate implementation of IMMEDIATE must not break this test.
\ https://forth-standard.org/standard/testsuite#test:core:IMMEDIATE

\ Furthermore, the fact that IMMEDIATE has traditionally been non-immediate
\ means that there is an existing corpus of code that expects to be able
\ to build meta-programming words, such as:
\   : nop : POSTPONE ; IMMEDIATE ;
\   nop filler
\ which should make filler, rather than nop, be immediate.  Without this
\ file, changing that to
\   : nop : POSTPONE ; POSTPONE IMMEDIATE ;
\   nop filler
\ is wrong; gforth 0.7.3 silently leaves filler as non-immediate, while gforth
\ 0.7.9 additionally warns "Compiling outside a definition" on "nop filler" as
\ a hint as to why.  Basically, because we already established that it is
\ ambiguous to invoke IMMEDIATE while there is a current compilation, the
\ semantics of appending ambiguous behavior to the current compilation
\ semantics of nop is likewise making nop ambiguous.  Fortunately, it does
\ appear to be portable to write
\   : nop : POSTPONE ; ['] IMMEDIATE EXECUTE ;
\   nop filler
\ and have filler reliably be immediate.  However, requiring the user to do
\ such a rewrite everywhere is surprising, and goes against the principle
\ in 6.1.0070 that "When interpreting, ' xyz EXECUTE is equivalent to xyz.",
\ when the user should be able assume that any actions after the postponed ;
\ are being executed in interpretation state.  So, it is desirable to keep
\ the shorter original form working, and this file instead must add
\ complexity to its wrappers.  The code must decide whether an instance of
\ IMMEDIATE encountered between : and : should act on the word being defined,
\ or is being used as a meta-programming context where at runtime some other
\ word will be the intended most recent definition.  For implementations with
\ other words like ]] or POSTPONE{ that can trigger meta-programming without
\ quite so many repetitions of POSTPONE, it may be necessary to similarly
\ wrap those words as well.

\ Implementations that provide other modifiers that affect the most recent
\ definition, such as compile-only or restrict, should be able to do similar
\ wrappers for those words to become immediate; that is left as an exercise
\ for the reader.  Likewise, if you rely on the implementation-defined
\ behavior of CODE or ;CODE, those words will need similar treatment to
\ what this file does for : and DOES>.

\ While testing the effects before and after this file, you may find it
\ convenient to use "imm name", defined as:
\   \g Parsing word to display whether the next word is immediate.
\   [DEFINED] immediate? [IF] : imm ( "word" -- ) ' immediate? . ;
\   [ELSE] : imm BL WORD FIND NIP 1 = . ; [THEN]

\ Dependencies:
\ Requires the following words from the Core word set
\  ! ( : ; ['] DOES> EXECUTE EXIT IF IMMEDIATE POSTPONE SWAP THEN VARIABLE
\ Requires the following words from the Core Extension word set
\  \ TRUE
\ Requires the following words from the Tools Extension word set
\  [DEFINED] [IF] [THEN] [UNDEFINED]

\ Definition order within this file is significant, since some of the
\ wrappers need to utilize the original IMMEDIATE, not the wrapper.

\ Compatibility stuff, inspired by gforth

\ document a word that is ambiguous to use outside of compilation semantics
[UNDEFINED] compile-only [IF] : compile-only ; [THEN]

\ specialized tag to distinguish documentation strings from internal comments
[UNDEFINED] \g [IF] : \g ['] \ EXECUTE ; IMMEDIATE [THEN]

\ convenience for altering the contents of a variable
[UNDEFINED] off [IF] : off 0 SWAP ! ; [THEN]
[UNDEFINED] on [IF] : on TRUE SWAP ! ; [THEN]

\ Implementation

\ Flag set when between : and ;
VARIABLE in-colon in-colon off
\ Flag set during in-colon after POSTPONE, DOES>, embedded :, and similar
VARIABLE in-meta in-meta off
\ Flag set when ; needs to perform a delayed IMMEDIATE.
VARIABLE needs-immediate needs-immediate off

\ Wrap ; to honor needs-immediate.
: ; ( C: colon-sys -- )
  \g Complete a colon-sys after appending run-time semantics of
  \g ( R: nest-sys -- ) to the current definition.
  POSTPONE ;
  needs-immediate @ IF IMMEDIATE THEN  \ uses original non-immediate word
  in-colon off
  in-meta off
  needs-immediate off
; IMMEDIATE compile-only

\ Wrap POSTPONE so that use of IMMEDIATE in the same meta-definition affects
\ the child word instead of the defining word.
: POSTPONE ( C: "name" -- )
  \g Append the compilation semantics of name to the current definition.
  in-meta on
  POSTPONE POSTPONE
; IMMEDIATE compile-only

\ If quotations are supported, the use of IMMEDIATE must occur when the xt
\ is executed, rather than affecting the defining word.
[DEFINED] [: [IF]
: [: ( C: -- quotation-sys colon-sys )
  \g Begin a quotation of an anonymous xt within a larger compilation.
  in-meta on
  POSTPONE [:
; IMMEDIATE compile-only
[THEN]

\ Wrap DOES> so that IMMEDIATE affects the same child word as does>, rather
\ than the does body or the word that used does.  The standard says it is
\ ambiguous to use DOES> in interpretatin context, but as some implementations
\ like gforth support it as a way to install a one-shot anonymous body,
\ so this wrapper works with that.
: DOES> ( C: colon-sys1 -- colon-sys2 )
  \g Complete a colon-sys and arranges to run the subsequent code at the
  \g beginning of a the most recently-defined child word /name/ defined with
  \g CREATE, where the execution of /name/ starts with an a-addr of /name/'s
  \g data field address on the stack.
  in-meta on
  in-colon @ IF POSTPONE DOES> EXIT THEN
  \ reach here only for extension use of interpretation semantics
  ['] DOES> EXECUTE
; IMMEDIATE

\ Wrap : so that uses of IMMEDIATE can be delayed.  Recognize a nested :
\ as an instance of meta-programming, so that ": imm: : immediate ;"
\ applies immediate to the word created by imm:, rather than imm: itself.
: : ( C: "<spaces>name" -- colon-sys )
  \g Begin a colon definition for /name/.
  in-colon @ IF in-meta on POSTPONE : EXIT THEN
  :
  in-colon on
; IMMEDIATE

\ Update IMMEDIATE to be immediate.
: IMMEDIATE ( -- )
  \g Make the most recent definition (whether a word currently being
  \g defined when between : and ;, or the word most recently defined
  \g when after ;) an immediate word.  When used after :, POSTPONE, or
  \g DOES> within a definition, the child word is marked immediate,
  \g rather than the defining word being constructed.  Ambiguous if the
  \g most recent definition does not have a name or was defined as a SYNONYM.
  in-meta @ IF POSTPONE IMMEDIATE EXIT THEN
  in-colon @ IF needs-immediate on EXIT THEN
  IMMEDIATE  \ uses original non-immediate word
; IMMEDIATE

ebblake · 2025-08-08T17:32:54Z

ebblake
Aug 8, 2025
Author

Note that this has the interesting effect that an initial IMMEDIATE behaves differently depending on whether it is the first word in the body of : vs :NONAME; copying and pasting bodies between named and unnamed definitions would have to take that into account:

: foo IMMEDIATE ... ; \ foo is marked immediate
:NONAME IMMEDIATE ... ; \ executing the resulting xt marks the most recent definition as immediate
: a ;
: b ;
EXECUTE  \ b is marked immediate

On the other hand, my personal usage will be along the lines of : name IMMEDIATE ( stack effect ) body..., where the stack effect comment serves as a nice barrier on which portion of the definition makes sense to copy around. And arguably, since the standard is already clear that it is ambiguous to execute IMMEDIATE when the most recent definition was a :NONAME, I can likewise argue that putting IMMEDIATE as the first word after :NONAME is falling foul of that ambiguity (is the user trying to make the anonymous xt immediate, or trying to write an xt that, when executed later, will make some other word immediate); so having a difference in behavior between named and unnamed words is not making the situation any worse.

0 replies

ebblake · 2025-08-08T19:16:08Z

ebblake
Aug 8, 2025
Author

Correcting myself:

\   : nop : POSTPONE ; POSTPONE IMMEDIATE ;
\   nop filler
\ is wrong; gforth 0.7.3 silently leaves filler as non-immediate, while gforth
\ 0.7.9 additionally warns "Compiling outside a definition" on "nop filler" as
\ a hint as to why.  Basically, because we already established that it is
\ ambiguous to invoke IMMEDIATE while there is a current compilation, the
\ semantics of appending ambiguous behavior to the current compilation
\ semantics of nop is likewise making nop ambiguous. 
\   : nop : POSTPONE ; POSTPONE IMMEDIATE ;
\   nop filler
\ is wrong; gforth 0.7.3 silently leaves filler as non-immediate, while gforth
\ 0.7.9 additionally warns "Compiling outside a definition" on "nop filler" as
\ a hint as to why.  Basically, because we already established that it is
\ ambiguous to invoke IMMEDIATE while there is a current compilation, the
\ semantics of appending ambiguous behavior to the current compilation
\ semantics of nop is likewise making nop ambiguous.

A better formulation of this would be that when neither nop nor immediate are marked immediate, the compilation effect of POSTPONE IMMEDIATE is to append the compilation semantics to nop that will execute the compilation semantics of IMMEDIATE when nop is executed. But the compilation semantics of a word that does not list special compilation semantics is to append things to the current definition at the time of execution. Restated, nop is basically compiled to include [ ' immediate ] literal compile,, and then while nop filler is running, compile, is also trying to append semantics to whatever the current word is, but there is no longer a current definition to compile into after the postponed ; completed.

0 replies

CCurl · 2025-08-08T21:40:55Z

CCurl
Aug 8, 2025
Maintainer

My definitions are 99% one-liners, so "immediate" being at the end is not a problem in any way.

I have no desire to put it right after the name of the word.

1 reply

Elkniwt Aug 9, 2025

Putting IMMEDIATE just after the name during the definition makes more sense, just as putting the stack-effect comment there does. Generally, we look at the top of the function to try to find a description of what it does. We could certainly consider adding the word :IMMEDIATE as so:

:immediate then here swap code! ;

It might take less effort, but (for my purposes) would also necessitate :?IMMEDIATE. Merging a modifier like that is just asking for O(2^N) complexity, I guess.

ruv · 2025-08-09T20:05:51Z

ruv
Aug 9, 2025
Maintainer

@ebblake wrote:

\ Wrap POSTPONE so that use of IMMEDIATE in the same meta-definition affects
\ the child word instead of the defining word.

[...]

Amazing work! But this approach is very fragile.

A better way is to define another word [immediate].

false value (shall-be-immediate)

: [immediate] ( -- )
  true to (shall-be-immediate)
; immediate

: ; ( colon-sys -- )
  postpone ;
  (shall-be-immediate) if
    false to (shall-be-immediate)
    immediate
  then
; immediate


\ Optional part, to reset the flag after errors, if any
: : ( "name" -- colon-sys )
  false to (shall-be-immediate)  :
;
: :noname ( -- xt colon-sys )
  false to (shall-be-immediate)  :noname
;

Testcase

t{ : foo [immediate] ; -> }t
t{ : bar ; -> }t
t{ s" foo" get-current search-wordlist nip -> 1 }t
t{ s" bar" get-current search-wordlist nip -> -1 }t

1 reply

ruv Aug 9, 2025
Maintainer

I also used a word imm: ( "name" -- colon-sys )

Using the word [immediate], it can be defined as:

: imm: ( "name" -- colon-sys )
  :
  postpone [immediate]
;

Testcase

t{ imm: foo ; -> }t
t{ s" foo" get-current search-wordlist nip -> 1 }t

ebblake · 2025-08-09T20:45:25Z

ebblake
Aug 9, 2025
Author

I'm liking your idea of a new word for less fragility. For example, https://forth-standard.org/standard/core/Colon#reply-1491 pointed out that my original version mishandles ": VALUE create , immediate does> ..." in an implementation where TO sets a flag on how to handle the next word. Fixing that in my version might be done by also wrapping , and maybe compile, without having to wrap all the defining words like create; or by changing my implementation to explicitly parse the next word to only special-case immediate if it is the very first word after : rather than anywhere before one of the wrapped words that toggle things back off.

But your idea of a new word completely solves the ambiguity, with less wrapping of other words needed. Looks like I get to rewrite my code along the lines of your suggestion!

5 replies

ruv Aug 10, 2025
Maintainer

Just a side note.

: VALUE create , immediate does> ...

Yes, such a case can occur in programs, but this definition does not define the standard value. Since a word that the standard value creates cannot be immediate, or more precisely, its execution semantics cannot depend on STATE.

Elkniwt Aug 10, 2025

I see the words "its execution semantics cannot depend on STATE", but I don't think I understand them on a practical level. The full definition I had was as follows:

create _to 0 ,
: TO 1 _to ! ; immediate
: VALUE
  create ,
  immediate
  does>
  STATE @ if
    _to @ if
      postpone literal
      postpone !
    else
      postpone literal
      postpone @
    then
  else
    _to @ if ! else @ then
  then
  0 _to !
;

The word that VALUE creates definitely takes two different paths based on the value of STATE, but in doing so it still appears to behave identically to the user regardless of STATE. Would "seems to behave the same regardless of STATE" satisfy the condition "execution semantics cannot depend on STATE", or is there a deeper meaning and implications of the above definition that I'm not understanding?

Does the standard explicitly state somewhere that VALUEs execution semantics cannot depend on STATE, or is it implied by the fact that there are not separate "compilation" and "run-time" sections?

ruv Aug 10, 2025
Maintainer

Does the standard explicitly state somewhere that VALUEs execution semantics cannot depend on STATE

Yes, because it explicitly specifies these execution semantics in the section 6.2.2405 VALUE:

name Execution: ( -- x )
Place x on the stack. The value of x is that given when name was created, until the phrase x TO name is executed, causing a new value of x to be assigned to name.

So, the execution semantics of name is to place x on the stack regardless of STATE.

The words search-wordlist, ' (Tick), ['] (Bracket-tick) return xt that identifies the execution semantics of a word.

An example:

1 value foo
: foo2 ( -- x ) ['] foo execute ;
: [foo2] ( -- x ) foo2 ; immediate

\ Now the phrase  "] [foo2] [" shall leave "1" on the data stack

t{  ] [foo2] [  ->  1  }t

Elkniwt Aug 10, 2025

This is upsetting. I was so pleased with the efficiency of postponing literal and fetch/store in my implementation. My first instinct was that maybe I could rework it with some flag kind of like STATE but something that indicated whether it was attempting to be compiled versus executed. I don't know of any way to do so. What's more, I wonder if I've overlooked this distinction elsewhere in my efforts.

I wonder if the idea of supplementing DOES> with COMPILES> versus EXECUTES> phrases would help. I've heard discussions about compilation versus execution semantics before, and cautions against STATE-aware words, but I could never fully comprehend what was being said. I think I'm one step closer.

What, then, is the "best" way to define TO/VALUE in terms of Core-only words? I could try this:

: VALUE create , does> @ ;
: TO bl word find if >body postpone literal postpone ! ; immediate

but this isn't nearly as scalable to 2VALUE and FVALUE as my original attempt, though I may need to encode magic numbers at >BODY, anyway, to handle error checking.

ruv Aug 10, 2025
Maintainer

I was so pleased with the efficiency of postponing literal and fetch/store in my implementation.

To make it efficient, you will probably have to implement it system-specifically. For example, compile, could analyze the kind of xt and inline corresponding code. Or you could associate a "compiler" for an xt that is used by compile, (if set).

the "best" way to define TO/VALUE in terms of Core-only words?

There is no universal best way, each has its own drawbacks.
See an example implementation in an r/Forth thread.

Elkniwt · 2025-08-09T23:09:26Z

Elkniwt
Aug 9, 2025

Similarly, my original draft of ?: had the companion word ;IMMEDIATE to end the optional definition of an immediate word. That draft would just PARSE-WORD until it found either ; or ;IMMEDIATE, so it was not too robust. I switched to using :NONAME later.

Still this could lead to O(2^N) complexity if there were other post-word modifiers (like compile-only, if it did something system-level, etc.). I maintain that a better option is to just ensure that applying such modifiers like IMMEDIATE to :NONAME definitions is just benignly ignored whenever possible. Especially on systems that can absolutely detect that IMMEDIATE is being applied to a :NONAME definition, given the flexibility of the "ambiguous condition" that the spec says exists under such a situation, I see no reason not to simply ignore the word (though I can imagine that at least emitting a warning may help if it's a programmer's error).

5 replies

Elkniwt Aug 9, 2025

... Although ;IMMEDIATE isn't nearly as useful as [IMMEDIATE], which not only gets word immediacy declarable at the top of the word, but also lines up well with the Forth manner of bracketing words (like ['] and [CHAR]). For my purposes, I would also need to prevent it from attempting to apply IMMEDIATE to a :NONAME definition, so I end up here:


( poor man's Core-only [IF]/[THEN]... avoid using `right-paren` in clauses: )
: ) ; : IF( 0= IF POSTPONE ( THEN ;

BL WORD [UNDEFINED] FIND NIP 0= IF(
: [UNDEFINED] BL WORD FIND NIP 0= ; IMMEDIATE
)

[UNDEFINED] \ IF( : \ SOURCE >IN ! DROP ; IMMEDIATE )

\ from [ruv], https://github.com/ForthHub/discussion/discussions/197 , modified:
[UNDEFINED] [IMMEDIATE] IF(

  CREATE _DO_IMM    0 ,
  CREATE _IS_NONAME 0 , 
  
  : [IMMEDIATE] \ { -- }
    1 _DO_IMM !
  ; IMMEDIATE

  : ; \ { colon-sys -- }
    POSTPONE ;
    
    _DO_IMM @ IF
      0 _DO_IMM !
      _IS_NONAME @ 0= IF
        IMMEDIATE
      THEN
    THEN
    0 _IS_NONAME ! 
    
  ; IMMEDIATE

  \ Optional part, to reset the flag after errors, if any
  : : \ { "name" -- colon-sys }
    0 _IS_NONAME !
    0 _DO_IMM !
    :
  ;
  
  : :NONAME \ { -- xt colon-sys }
    -1 _IS_NONAME !
    0 _DO_IMM !
    :NONAME
  ;

)

[UNDEFINED] ?: IF(

  CREATE SKIP-DEF 0 ,

  : ; \ { colon-sys -- }
    POSTPONE ;
    
    SKIP-DEF @ IF
      DROP HERE - ALLOT
      0 SKIP-DEF !
    THEN
    
  ; IMMEDIATE

  \ usage:  `?: -ROT ROT ROT ;`, for instance, will
  \ define `-ROT` only if it's not already defined.
  : ?: \ { "name" -- xt? colon-sys }
    >IN @
    BL WORD FIND NIP
    IF
      \ skip definition:
      DROP
      HERE
      -1 SKIP-DEF !
      :NONAME \ from Core-ext!
    ELSE
      \ back up and define
      >IN ! :
    THEN
  ;
  
)
  
\ define words if they don't already exist:
?: 4TH   ( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 ) 3 PICK   ;
?: <=    ( n1 n2 -- flag )        > 0=              ;
?: 2NIP  ( x1 x2 x3 x4 -- x3 x4 ) ROT DROP ROT DROP ;
?: -ROT  ( x1 x2 x3 -- x2 x3 x1 ) -ROT -ROT         ;
?: RDROP ( R: a -- ) [IMMEDIATE]  R> DROP           ;

ruv Aug 10, 2025
Maintainer

?: RDROP ( R: a -- ) [IMMEDIATE]  R> DROP           ;

Probably it should be POSTPONE R> POSTPONE DROP.

Elkniwt Aug 10, 2025

Probably it should be POSTPONE R> POSTPONE DROP.

Definitely. I got too excited about it all coming together and it made me sloppy :(

ebblake Aug 10, 2025
Author

?: -ROT ( x1 x2 x3 -- x2 x3 x1 ) -ROT -ROT ;

This should be ROT ROT, not -ROT -ROT.

My latest revision has the advantage that I can write : a 1 ; [IMMEDIATE] : b 2 ; and a gets marked immediate; your version at least does not make b immediate, but it fails to make a immediate.

Elkniwt Aug 10, 2025

This should be ROT ROT, not -ROT -ROT.

... typical Elkniwt finish-line fumble. I'll correct this.

My latest revision has the advantage that I can write : a 1 ; [IMMEDIATE] : b 2 ; and a gets marked immediate; your version at least does not make b immediate, but it fails to make a immediate.

Yeah, I had noticed that. It is easy enough to adjust (I think).

ebblake · 2025-08-10T03:11:46Z

ebblake
Aug 10, 2025
Author

Updated version:

\ This file is in the public domain. NO WARRANTY.

\ Originally designed by Eric Blake, August 2025,
\ with revisions inspired by ruv.

\ Add the word [IMMEDIATE] which can be used to mark the intent of defining
\ an immediate word sooner than waiting until the closing ;

\ The goal of this file is to permit the following:
\   : name [IMMEDIATE] ... ;
\ as syntax sugar for
\   : name ... ; IMMEDIATE
\ to satisfy the mantra "say what you are doing as soon as you can":
\ https://forth-standard.org/standard/core/IMMEDIATE#reply-313

\ First, note that there is an ambiguity observable between implementations
\ on the following code:
\    : foo ." foo " ;
\    : bar [ immediate ] ." bar " ;
\ where some implementations (gforth, SwitfForth, VFX) mark bar as
\ immediate, and others (iForth) mark foo as immediate.
\ https://forth-standard.org/standard/core/IMMEDIATE#contribution-112

\ Forth-2012 16.3.3 basically states that it is ambiguous if a program
\ modifies the compilation word list during compilation, but the purpose
\ of IMMEDIATE is to change the compilation list by making the latest
\ definition immediate.  So, regardless of whether : is required to make
\ the latest definition be the ongoing compilation, actually executing
\ IMMEDIATE before ; triggered ambiguous behavior.

\ At the same time, the standard requires this test to pass:
\   T{ : IW9 CREATE , DOES> @ 2 + IMMEDIATE ; -> }T
\   : FIND-IW BL WORD FIND NIP ;  ( -- 0 | 1 | -1 )
\   T{ 222 IW9 IW10 FIND-IW IW10 -> -1 }T   \ IW10 is not immediate
\   T{ IW10 FIND-IW IW10 -> 224 1 }T        \ IW10 becomes immediate
\ Basically, once the DOES> body is installed into iw10, then any future
\ execution of iw10 invokes IMMEDIATE on whatever happens to be the most
\ recently compiled word.  Furthermore, while not explicitly shown in
\ the test, it is worth noting that IW9 was not marked immediate; an
\ implementation where IMMEDIATE is immediate is unlikely to pass this
\ test, and an immediate word [IMMEDIATE] must be sure that actually
\ invoking IMMEDIATE does not happen before ; completes.
\ https://forth-standard.org/standard/testsuite#test:core:IMMEDIATE

\ Furthermore, the fact that IMMEDIATE has traditionally been non-immediate
\ means that there is an existing corpus of code that expects to be able
\ to build meta-programming words, such as:
\   : nop : POSTPONE ; IMMEDIATE ;
\   nop filler
\ which should make filler, rather than nop, be immediate.  This file does
\ not change that behavior.  Although this file does not declare imm:, it
\ also makes it easy to declare
\   : imm: ( "name" -- colon-sys ) : POSTPONE [IMMEDIATE] ;
\ as a way to write "imm: name" instead of ": name [IMMEDIATE]" for an
\ alternative way to declare intent of defining an immediate macro.

\ Implementations that provide other modifiers that affect the most recent
\ definition, such as compile-only or restrict, should be able to do similar
\ wrappers for those words to declare intent at the name of a definition.
\ Likewise, if you rely on the implementation-defined behavior of CODE or
\ ;CODE, you may want those words to have similar treatment to what this
\ file does for :.

\ Standard forth does not provide an easy interface to see if a given nt or
\ xt is immediate, although several implementations provide a word
\ "immediate?" for that purpose.  For debugging the effects of this file,
\ it is possible to write a parsing word that is portable:
\   \g Parsing word to display whether the next word is immediate.
\   [DEFINED] immediate? [IF] : imm ( "word" -- ) ' immediate? . ;
\   [ELSE] : imm BL WORD FIND NIP 1 = . ; [THEN]
\ And implementations that support SEARCH-WORDLIST can avoid the need to parse:
\   t{ S" [IMMEDIATE]" GET-CURRENT SEARCH-WORDLIST NIP 1 = -> TRUE }t

\ Dependencies:
\ Requires the following words from the Core word set
\  ! ( : ; ['] EXECUTE EXIT IF IMMEDIATE POSTPONE SWAP THEN VARIABLE
\ Requires the following words from the Core Extension word set
\  \ TRUE
\ Requires the following words from the Tools Extension word set
\  [DEFINED] [IF] [THEN] [UNDEFINED]

\ Compatibility stuff, inspired by gforth

\ document a word that is ambiguous to use outside of compilation semantics
[UNDEFINED] compile-only [IF] : compile-only ; [THEN]

\ specialized tag to distinguish documentation strings from internal comments
[UNDEFINED] \g [IF] : \g ['] \ EXECUTE ; IMMEDIATE [THEN]

\ convenience for altering the contents of a variable
[UNDEFINED] off [IF] : off 0 SWAP ! ; [THEN]
[UNDEFINED] on [IF] : on TRUE SWAP ! ; [THEN]

\ Implementation

\ Flag set when between : and ;
VARIABLE (defining) (defining) off
\ Flag set when ; needs to perform a delayed IMMEDIATE.
VARIABLE (needs-immediate) (needs-immediate) off

\ Wrap ; to honor (needs-immediate) and clear (defining).
: ; ( C: colon-sys -- )
  \g Complete a colon-sys after appending run-time semantics of
  \g ( R: nest-sys -- ) to the current definition.
  POSTPONE ;
  (needs-immediate) @ IF
    IMMEDIATE  \ uses original non-immediate word
    (needs-immediate) off
  THEN
  (defining) off
; IMMEDIATE compile-only

\ Wrap : to set (defining).
: : ( C: "<spaces>name" -- colon-sys )
  \g Begin a colon definition for /name/.
  :
  (defining) on
  (needs-immediate) off \ resest the flag after errors, if any
; IMMEDIATE

\ Provide [IMMEDIATE] which will trigger the effects of IMMEDIATE at the
\ next possible safe moment.
: [IMMEDIATE] ( -- )
  \g Make the most recent definition (whether a word currently being
  \g defined when between : and ;, or the word most recently defined
  \g when after ;) an immediate word.  Ambiguous if the current or
  \g most recent definition does not have a name, or was defined as
  \g a SYNONYM.
  (defining) @ IF (needs-immediate) on EXIT THEN  \ ; will do the job later
  IMMEDIATE  \ not currently between : and ;, so safe to do now
; IMMEDIATE

\ Optional: wrap :NONAME to reset the flag after erors, if any.  Since
\ IMMEDIATE is ambiguous if used after a :NONAME, [IMMEDIATE] is likewise
\ ambiguous if used within a :NONAME.
[DEFINED] :NONAME [IF]
: :NONAME ( -- xt colon-sys )
  \g Create an anonymous colon definition.
  :noname
  (needs-immediate) off
;
[THEN]

3 replies

This comment has been hidden.

Sign in to view

ebblake Aug 10, 2025
Author

Good idea. Current history at https://repo.or.cz/henceforth.git/history/90400b58dd362d4bf6bdfb9c942572ad19be99cc:/intcode/hence/immediate.fs
I'm in the process of seeing if I can separate this out into a new package to post on theforth.net

ruv Aug 10, 2025
Maintainer

@ebblake, you could edit your messages in this thread to fold the program code under some summary using <details> and <summary> tags, as I have done above. See Creating a collapsed section.

Also, you could use forth tag in starting code fragment to trigger syntax highlighting. See: Writing on GitHub / Syntax highlighting.

ebblake · 2025-08-10T12:16:48Z

ebblake
Aug 10, 2025
Author

And another revision to explicitly make [IMMEDIATE] a no-op when used between :NONAME and ;, in order to cater to Elkniwt's desire to write a definition body of ?: independent of whether ?: produces a name or anonymous setting.

Source code

\ This file is in the public domain. NO WARRANTY.

\ Originally designed by Eric Blake, August 2025,
\ with revisions inspired by ruv.

\ Add the word [IMMEDIATE] which can be used to mark the intent of defining
\ an immediate word sooner than waiting until the closing ;.

\ The goal of this file is to permit the following:
\   : name [IMMEDIATE] ... ;
\ as syntax sugar for
\   : name ... ; IMMEDIATE
\ to satisfy the mantra "say what you are doing as soon as you can":
\ https://forth-standard.org/standard/core/IMMEDIATE#reply-313

\ First, note that there is an ambiguity observable between implementations
\ on the following code:
\    : foo ." foo " ;
\    : bar [ immediate ] ." bar " ;
\ where some implementations (gforth, SwitfForth, VFX) mark bar as
\ immediate, and others (iForth) mark foo as immediate.
\ https://forth-standard.org/standard/core/IMMEDIATE#contribution-112

\ Forth-2012 16.3.3 basically states that it is ambiguous if a program
\ modifies the compilation word list during compilation, but the purpose
\ of IMMEDIATE is to change the compilation list by making the latest
\ definition immediate.  So, regardless of whether : is required to make
\ the latest definition be the ongoing compilation, actually executing
\ IMMEDIATE before ; triggered ambiguous behavior.

\ At the same time, the standard requires this test to pass:
\   T{ : IW9 CREATE , DOES> @ 2 + IMMEDIATE ; -> }T
\   : FIND-IW BL WORD FIND NIP ;  ( -- 0 | 1 | -1 )
\   T{ 222 IW9 IW10 FIND-IW IW10 -> -1 }T   \ IW10 is not immediate
\   T{ IW10 FIND-IW IW10 -> 224 1 }T        \ IW10 becomes immediate
\ Basically, once the DOES> body is installed into iw10, then any future
\ execution of iw10 invokes IMMEDIATE on whatever happens to be the most
\ recently compiled word.  Furthermore, while not explicitly shown in
\ the test, it is worth noting that IW9 was not marked immediate; an
\ implementation where IMMEDIATE is immediate is unlikely to pass this
\ test, and an immediate word [IMMEDIATE] must be sure that actually
\ invoking IMMEDIATE does not happen before ; completes.
\ https://forth-standard.org/standard/testsuite#test:core:IMMEDIATE

\ Furthermore, the fact that IMMEDIATE has traditionally been non-immediate
\ means that there is an existing corpus of code that expects to be able
\ to build meta-programming words, such as:
\   : nop : POSTPONE ; IMMEDIATE ;
\   nop filler
\ which should make filler, rather than nop, be immediate.  This file does
\ not change that behavior.  Although this file does not declare imm:, it
\ also makes it easy to declare
\   : imm: ( "name" -- colon-sys ) : POSTPONE [IMMEDIATE] ;
\ as a way to write "imm: name" instead of ": name [IMMEDIATE]" for an
\ alternative way to declare intent of defining an immediate macro.

\ The standard is clear that IMMEDIATE is ambiguous if used when the last
\ definition was via :NONAME or SYNONYM; this file does not remove that
\ ambiguity when there is no current definition (doing so would require
\ wrapping every defining word, which does not scale), so [IMMEDIATE] is
\ likewise ambiguous in those situations.  However, this file does ensure
\ that [IMMEDIATE] between :NONAME and ; is well-defined to do nothing.
\ The reason for this is so that it becomes easier to copy and paste a
\ definition body without regards to whether the definition was started
\ by ": name" or ":NONAME".

\ Implementations that provide other modifiers that affect the most recent
\ definition, such as compile-only or restrict, should be able to do similar
\ wrappers for those words to declare intent at the name of a definition.
\ Likewise, if you rely on the implementation-defined behavior of CODE or
\ ;CODE, you may want those words to have similar treatment to what this
\ file does for :.

\ Standard forth does not provide an easy interface to see if a given nt or
\ xt is immediate, although several implementations provide a word
\ "immediate?" for that purpose.  For debugging the effects of this file,
\ it is possible to write a parsing word that is portable:
\   \g Parsing word to display whether the next word is immediate.
\   [DEFINED] immediate? [IF] : imm ( "word" -- ) ' immediate? . ;
\   [ELSE] : imm BL WORD FIND NIP 1 = . ; [THEN]
\ And implementations that support SEARCH-WORDLIST can avoid the need to parse:
\   t{ S" [IMMEDIATE]" GET-CURRENT SEARCH-WORDLIST NIP 1 = -> TRUE }t

\ Dependencies:
\ Requires the following words from the Core word set
\  ! ( : ; ['] 0< ?DUP EXECUTE EXIT IF IMMEDIATE POSTPONE SWAP THEN VARIABLE
\ Requires the following words from the Core Extension word set
\  \ TRUE
\ Requires the following words from the Tools Extension word set
\  [DEFINED] [IF] [THEN] [UNDEFINED]

\ Compatibility stuff, inspired by gforth

\ document a word that is ambiguous to use outside of compilation semantics
[UNDEFINED] compile-only [IF] : compile-only ; [THEN]

\ specialized tag to distinguish documentation strings from internal comments
[UNDEFINED] \g [IF] : \g ['] \ EXECUTE ; IMMEDIATE [THEN]

\ convenience for altering the contents of a variable
[UNDEFINED] off [IF] : off 0 SWAP ! ; [THEN]
[UNDEFINED] on [IF] : on TRUE SWAP ! ; [THEN]

\ Implementation

\ Integer tracking whether there is an ongoing definition body.  1 after
\ :NONAME, -1 after :, and 0 after ;.
VARIABLE (defining) 0 (defining) !
\ Flag set when ; needs to perform a delayed IMMEDIATE.
VARIABLE (needs-immediate) (needs-immediate) off

\ Wrap ; to honor (needs-immediate) and clear (defining).
: ; ( C: colon-sys -- )
  \g Complete a colon-sys after appending run-time semantics of
  \g ( R: nest-sys -- ) to the current definition.
  POSTPONE ;
  (needs-immediate) @ IF
    IMMEDIATE  \ uses original non-immediate word
    (needs-immediate) off
  THEN
  (defining) off
; IMMEDIATE compile-only

\ Wrap : to delay [IMMEDIATE] by setting (defining).
: : ( C: "<spaces>name" -- colon-sys )
  \g Begin a colon definition for /name/.
  :
  -1 (defining) !
  (needs-immediate) off \ resest the flag after errors, if any
;

\ Wrap :NONAME to ignore [IMMEDIATE] by setting (defining).
[DEFINED] :NONAME [IF]
: :NONAME ( -- xt colon-sys )
  \g Create an anonymous colon definition.
  :NONAME
  1 (defining) !
  (needs-immediate) off \ resest the flag after errors, if any
;
[THEN]

\ Provide [IMMEDIATE] which will trigger the effects of IMMEDIATE at the
\ next possible safe moment.
: [IMMEDIATE] ( -- )
  \g Make the most recent definition (whether a word currently being
  \g defined when between : and ;, or the word most recently defined
  \g when after ;) an immediate word.  Ignored during the body of
  \g :NONAME, otherwise ambiguous if the most recent definition does not
  \g have a name, or was defined as a SYNONYM.
  (defining) @ ?DUP IF  \ inside : or :NONAME
    0< IF (needs-immediate) on THEN  \ delay during :, ignore during :NONAME
    EXIT THEN
  IMMEDIATE  \ not currently defining, so safe to do now
; IMMEDIATE

0 replies

ebblake · 2025-08-11T02:05:18Z

ebblake
Aug 11, 2025
Author

Now uploaded to https://theforth.net/package/immediate

0 replies

ruv · 2025-11-03T10:06:01Z

ruv
Nov 3, 2025
Maintainer

From /intcode/hence/immediate/README.md:

[IMMEDIATE] is explicitly a no-op in the body of :NONAME ;, in order to make it easier to copy-and-paste definitions without regards to whether the definition will be named or anonymous.

BTW, if we want to allow testing a definition body interactively (in REPL), [immediate] should probably be a no-op if the current definition does not exist. But then [immediate] cannot be used after ; to make the latest definition immediate.

0 replies

Demo of an immediate IMMEDIATE #197

Uh oh!

Uh oh!

Replies: 10 comments · 15 replies

Uh oh!

ebblake Aug 8, 2025 Author

Uh oh!

ebblake Aug 8, 2025 Author

Uh oh!

CCurl Aug 8, 2025 Maintainer

Uh oh!

Uh oh!

ruv Aug 9, 2025 Maintainer

Uh oh!

Uh oh!

ruv Aug 9, 2025 Maintainer

Uh oh!

ebblake Aug 9, 2025 Author

Uh oh!

ruv Aug 10, 2025 Maintainer

Uh oh!

Uh oh!

Uh oh!

ruv Aug 10, 2025 Maintainer

Uh oh!

Uh oh!

ruv Aug 10, 2025 Maintainer

Uh oh!

Uh oh!

Uh oh!

ruv Aug 10, 2025 Maintainer

Uh oh!

Uh oh!

ebblake Aug 10, 2025 Author

Uh oh!

Uh oh!

Uh oh!

ebblake Aug 10, 2025 Author

This comment has been hidden.

Uh oh!

ebblake Aug 10, 2025 Author

Uh oh!

ruv Aug 10, 2025 Maintainer

Uh oh!

Uh oh!

ebblake Aug 10, 2025 Author

Uh oh!

ebblake Aug 11, 2025 Author

Uh oh!

ruv Nov 3, 2025 Maintainer

Replies: 10 comments 15 replies

ebblake
Aug 8, 2025
Author

ebblake
Aug 8, 2025
Author

CCurl
Aug 8, 2025
Maintainer

ruv
Aug 9, 2025
Maintainer

ruv Aug 9, 2025
Maintainer

ebblake
Aug 9, 2025
Author

ruv Aug 10, 2025
Maintainer

ruv Aug 10, 2025
Maintainer

ruv Aug 10, 2025
Maintainer

ruv Aug 10, 2025
Maintainer

ebblake Aug 10, 2025
Author

ebblake
Aug 10, 2025
Author

ebblake Aug 10, 2025
Author

ruv Aug 10, 2025
Maintainer

ebblake
Aug 10, 2025
Author

ebblake
Aug 11, 2025
Author

ruv
Nov 3, 2025
Maintainer