Document: Specifications of words proposed by MLG for inclusion into the standard
Author: Michael L. Gassanenko

Words Proposed for Inclusion into the Standard

(Proposed does not mean approved)

The purpose of this document is to let Forth implementors and programmers know words that I found useful in my practice. To keep this article small, I has left the discussion out; nevertheless, if you want to know my argumentation, you can follow the "full text" reference in each section.

Contents

Add the words N>R NR> to the CORE EXT word set

full text

Add the words N>R NR> to the CORE EXT word set

Inclusion of words N>R and NR> into the standard would compensate the lack of means to manipulate with "counted arrays" left on the data stack by SAVE-INPUT and GET-ORDER (as well as proposed SAVE-SECTIONS). 

N>R                                     "n-to-r"    CORE EXT
( xn ... x1 n -- ) ( R: -- x1 ... xn n )
Take n off the data stack. Repeat n times: move the top data stack item to the return stack. After that, place n onto the return stack. 

NR>                                     "n-r-from"  CORE EXT
( -- xn ... x1 n ) ( R: x1 ... xn n -- )
Take n off the return stack. Repeat n times: move the top return stack item to the data stack. After that, place n onto the data stack.

Add the word NDROP to the TOOLS EXT word set

 full text (there was a typo in the stack effect) 


NDROP                                   "n-drop"    TOOLS EXT
( xn ... x1 n -- )
Take n off the data stack. Remove n items from the data stack. If n is zero, just remove n.

An ambiguous condition exists if there are less than n+1 items on the data stack when NDROP begins execution.

Add CS-SWAP to TOOLS EXT

 full text

Add the word CS-SWAP to the Programming-Tools extension word set with the following specification: 

15.6.2.???? CS-SWAP             "c-s-swap"      TOOLS EXT
Interpretation: Interpretation semantics for this word are undefined.

Execution: ( C: orig1|dest1 orig2|dest2 -- orig2|dest2 orig1|dest1 )

Swap two elements on top of the control-flow stack. An ambiguous condition exists if there are less than two items, each of which shall be an orig or dest, at the top of the control-flow stack before CS-SWAP is executed.

Add CS-DROP to TOOLS EXT

 full text (note: this proposal has been "seconded")

Add the word CS-DROP to the Programming-Tools extension word set with the following specification: 

15.6.2.???? CS-DROP             "c-s-drop"      TOOLS EXT
Interpretation: Interpretation semantics for this word are undefined.

Execution: ( C: orig|dest -- )

Remove the top element from the control-flow stack. An ambiguous condition exists if the top control-flow stack item is not an orig or dest.

In this connection, modify "15.6.2.1015 CS-PICK" to be: 

15.6.2.1015   CS-PICK           "c-s-pick"   TOOLS EXT
Interpretation: Interpretation semantics for this word are undefined.
Execution:
 		 ( C: origu|destu ... orig0|dest0 -- origu|destu ... orig0|dest0 origu|destu )
( S: u -- )
Remove u. Copy origu|destu to the top of the control-flow stack. An ambiguous condition exists if there are less than u+1 items, each of which shall be an orig or dest, on the control-flow stack before CS-PICK is executed.

If the control-flow stack is implemented using the data stack, u shall be the topmost item on the data stack.

An ambiguous condition exists if the same orig value is resolved multiple times.

and extend "15.4.1.2 Ambiguous conditions": 

15.4.1.2 Ambiguous conditions
- resolving the same orig value multiple times

Add HIDE and REVEAL to TOOLS EXT

 full text (note: this proposal has been "seconded")

Add the following definitions to the optional Programming-Tools extension wordset: 

HIDE                                TOOLS EXT
( -- )
If the last definition is findable in the dictionary, make the last definition not findable. Do nothing if the last definition is not findable or has no name.

Ambiguous conditions: - no definition has been created before execution of HIDE - the compilation wordlist has changed after creation of the last definition

See also: REVEAL 

REVEAL                              TOOLS EXT
( -- )
If the last definition is not findable in the dictionary, make the last definition findable. Do nothing if the last definition already is findable or has no name.

Ambiguous conditions:
- no definition has been created before execution of REVEAL
- the compilation wordlist has changed after creation of the last definition
- execution of a definition begins before the definition is finished

See also: HIDE

Add the word S-SOURCE! to the TOOLS EXT word set, and extend the semantics of RESTORE-INPUT in the TOOLS EXT word set

 full text

The specification itself is very simple (a few lines of text) and may be implemented as one line of system-dependent code: 

: SOURCE! ( addr len -- ) #TIB !  'TIB !  0 >IN !  -1 TO SOURCE-ID ;
Nevertheless, the proposal is long because it has to describe how this very simple functionality fits into the nobody-knows-how-implemented standard model. 

15.6.2.???? S-SOURCE!                                 TOOLS EXT
( addr len -- )
Make the string described by c-addr and u both the input source and input buffer. Store minus-one (-1) in SOURCE-ID if it is present. Store zero in BLK if it is present. Set >IN to zero. An ambiguous condition exists if the system attempts to refill the input buffer before the program restores the original input source.

See: A.15.6.2.???? S-SOURCE!, 6.2.2148 RESTORE-INPUT, 6.2.2182 SAVE-INPUT, 6.2.2218 SOURCE-ID, 7.6.1.0790 BLK, 15.6.2.2148 RESTORE-INPUT. 

A.15.6.2.???? S-SOURCE!             "s-source-store" TOOLS EXT
An attempt to refill the input buffer when the current input source have been switched to a memory string is ambiguous, but closing the file being loaded or making an analogous action with a block input source when an exception happens is not ambiguous.

When an exception happens, a system that implememts 15.6.2.???? S-SOURCE! and/or 15.6.2.2148 RESTORE-INPUT shall not use the current input source parameters to close the file being INCLUDEd, because the value in SOURCE-ID may be -1; instead, it shall use e.g. a copy of the file's fileid. The same may apply to interpreting from a block. Such precaution is anyway meaningful because a program with environmental dependencies may change the input source specification using unstandard means. See: 9.6.1.2275 THROW.

Implementors of the Forth systems designed according to the 1994 standard that have problems with S-SOURCE! and closing files, have an option:

  1. not to support S-SOURCE!
  2. to modify INCLUDE-FILE
  3. to document an environmental restriction, e.g. S-SOURCE! is implemented with an environmental restriction that when INCLUDE-FILE tries to close the current file when an exception happens while the input source specification is modified by S-SOURCE! .
15.6.2.2148 RESTORE-INPUT                             TOOLS EXT
Extend the semantics of 6.2.2148 RESTORE-INPUT to be able to restore the argument input source different from the current input source when:
  1. the argument input source specifies a memory string;
  2. the current input source is a memory string (established by EVALUATE or S-SOURCE! or RESTORE-INPUT), and the argument input source specifies the last active input source other than a memory string.
An ambiguous condition exists if the system attempts to refill the input buffer when the input source is changed and not restored by the program.

See: 15.6.2.???? S-SOURCE!, A.15.6.2.???? S-SOURCE!. 

15.4.1.2 Ambiguous conditions
- the system attempts to refill the input buffer when the input source is changed and not restored by the program (15.6.2.???? S-SOURCE! , 15.6.2.2148 RESTORE-INPUT)
end of file