RfD - Local buffers, v4
=======================
Stephen Pelc - 14 September 2007

20080811 Brought into line with LocalsExt4.txt.
20070914 Split local buffers to a separate proposal.

Problem
=======
When programming large applications, especially those
interfacing
with a host operating system, there is a frequent need for
temporary
buffers. This proposal is an extension to the extended locals
proposal, on which this proposal depends.

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).

This proposal is derived from implementations that have existed
for
more than 15 years.

Solution
========
The following syntax for local arguments and local values is
proposed elsewhere. The sequence:
{ ni1 ni2 ... | lv1 lv2 ... -- o1 o2 ... }
defines local arguments, local values, 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 values 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 values.
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 values return their values when referenced,
and must be preceded by TO to perform a store.

In the local value region, local buffers may be defined in the
form:
[ <expr> ] lbuff
At least one existing implementation uses the form:
lbuff[ <expr> ]
where any name ending in thr '[' character indicates a local
buffer. To prevent conflict, we define names ending in '[' as
being an ambiguous condition.

Any name preceded by '[ <expr> ]' will be treated as a buffer
whose
size is given by the result of interpreting the expression.
Local buffers return their base address, all operators such as
TO
are an ambiguous condition.

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

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

Forth 200x text
===============
Replace the text for 13.6.2.xxxx { as follows:

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 implementation defined
actions.
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 values or buffers by repeatedly
skipping
leading spaces, parsing the "lv" token, and creating the local
element. The list of local values and buffers to be defined is
terminated by "--" or "}". Append the run-time semantics for
local
values and local buffers given below to the current definition.
If "--" has been encountered, further text between "--" and }
is
ignored.

Local buffers are declared in the form:
[ <expr> ] lbuff
They expression between the whitespace delimited ']' and the
closing ']' is parsed, and pass to 7.6.1.1360 EVALUATE to obtain
the size of the storage in address units.

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

Initialise up to eight local arguments from the data stack.
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.

Initialise up to eight local values or local buffers. The
initial contents of local values and local buffers are
undefined.
When invoked, each local value returns its value. The contents
of
a local value may be changed using 13.6.1.2295 TO. The size of a
local value is a cell. When invoked, each local buffer will
return
its address. The user may make no assumption about the order and
contiguity of separate local values 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 whitespace
delimited.
2) A local argument, value or buffer name ends in the '['
character.

See: 3.4 The Forth text interpreter

Ambiguous conditions:
a local argument, value or buffer is executed while in
interpretation state.
TO is applied to a local buffer.


Reference implementation
=========================

0 [if]
This implementation supports the existing notation as well as
that of the proposed standard. This is done to prevent breaking
existing code.

BUILDLV 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 value, +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, values and/or
buffers, each of which is a definition name, that only have
execution semantics within the scope of that definition's
source.
[then]

: BUILDLV \ c-addr u +n mode --
\ Dummy for testing
CR 2SWAP TYPE SPACE SWAP . .
;

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

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

: LBSIZE \ -- +n
\ Parse up to the terminating ']' and EVALUATE the expression
\ not including the terminating ']'.
POSTPONE [ [CHAR] ] PARSE EVALUATE ]
;

: LB? \ caddr u -- flag
\ Return true if the last character of the string is '['.
+ 1 CHARS - C@ [CHAR] [ =
;

: LSEP? \ caddr u -- flag
\ Return true if the string caddr/u is the separator between
\ local arguments and local values or buffers.
2DUP S" |" COMPARE 0= >R
S" \" COMPARE 0= R> OR
;

: {
1 >R
BEGIN
TOKEN 2DUP LTERM? 0=
WHILE
2DUP LSEP? IF
2DROP R> DROP 0 >R
ELSE
R@ IF
1 CELLS 1
ELSE
2DUP S" [" COMPARE 0= IF
2DROP LBSIZE TOKEN ROT 3
ELSE
2DUP LB? IF
1- LBSIZE 3
ELSE
1 CELLS 2
THEN
THEN
THEN
BUILDLV
THEN
REPEAT
BEGIN
S" }" COMPARE
WHILE
TOKEN
REPEAT
0 0 0 0 BUILDLV
R> DROP ; IMMEDIATE

: TEST1 { a | b c[ 66] [ 77] d e -- f }
CR ." Hello1 " CR ;

TEST1

CR .( swapping c and d ) CR

: TEST2 { a | b [ 77] d c[ 66] e -- f }
CR ." Hello2 " CR ;

TEST2

--
Stephen Pelc, stephen@...
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web: http://www.mpeforth.com - free VFX Forth downloads