Value and Local Variable Words

Full builds of zeptoforth include support for value and 2value along with local variables. Unlike variable and 2variable, value and 2value variables are initialized, and retain their initialization across reboots. values, 2values, and local variables are all set with to or added to with +to, which are state-smart words that can be used both in interpretation and in compilation mode.

Note that local variables are lexically scoped, and are safe to use within if … then, if … else … then, begin … until, begin … while … repeat, begin … again, case … endcase/endcasestr, of/ofstr/ofstrcase … endof, and do/?do … loop/+loop constructs. Local variables declared between these words are not accessible outside them, and do not retain their values between multiple iterations.

All of these words are in the default forth module.

Values

value

( x “name” – )

This compiles a word name for a single-cell value which is initialized to x, immediately when compiling to RAM and upon boot when compiling to flash. name evaluates to its current value when executed. to may be used to change the value of name at runtime, but this value reverts to the initialization value upon bootup for values compiled to flash.

2value

( d “name” – )

This compiles a word name for a double-cell value which is initialized to d, immediately when compiling to RAM and upon boot when compiling to flash. name evaluates to its current value when executed. to may be used to change the value of name at runtime, but this value reverts to its initialization value upon bootup for values compiled to flash.

Local Variables

{

( [“W:” / “W^” / “D:” / “D^”] “xn” … [“W:” / “W^” / “D:” / “D^”] “x0” [ “–” … ] “}” – )

This compiles a set of single-cell and/or double-cell local variables, declared with either W: or W^ (or no local variable type marker), or D: or D^, preceding the variable name, respectively, within a word that at runtime take their values off the top of the stack, with x0 (the last local variable declared) taking its value off the very top of the stack. Local variable declarations can extend across multiple lines. } declares the end of a local variable declaration. -- within a local variable declaration declares a comment that extends, across multiple lines, until } is reached. After this point each of these local variables either evaluate to their set values, if declared with W:, D:, or nothing at all, or to their addresses on the return stack, if declared with W^ or D^, until containing code block is completed. to may be used to change the values of these local variables after they are declared. Local variables may be used within quotations declared with [: and ;], including if local variables are used within the containing word, and are properly discarded when exit is used within a word. They can be used alongside do loops but are not compatible with the use of >r, r@, or r>.

Setting Values and Local Variables

to

( x|d “name” – )

This sets a value or local variable name to either a single-cell or double-cell on the stack depending on whether name refers to a value, 2value, a single-cell local variable, or a double-cell local variable. This is state smart, and can be used both in interpretation mode and in compilation mode.

+to

( x|d “name” – )

This adds a single-cell or double-cell on the stack to a value or local variable name depending on whether name refers to a value, 2value, a single-cell local variable, or a double-cell local variable. This is state smart, and can be used both in interpretation mode and in compilation mode.