5.12.1 Literals

The simplest and most frequent example is to compute a literal during compilation. E.g., the following definition prints an array of strings, one string per line:

     : .strings ( addr u -- ) \ gforth
         2* cells bounds U+DO
     	cr i 2@ type
         2 cells +LOOP ;

With a simple-minded compiler like Gforth's, this computes 2 cells on every loop iteration. You can compute this value once and for all at compile time and compile it into the definition like this:

     : .strings ( addr u -- ) \ gforth
         2* cells bounds U+DO
     	cr i 2@ type
         [ 2 cells ] literal +LOOP ;

[ switches the text interpreter to interpret state (you will get an ok prompt if you type this example interactively and insert a newline between [ and ]), so it performs the interpretation semantics of 2 cells; this computes a number. ] switches the text interpreter back into compile state. It then performs Literal's compilation semantics, which are to compile this number into the current word. You can decompile the word with see .strings to see the effect on the compiled code.

You can also optimize the 2* cells into [ 2 cells ] literal * in this way.

[       –         core       “left-bracket”

Enter interpretation state. Immediate word.

]       –         core       “right-bracket”

Enter compilation state.

Literal       compilation n – ; run-time – n         core       “Literal”

Compilation semantics: compile the run-time semantics.
Run-time Semantics: push n.
Interpretation semantics: undefined.

]L       compilation: n – ; run-time: – n         gforth       “]L”

equivalent to ] literal

There are also words for compiling other data types than single cells as literals:

2Literal       compilation w1 w2 – ; run-time  – w1 w2         double       “two-literal”

Compile appropriate code such that, at run-time, w1 w2 are placed on the stack. Interpretation semantics are undefined.

FLiteral       compilation r – ; run-time – r         float       “f-literal”

Compile appropriate code such that, at run-time, r is placed on the (floating-point) stack. Interpretation semantics are undefined.

SLiteral       Compilation c-addr1 u ; run-time – c-addr2 u         string       “SLiteral”

Compilation: compile the string specified by c-addr1, u into the current definition. Run-time: return c-addr2 u describing the address and length of the string.

You might be tempted to pass data from outside a colon definition to the inside on the data stack. This does not work, because : puhes a colon-sys, making stuff below unaccessible. E.g., this does not work:

     5 : foo literal ; \ error: "unstructured"

Instead, you have to pass the value in some other way, e.g., through a variable:

     variable temp
     5 temp !
     : foo [ temp @ ] literal ;