20070607 Wordsmithing. Corrected reference implementation.
20060822 Added explanatory text.
          Corrected reference implementation.
          Updated ambiguous conditions.

Problem
=======
1) The current LOCALS| ... | notation explicitly forces all locals
    to be initialised from the data stack.
2) The current LOCALS| ... | notation defines locals in reverse
    order to the normal stack notation.
3) When programming large applications, especially those interfacing
    with a host operating system, there is a frequent need for temporary
    buffers.
4) Current implementations show that creation and destruction of
    local buffers are much faster than using ALLOCATE (14.6.1.0707)
    and FREE (14.6.1.1605).

Solution
========
Base version
------------
The following syntax for local arguments and local variables is
proposed. The sequence:

   { ni1 ni2 ... | lv1 lv2 ... -- o1 o2 ... }

defines local arguments, local variables, and outputs. The local
arguments are automatically initialised from the data stack on
entry, the rightmost being taken from the top of the data stack.
Local arguments and local variables can be referenced by name within
the word during compilation. The output names are dummies to allow
a complete stack comment to be generated.

The items between { and | are local arguments.
The items between | and -- are local variables or buffers.
The items between -- and } are outputs for formal comments only.

The outputs are provided in the notation so that complete stack
comments can be produced. However, all text between -- and } is
ignored. The facility is there to permit the notation to form a
complete stack comment. This eases documentation and current
users of the notation like this facility.

Local arguments and variables return their values when referenced,
and must be preceded by TO to perform a store.

Local buffers may be defined in the form:

   arr[ <expr> ]

Any name ending in the '[' character will be treated as a buffer,
the expression up to the terminating ']' will be interpreted to
provide the size of the buffer. Local buffers only return their base
address, all operators such as TO generate an ambiguous condition.

In the example below, a and b are local arguments, a+b and a*b are
local variables, and arr[ is a 10 byte local buffer.

: foo  { a b | a+b a*b arr[ 10 ] -- }
   a b + to a+b
   a b * to a*b
   cr a+b .  a*b .
   arr[ 10 erase
   s" Hello" arr[ swap cmove
;

Local types
-----------
Some current Forth systems use indicators to define local variables
of sizes other than a cell. It is proposed that any name ending in a ':'
(colon) be reserved for this use.

: foo  { a b | F: f1 F: f2 -- c }
   ...
;

Discussion
==========
The '|' (ASCII 0x7C) character is widely used as the separator
between local arguments and local variables. Other characters
accepted in current Forth implementations are '\' (ASCII 0x5C) and
'¦' (ASCII 0xA6).. Since the ANS standard is defined in terms of
7 bit ASCII, and with regard to internationalisation, we propose only
to consider the '|' and '\' characters further. Only recognition of
the '|' separator is mandatory.

The use of local types is contentious as they only become useful
if TO is available for these. In practice, some current systems
permit TO to be used with floats (children of FVALUE) and other
data types. Such systems often provide additional operators such
as +TO (add from stack to item) for children of VALUE and FVALUE.
Standardisation of operators with (for example) floats needs to
be done before the local types extension can be incorporated into
Forth200x. Apart from forcing allocation of buffer space, no
additional functionality is provided by local types that cannot
be obtained using local buffers. More preparatory standardisation
needs to be done before local types can be standardised.

Apart from { (brace) itself, the proposal introduces one new
word BUILDLV. The definition of this word is designed for future
enhancements, e.g. more local data types, without having to
introduce more new words.

It has been noted that one widely used implementation uses brace
for multi line comments. However, inspection of the vendor's code
shows that this use only occurs during interpretation. The
interpretation semantics of brace in this proposal are undefined
in order for that implementation to coexist with this proposal.

Proposal
========

13.3 and 13.4
Add "and BUILDLV" where (LOCAL) is referenced.

13.6.2.xxxx {
brace LOCAL EXT

Interpretation: Interpretation semantics for this word are undefined.

Compilation:
( "<spaces>arg1" ... "<spaces>argn" | "<spaces>lv1" ... "<spaces>lvn" -- )

Create up to eight local arguments by repeatedly skipping leading
spaces, parsing arg, and executing 13.6.2.yyyy BUILDLV. The list of
local arguments to be defined is terminated by "|", "--" or "}".
Append the run-time semantics for local arguments given below to the
current definition. If a space delimited '|' is encountered, create
up to eight local variables or buffers by repeatedly skipping
leading spaces, parsing lv, and executing 13.6.2.yyyy BUILDLV. The
list of local variables and buffers to be defined is terminated by
"--" or "}". Append the run-time semantics for local variables and
local buffers given below to the current definition. If "--" has
been encountered, further text between  "--" and } is ignored.

Local buffers have names that end in the '[' character. They define
their size by parsing the text string up to the next ']' character,
and passing that string to 7.6.1.1360 EVALUATE to obtain the size
of the storage in address units.

Local argument run-time: ( x1 ... xn -- )
Local variable run-time: ( -- )
Local buffer run-time: ( -- )

Initialize up to eight local arguments as described in 13.6.2.yyyy
BUILDLV. Local argument arg1 is initialized with x1, arg2 with x2 up
to argn from xn, which is on the top of the data stack. When
invoked, each local argument will return its value. The value
of a local argument may be changed using 13.6.1.2295 TO.

Initialize up to eight local variables or local buffers as described
in 13.6.2.yyyy BUILDLV. The initial contents of local variables and
local buffers are undefined. When invoked, each local variable
returns its value. The value of a local variable may be changed
using 13.6.1.2295 TO. The size of a local variable is a cell.
When invoked, each local buffer will return its address. The user
may make no assumption about the order and contiguity of local
variables and buffers in memory.

Ambiguous conditions:
a) The { ... } text extends over more than one line.
b) The expression for local buffer size does not return a single
    cell.
c) { ... } is declared more than once in a word.
d) Parsing units '|', ']', '--' and '}' are not white space delimited.

13.6.2.yyyy BUILDLV
build-l-v LOCAL EXT

Interpretation: Interpretation semantics for this word are undefined.

Execution: ( c-addr u +n mode -- )
When executed during compilation, BUILDLV passes a message to the
system identifying a new local argument whose definition name is
given by the string of characters identified by c-addr u. The size
of the data item is given by +n address units, and the mode
identifies the construction required as follows:
     0 - finish construction of initialisation and data storage
         allocation code. C-addr and u are ignored. +n is 0
         (other values are reserved for future use).
     1 - identify a local argument, +n = cell
     2 - identify a local variable, +n = cell
     3 - identify a local buffer, +n = storage required.
    4+ - reserved for future use
   -ve - implementation specific values

The result of executing BUILDLV during compilation of a definition
is to create a set of named local arguments, variables and/or
buffers, each of which is a definition name, that only have
execution semantics within the scope of that definition's source.

local argument execution: ( -- x )
Push the local argument's value, x, onto the stack. The local
argument's value is initialized as described in 13.6.2.xxxx { and may be
changed by preceding the local argument's name with TO.

local variable execution: ( -- x )
Push the local variable's value, x, onto the stack. The local
variable is not initialised. The local variable's value may be
changed by preceding the local variable's name with TO.

local buffer execution: ( -- a-addr )
Push the local buffer's address, a-addr, onto the stack. The address
is aligned as in 3.3.3.1. The contents of the buffer are not
initialised.

Note: This word does not have special compilation semantics in the
usual sense because it provides access to a system capability for
use by other user-defined words that do have them. However, the
locals facility as a whole and the sequence of messages passed
defines specific usage rules with semantic implications that are
described in detail in section 13.3.3 Processing locals.

Note: This word is not intended for direct use in a definition to
declare that definition's locals. It is instead used by system or
user compiling words. These compiling words in turn define their
own syntax, and may be used directly in definitions to declare
locals. In this context, the syntax for BUILDLV is defined in terms
of a sequence of compile-time messages and is described in detail
in section 13.3.3 Processing locals.

Note: The LOCAL EXT word set modifies the syntax and semantics of
6.2.2295 TO as defined in the Core Extensions word set.

See: 3.4 The Forth text interpreter

Ambiguous conditions:
   a local argument, variable or buffer is executed while in
   interpretation state.

Reference implementation
=========================
(currently untested)

: TOKEN         \ -- caddr u
\ Get the next space delimited token from the input stream.
   BL PARSE
;

: LTERM?        \ caddr u -- flag
\ Return true if the string caddr/u is "--" or "}"
   2DUP S" --" COMPARE 0= >R
   S" }" COMPARE 0=  R> OR
;

Also, extending TO to support FP locals is easy with the proposed
rewording of TO.

If you mean operators like TO, and you don't want to propose it, don't
do it; I'm sure Marcel Hendrix will step up.  If you want to propose
TO for FP locals, I don't see any hurdle.

--
Coos

    bufname[

where   [  is stripped off, leaving the actual name  'bufname'

That's contrary to forth practice where names are space delimited.
The first time I saw this syntax being used, I thought there existed
a word in the dictionary called  'bufname['  but try as I might I could
not find it.

" Variable: a named region of data space located and accessed by its
memory address."

The proposed local variables do not do that and so should be called
local values.

I know this is nit picking but a standard needs its nits to be picked.

        20 buffer: bufname      or      bufname [ 20 ALLOT ]

both of which would make the parsing of locals considerably more complex.

As we are talking about a standard, we have to consider what already
exists, not what we would like to exist. There are systems out there
which have been using the bufname[ 20 ] format for many years.

Let's see ..

        bufname buffer 20
or      
        bufname [] 20

or      bufname [ 20 CELLS ]

.. where buffer, [] or [ is recognized by LOCALS| and executed instead of made
into a local. The BUFFER modifier word would then simply modify the allocation
size of the latest local.

I don't see that '[' would make the locals parser 'considerably more complex.'

: BUFFER: ( n -- )   CREATE ALLOT ;

Trivial syntactic sugar, to be sure, but widely used and very popular.

Cheers,
Elizabeth

--
==================================================
Elizabeth D. Rather   (US & Canada)   800-55-FORTH
FORTH Inc.                         +1 310-491-3356
5155 W. Rosecrans Ave. #1018  Fax: +1 310-978-9454
Hawthorne, CA 90250
http://www.forth.com

    [ alignment/size ]  name

Given the parser is already looking for a delimiter/operator e.g.  --  }
then adding  [  should not be difficult?

: LB?           \ caddr u -- flag
   S" [" COMPARE 0=
;

This RfD and the solutions discussed elsewhere in this thread lead me
to conclude that, as LOCALS (both { and LOCALS|) already demand an
alternative parse to the traditional Forth parse of find and compile,
neither is amenable to further simple expansion due to the
increasingly bizarre extensions of syntax being put forward. I would
prefer to see a straightforward and clean parse based, as far as is
possible, on the current Forth model, and not a parse that /by design/
requires alternative meanings or special syntaxes for standard Forth
words that are not available outside of LOCALS use (i.e. [ n ] ARR or
ARR[ n ] for CREATE ARR n ALLOT; or f: for FLOAT values).

I realise that Win32Forth is guilty of the use of trailing : for OOP
class methods, and [ ] for late binding; that's a feature of NEON/MOPS
that I, for one, dislike, as it makes complex something that should be
simple. This proposal on a NEON/MOPS system would allow

: f: { f: seconds | } seconds f: rocket ;

Three seperate meanings of f: (a word, a float definition and a method
invocation respectively). Even on simpler, non-NEON/MOPS systems,
there would be two meanings. Best not to repeat that mistake.

I believe { } needs abandoned as a standards proposal, or fixed in its
current usage, and some other design should take its place. I can't
support this RfD in its current form, nor the alternative proposals it
has spawned.

I think the Neon stuff is a mistake, because AFAIK one cannot tick or
POSTPONE the words ending in ":".

In that sense locals are a mistake irrespective of syntax, because you
cannot tick or POSTPONE a local.  However, since locals are just a
convenience for stuff that one can also do without too much ado in
other ways (i.e., using the stacks), this has not turned out to be a
problem (I never find myself wishing that I could tick or POSTPONE a
local).

Concerning the { syntax, one can POSTPONE { itself; this is a parsing
word, so if one cannot also POSTPONE the stuff it parses, that's
nothing unusual.

: SWAP SWAP ;

and the two occurences of SWAP have different meanings.

AFAIK, at the moment '{' is not standard, so I am amazed to get such heavy
flak each time I for once decide to use a standard Forth construct :-)

[ I do not complain that F: is missing in the proposal because I do not
  like the looks of it. I remember how to use things by reconstructing how
  they work (This means I never learned to tie my shoelaces properly because
  the Kindergarten teacher didn't succeed in explaining the mathematics,
  the WHY, of this fantastic trick to me). For me, there is no logic in the '{'
  proposal because local initializers must be popped off the stack, which
  means the logical arrangement of names is first-local-connects-to-TOS.
  Floats are on a different stack, so they shouldn't mix with integer locals.
  Besides that, I have many more types of locals (complex, double-double,
  long integer, strings). I could start using '{', but it wouldn't make
  my code portable. ]

In eForth64 I have now added the line:

: PARAMS| ( "names |" -- )
        lp@ @ >S
        ['] (LOCAL) 1 MAKE-LOCALS  
        S> INIT-LOCALS2, ; IMMEDIATE

... and as soon as the standard is final I will do a SYNONYM (or something)
and create a '{' for those programmers that absolutely need it.

Don't take it from this a request for a veto. It's right that a simple
majority should suffice to carry an RfD.

During the Forth94 process we required all proposals that had more than
2 'no' votes to go back to committee for resolution.  Broad consensus is
required to ensure that there really will be widespread support for a
feature or rule and that all viewpoints have been considered.  The only
issue on which the Forth94 TC failed to get consensus was locals: we
struggled with them for years, and ended up deadlocked on the issue of
the order in which things were removed from the stack.  By one vote we
chose to follow the only existing widespread usage (MacForth) and folks
have been unhappy ever since.

No proposal that doesn't have really broad consensus should be adopted.

Cheers,
Elizabeth

--
==================================================
Elizabeth D. Rather   (US & Canada)   800-55-FORTH
FORTH Inc.                         +1 310-491-3356
5155 W. Rosecrans Ave. #1018  Fax: +1 310-978-9454
Hawthorne, CA 90250
http://www.forth.com