Authors
=======
Peter Knaggs
Anton Ertl


Change History
==============
2006-10-07
Spelling and Grammar Corrections.
Added Comments.

2006-09-30 First Public Draft.


Problem
=======

There are a number of proposals (FVALUE, 2VALUE, possibly
extended locals) which extend the operation of the word
TO. They take the definition of 13.6.1.2295 TO from the LOCAL
word set as their example. The new proposals then provide two
more definitions of TO, one with and one without locals.
Eventually, for n new proposals that extend TO, this would
lead to 2^(n+1) definitions of TO, one for each possible
subset of features that the system implemented. (Actually,
VALUE is also an optional word, so there should also be
variants of TO that cater for the possible absence of VALUE,
increasing the number of possible TO definitions to
2^(n+2).)

This approach is clearly impractical, so this proposal rewords
the definition of TO and related words in a more modular way.

We also clarify whether TO can be ticked, it should not.

Solution
========

Rewrite the definition of TO in a generic way. The behaviour
specific to each defining word is given in a section "TO
/name/ run-time" in the specification of the defining word.
So, e.g., a proposal for FVALUE can extend TO by just putting
such a section in the specification of FVALUE.

The text we propose should not alter the operation of VALUE,
(LOCAL) or TO, but moves the definition of the run-time action
in the document. Neither standard programs nor standard
systems should be affected.

The present proposal also makes it explicit that TO cannot be
ticked. This is in line with the intention of the ANS Forth
TC's intention to allow STATE-smart implementations of TO. It
may already be present implicitly in the ANS Forth document,
through the absence of an execution semantics for TO, but we
choose to make it explicit for increased clarity.

We have also changed the rationale text with respect to
whether mode-flag implementations can be compatible with the
specification (both the old one and the new one). We failed
to come up with a scenario where a standard program would fail
on a appropriately constructed mode-flag system; the original
rationale mentioned using TO at the end of the parse area, but
a standard program does not do that, so that is not an issue.

Procedure
=========

Because this proposal is intended to be just a wording change
that does not change the normative content of the standard, it
makes no sense to perform a poll among system implementors and
programmers whether they are going to implement/use the
proposal. Therefore, after the proposal has been discussed in
the RfD stage, it will be frozen and directly passed on to the
Forth200x committee. However, please do read the proposal and
comment on it, especially if you see a change in normative
content.

Proposal
========

1) Replace the existing definition of 6.2.2295 TO with the following:

6.2.2295 TO CORE EXT

Interpretation: ( i*x ``<spaces>name'' -- )

Skip leading spaces and parse /name/ delimited by a
space. Perform the TO /name/ run-time semantics given
in the definition for the defining word of /name/.

Compilation: ( ``<spaces>name'' -- )

Skip leading spaces and parse /name/ delimited by a
space. Append the run-time semantics given in the
definition for the defining word of /name/ to the
current definition.

Note: An ambiguous condition exists if any of POSTPONE,
[COMPILE] ' or ['] is applied to TO.

An ambiguous condition exists if /name/ was not
defined by a word which has a TO /name/ run-time
semantics.

See: 6.2.2405 VALUE, 13.6.1.0086 (LOCAL).

Rationale:
Some implementations of TO parse, and some only set
a mode flag that is then tested by /name/. ANS Forth
specifies that TO parses, allowing parsing
implementations of TO to be standard. Mode-setting
implementations can also be standard; however, note
that /name/ must not be state-smart.

Typical use: x TO /name/

See A.6.2.2295 VALUE for testing.

2) Replace the existing definition of 6.2.2405 VALUE with the following:

6.2.2405 VALUE CORE EXT
( /x/ ``<spaces>name'' -- )

Skip leading space delimiters. Parse /name/ delimited
by a space. Create a definition for /name/ with the
execution semantics given below, with an initial value
equal to /x/.

/name/ Execution: ( -- /x/ )

Place /x/ on the stack. The value of /x/ is that given
when /name/ was created, until the phrase /x/ TO /name/
is executed, causing a new value of /x/ to be associated
with /name/.

TO /name/ Run-Time: ( /x/ -- )

Associate the value /x/ with /name/.

See: 3.4.1 Parsing and 6.2.2295 TO.

Rationale:
Typical use:
0 VALUE data

: EXCHANGE ( n1 -- n2 )
data SWAP TO data
;

EXCHANGE leaves n1 in data and returns the prior value
n2.

Testing:

{ 0 VALUE Tval -> }
{ Tval -> 0 }

{ 1 TO Tval -> }
{ Tval -> 1 }

: SETTval Tval SWAP TO Tval ;
{ 3 SETTval Tval -> 1 3 }


3) Replace the following note at the end of the definition of
13.6.1.0086 (LOCAL):

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

with the following description of the TO /local/ run-time semantics:

TO /local/ Run-Time: ( /x/ -- )
Associate the value /x/ with the local value /local/.


4) Remove the definition 13.6.1.2295 TO. It is no longer required, as
6.2.2295 no longer requires extension.


5) In the definition 13.6.2.1795 LOCALS| the reference to 13.6.1.2295
TO should be replaced with a reference to 6.2.2295 TO.


6) The ambiguous condition "/name/ not defined by VALUE or (LOCAL)
(13.6.1.2295 TO)" in section 13.4.1.2 *Ambiguous conditions* is no
longer required. The ambiguous condition that TO can not be used
on a definition which does not define a TO /name/ run-time
semantics, in the new 6.2.2295 TO is sufficient.


7) In 4.1.2, replace the ambiguous conditions:

- /name/ not defined by 6.2.2405 VALUE used by 6.2.2295 TO;

- 6.1.2033 POSTPONE or 6.2.2530 [COMPILE] applied to 6.2.2295 TO;

with:

- /name/ not defined by a word which has a TO /name/ run-time
semantics (6.2.2295 TO);

- 6.1.2033 POSTPONE, 6.2.2530 [COMPILE], 6.1.0070 ' or 6.1.2510
['] applied to 6.2.2295 TO;


Comments
========

Ignoring the comments relating to the spelling and grammar of
the original posting.

Mitch Bradley felt that the proposal "looks good to me".


Julian V. Noble feels that rather than over-complicating TO and
changing an existing definition, it would be better to introduce
the variant FTO for things like FVALUEs and FLOCALs. Otherwise,
you have to have the entity (that is being stored to) know its
own type and proclaim it when TO executes. Whilst this is
possible, it swims somewhat against the natural Forth untyped
current.

The proposal does not add any further word types (FVALUEs or
whatever) for TO to handle. Moreover, systems exist that have
implemented FVALUEs and have extended TO to deal with them, this
shows that it can be done. In addition TO is already required to
discover the type of its target, is it a VALUE or a LOCAL?

It should be noted that entities have always know their own
type. When CREATE DOES> is used in a defining word, a new
entity type is defined. The child of such a defining word knows
its own type, it is implicit in the DOES> clause of the creator.

This proposal is saying that defining words which wish to use
the TO prefix operator are required to define the effect of
preceding the child entity with the TO prefix. It does not
specify how the TO prefix is passed to the child entity, that
is left to the system implementor. It does however require that
words wanting to use the TO prefix document the effect of using
the prefix in the definition of the defining word.


Hans Bezemer supports Julian Noble's view saying that Forth has
always been aware of the type of its operators, considering +,
D+, F+, etc. If we abandon it here for TO, consequently we must
be abandoning it for all other type aware words (since the
approach seems viable). TO will be a monster and DTO and FTO
seem a much better idea.

Andrew Haley pointed out that originally TO was simply a switch
that affected the action of the following word. The compile-
time action of TO is, by that means, distributed throughout all
the different kinds of VALUEs. That's a good idea: it
simplifies everything. There's no need for TO to have any type
at all.

While Doug Hoffman notes that D+, F+, etc are not the same
thing. For example, if we tried to make + work for floats as
well as integers, how would + know from which stack to pull its
arguments?

He pointed out that this approach would advocate VTO and LTO to
differentiate between VALUEs and LOCALs? So then we would also
have +VTO +LTO FTO LFTO (local floats) +FTO +LFTO. Eight words
that could be replaced with two ( TO and +TO ). He would prefer
two words instead.

Whilst this proposal does not include additional prefix
operators, it does not forbid them. Indeed systems exist which
have implemented additional prefix operators such as +TO, -TO,
++, --, and PRINT.