5.21.2 Standard Forth locals

The Forth-2012 standard defines a syntax for locals, that is similar to a subset of Gforth locals. Instead of using { and }, the standard decided to use {: and :}, as shown in the following examples:

{: local1 local2 ... -- comment :}

or

{: local1 local2 ... | local3 local4 ... -- comment :}

where local3 and local4 are uninitialized or

{: local1 local2 ... :}

The order of the locals corresponds to the order in a stack comment. The restrictions are:

• Locals can only be cell-sized values (no type specifiers are allowed).
• Locals can be defined only outside control structures.
• Locals can interfere with explicit usage of the return stack. For the exact (and long) rules, see the standard. If you don’t use return stack accessing words in a definition using locals, you will be all right. The purpose of this rule is to make locals implementation on the return stack easier.
• The whole definition must be in one line.

Locals defined in Standard Forth behave like VALUEs (see Values). I.e., they are initialized from the stack. Using their name produces their value. Their value can be changed using TO.

Since the syntax above is supported by Gforth directly, you need not do anything to use it. If you want to port a program using this syntax to another ANS Forth system, use compat/anslocal.fs to implement the syntax on the other system.

Note that a syntax shown in the standard, section A.13 looks similar, but is quite different in having the order of locals reversed. Beware!

The Standard Forth locals wordset itself consists of two words:

(local) ( addr u –  ) local “paren-local-paren”

{: ( – hmaddr u latest latestnt wid 0  ) forth-2012 “open-brace-colon”

Start standard locals declaration. All Gforth locals extensions are supported by Gforth, though the standard only supports the subset of cells.

The ANS Forth locals extension wordset defines a syntax using locals|, but it is so awful that we strongly recommend not to use it. We have implemented this syntax to make porting to Gforth easy, but do not document it here. The problem with this syntax is that the locals are defined in an order reversed with respect to the standard stack comment notation, making programs harder to read, and easier to misread and miswrite. The only merit of this syntax is that it is easy to implement using the ANS Forth locals wordset.