% !TeX root = forth.tex \chapter{The optional Programming-Tools word set} % 15 \wordlist{tools} \section{Introduction} % 15.1 This optional word set contains words most often used during the development of applications. \section{Additional terms and notation} % 15.2 None. \section{Additional usage requirements} % 15.3 \subsection{Data types} % 15.3.1 \label{tools:datatype} A name token is a single-cell value that identifies a named word. Append table \ref{tools:types} to table \ref{table:datatypes}. \begin{table}[h] \begin{center} \caption{Data types} \label{tools:types} \begin{tabular}{llr} \hline\hline \emph{Symbol} & \emph{Data type} & \emph{Size on stack} \\ \hline \emph{nt} & name token & 1 cell \\ \hline\hline \end{tabular} \end{center} \end{table} See: \xref[A.15.3.x Name token]{rat:tools:nt}{}. \subsection{The Forth dictionary} % 15.3.2 \label{tools:dict} A program using the words \word{CODE} or \word{;CODE} associated with assembler code has an environmental dependency on that particular instruction set and assembler notation. Programs using the words \word{EDITOR} or \word{ASSEMBLER} require the Search Order word set or an equivalent implementation-defined capability. See: \xref[3.3 The Forth dictionary]{usage:dict}. \section{Additional documentation requirements} % 15.4 \subsection{System documentation} % 15.4.1 \subsubsection{Implementation-defined options} % 15.4.1.1 \begin{itemize} \item ending sequence for input following \wref{tools:;CODE}{;CODE} and \wref{tools:CODE}{CODE}; \item manner of processing input following \wref{tools:;CODE}{;CODE} and \wref{tools:CODE}{CODE}; \item search-order capability for \wref{tools:EDITOR}{EDITOR} and \wref{tools:ASSEMBLER}{ASSEMBLER} (\xref[15.3.3 The Forth dictionary]{tools:dict}); \item source and format of display by \wref{tools:SEE}{SEE}. \end{itemize} \subsubsection{Ambiguous conditions} % 15.4.1.2 \label{tools:ambiguous} \begin{itemize} \item deleting the compilation word-list (\wref{tools:FORGET}{}); \item fewer than $u+1$ items on control-flow stack (\wref{tools:CS-PICK}{CS-PICK}, \wref{tools:CS-ROLL}{CS-ROLL}); \item \emph{name} can't be found (\wref{tools:FORGET}{}, \wref{tools:SYNONYM}{}); \item \emph{name} not defined via \wref{core:CREATE}{CREATE} (\wref{tools:;CODE}{;CODE}); \item \wref{core:POSTPONE}{POSTPONE} applied to \wref{tools:[IF]}{[IF]}; \item reaching the end of the input source before matching \wref{tools:[ELSE]}{[ELSE]} or \wref{tools:[THEN]}{[THEN]} (\wref{tools:[IF]}{[IF]}); \item removing a needed definition (\wref{tools:FORGET}{}). \item \wref{core:IMMEDIATE}{} is applied to a word defined by \wref{tools:SYNONYM}{}; \item \wref{tools:NRfrom}{} is used with data not stored by \wref{tools:NtoR}{}; \item adding to or deleting from the wordlist during the execution of \wref{tools:TRAVERSE-WORDLIST}. \end{itemize} \subsubsection{Other system documentation} % 15.4.1.3 \begin{itemize} \item no additional requirements. \end{itemize} \subsection{Program documentation} % 15.4.2 \subsubsection{Environmental dependencies} % 15.4.2.1 \begin{itemize} \item using the words \wref{tools:;CODE}{;CODE} or \wref{tools:CODE}{CODE}. \end{itemize} \subsubsection{Other program documentation} % 15.4.2.2 \begin{itemize} \item no additional requirements. \end{itemize} \section{Compliance and labeling} % 15.5 \enlargethispage{2ex} \subsection{Forth-\snapshot{} systems} % 15.5.1 The phrase ``Providing the Programming-Tools word set'' shall be appended to the label of any Standard System that provides all of the Programming-Tools word set. The phrase ``Providing \emph{name(s)} from the Programming-Tools Extensions word set'' shall be appended to the label of any Standard System that provides portions of the Programming-Tools Extensions word set. The phrase ``Providing the Programming-Tools Extensions word set'' shall be appended to the label of any Standard System that provides all of the Programming-Tools and Programming-Tools Extensions word sets. \subsection{Forth-\snapshot{} programs} % 15.5.2 The phrase ``Requiring the Programming-Tools word set'' shall be appended to the label of Standard Programs that require the system to provide the Programming-Tools word set. The phrase ``Requiring \emph{name(s)} from the Programming-Tools Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide portions of the Programming-Tools Extensions word set. The phrase ``Requiring the Programming-Tools Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide all of the Programming-Tools and Programming-Tools Extensions word sets. \section{Glossary} % 15.6 \subsection{Programming-Tools words} % 15.6.1 \begin{worddef}{0220}{.S}[dot-s] \item \stack{}{} Copy and display the values currently on the data stack. The format of the display is implementation-dependent. \word{.S} may be implemented using pictured numeric output words. Consequently, its use may corrupt the transient region identified by \word[core]{num-end}. \see \xref[3.3.3.6 Other transient regions]{usage:transient}, \rref{tools:.S}{}. \begin{rationale} % A.15.6.1.0220 .S \word[tools]{.S} is a debugging convenience found on almost all Forth systems. It is universally mentioned in Forth texts. \end{rationale} \end{worddef} \begin{worddef}[q]{0600}{?}[question] \item \stack{a-addr}{} Display the value stored at \param{a-addr}. \word{q} may be implemented using pictured numeric output words. Consequently, its use may corrupt the transient region identified by \word[core]{num-end}. \see \xref[3.3.3.6 Other transient regions]{usage:transient}. \end{worddef} \begin{worddef}{1280}{DUMP} \item \stack{addr u}{} Display the contents of \param{u} consecutive addresses starting at \param{addr}. The format of the display is implementation dependent. \word{DUMP} may be implemented using pictured numeric output words. Consequently, its use may corrupt the transient region identified by \word[core]{num-end}. \see \xref[3.3.3.6 Other transient regions]{usage:transient}. \end{worddef} \begin{worddef}{2194}{SEE} \item \stack{"name"}{} Display a human-readable representation of the named word's definition. The source of the representation (object-code decompilation, source block, etc.) and the particular form of the display is implementation defined. \word{SEE} may be implemented using pictured numeric output words. Consequently, its use may corrupt the transient region identified by \word[core]{num-end}. \see \xref[3.3.3.6 Other transient regions]{usage:transient}, \rref{tools:SEE}{}. \begin{rationale} % A.15.6.1.2194 SEE \word[tools]{SEE} acts as an on-line form of documentation of words, allowing modification of words by decompiling and regenerating with appropriate changes. \end{rationale} \end{worddef} \begin{worddef}{2465}{WORDS} \item \stack{}{} List the definition names in the first word list of the search order. The format of the display is implementation-dependent. \word{WORDS} may be implemented using pictured numeric output words. Consequently, its use may corrupt the transient region identified by \word[core]{num-end}. \see \xref[3.3.3.6 Other transient regions]{usage:transient}, \rref{tools:WORDS}{}. \begin{rationale} % A.15.6.1.2465 WORDS \word[tools]{WORDS} is a debugging convenience found on almost all Forth systems. It is universally referred to in Forth texts. \end{rationale} \end{worddef} \subsection{Programming-Tools extension words} % 15.6.2 \extended \begin{worddef}{0470}{;CODE}[semicolon-code] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{colon-sys}{} Append the run-time semantics below to the current definition. End the current definition, allow it to be found in the dictionary, and enter interpretation state, consuming \param{colon-sys}. Subsequent characters in the parse area typically represent source code in a programming language, usually some form of assembly language. Those characters are processed in an implementation-defined manner, generating the corresponding machine code. The process continues, refilling the input buffer as needed, until an implementation-defined ending sequence is processed. \runtime \stack{}{} \stack[R]{nest-sys}{} Replace the execution semantics of the most recent definition with the \emph{name} execution semantics given below. Return control to the calling definition specified by \param{nest-sys}. An ambiguous condition exists if the most recent definition was not defined with \word[core]{CREATE} or a user-defined word that calls \word[core]{CREATE}. \execute[name] \stack{i*x}{j*x} Perform the machine code sequence that was generated following \word{;CODE}. \see \wref{core:DOES}{DOES>}, \rref{tools:;CODE}{}. \begin{rationale} % A.15.6.2.0470 ;CODE Typical use: \word[core]{:} \texttt{namex} {\ldots} \arg{create} {\ldots} \word{;CODE} {\ldots} where \texttt{namex} is a defining word, and \arg{create} is \word[core]{CREATE} or any user defined word that calls \word[core]{CREATE}. \end{rationale} \end{worddef} \begin{worddef}{0702}{AHEAD} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{orig} Put the location of a new unresolved forward reference \param{orig} onto the control flow stack. Append the run-time semantics given below to the current definition. The semantics are incomplete until \param{orig} is resolved (e.g., by \word[core]{THEN}). \runtime \stack{}{} Continue execution at the location specified by the resolution of \param{orig}. \begin{testing} \test{\word{:} pt1 \word{AHEAD} 1111 2222 \word{THEN} 3333 \word{;}}{} \\ \test{pt1}{3333} \end{testing} \end{worddef} \vspace*{-2ex} \begin{worddef}{0740}{ASSEMBLER} \item \stack{}{} Replace the first word list in the search order with the \word{ASSEMBLER} word list. \see \xref[16. The optional Search-Order word set]{wordlist:search}. \end{worddef} \vspace*{-2ex} \begin{worddef}{0830}{BYE} \item \stack{}{} Return control to the host operating system, if any. \end{worddef} \vspace*{-2ex} \enlargethispage{6ex} \begin{worddef}{0930}{CODE} \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name}, called a ``code definition'', with the execution semantics defined below. Subsequent characters in the parse area typically represent source code in a programming language, usually some form of assembly language. Those characters are processed in an implementation-defined manner, generating the corresponding machine code. The process continues, refilling the input buffer as needed, until an implementation-defined ending sequence is processed. \execute[name] \stack{i*x}{j*x} Execute the machine code sequence that was generated following \word{CODE}. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{tools:CODE}{}. \begin{rationale} % A.15.6.2.0930 CODE Some Forth systems implement the assembly function by adding an \word[tools]{ASSEMBLER} word list to the search order, using the text interpreter to parse a postfix assembly language with lexical characteristics similar to Forth source code. Typically, in such systems, assembly ends when a word \texttt{END-CODE} is interpreted. \end{rationale} \end{worddef} \begin{worddef}{1015}{CS-PICK}[c-s-pick] \interpret Interpretation semantics for this word are undefined. \execute \stack[C]{dest_u {\ldots} orig_0|dest_0}{dest_u {\ldots} orig_0|dest_0 dest_u} \stack[S]{u}{} Remove \param{u}. Copy \param{dest_u} to the top of the control-flow stack. An ambiguous condition exists if there are less than \param{u}+1 items, each of which shall be an \param{orig} or \param{dest}, on the control-flow stack before \word{CS-PICK} is executed. If the control-flow stack is implemented using the data stack, \param{u} shall be the topmost item on the data stack. \see \rref{tools:CS-PICK}{}. \begin{rationale} % A.15.6.2.1015 CS-PICK The intent is to copy a \param{dest} on the control-flow stack so that it can be resolved more than once. For example: \setwordlist{core} \begin{quote}\ttfamily \word{bs} Conditionally transfer control to beginning of \\ \word{bs} loop. This is similar in spirit to C's "continue" \\ \word{bs} statement. \word{:} ?REPEAT ~~\word{p} dest -{}- dest ) \word{bs} Compilation \\ \tab\tab\tab~\word{p} flag -{}- ) \tab~\word{bs} Execution \\ \tab 0 \word[tools]{CS-PICK} ~ \word{POSTPONE} \word{UNTIL} \\ \word{;} \word{IMMEDIATE} \word{:} XX \word{p} -{}- ) \word{bs} Example use of ?REPEAT \\ \tab \word{BEGIN} \\ \tab\tab {\ldots} \\ \tab flag ?REPEAT \word{p} Go back to BEGIN if flag is false ) \\ \tab\tab {\ldots} \\ \tab flag ?REPEAT \word{p} Go back to BEGIN if flag is false ) \\ \tab\tab {\ldots} \\ \tab flag \word{UNTIL}~~ \word{p} Go back to BEGIN if flag is false ) \\ \word{;} \end{quote} \setwordlist{tools} \end{rationale} \begin{testing}\ttfamily \word{:} ?repeat \\ \tab 0 \word{CS-PICK} \word{POSTPONE} \word{UNTIL} \\ \word{;} \word{IMMEDIATE} \word{VARIABLE} pt4 \word{:} <= \word{more} \word{0=} \word{;} \test{\word{:} pt5 \word{p} n1 -{}- ) \\ \tab[2.4] pt4 \word{!} \\ \tab[2.4] \word{BEGIN} \\ \tab[3.4] -1 pt4 \word{+!} \\ \tab[3.4] pt4 \word{@} 4 <= ?repeat \tab \word{bs} \textdf{Back to \word{BEGIN} if false} \\ \tab[3.4] 111 \\ \tab[3.4] pt4 \word{@} 3 <= ?repeat \\ \tab[3.4] 222 \\ \tab[3.4] pt4 \word{@} 2 <= ?repeat \\ \tab[3.4] 333 \\ \tab[3.4] pt4 \word{@} 1 \word{=} \\ \tab[2.4] \word{UNTIL} \\ \tab[1.2] \word{;}}{} \test{6 pt5}{111 111 222 111 222 333 111 222 333} \end{testing} \end{worddef} \begin{worddef}{1020}{CS-ROLL}[c-s-roll] \interpret Interpretation semantics for this word are undefined. \execute \stack[C]{orig_u|dest_u orig_{u-1}|dest_{u-1} {\ldots} orig_0|dest_0} {orig_{u-1}|dest_{u-1} {\ldots} orig_0|dest_0 orig_u|dest_u} \stack[S]{u}{} Remove \param{u}. Rotate \param{u}+1 elements on top of the control-flow stack so that \param{orig_u|dest_u} is on top of the control-flow stack. An ambiguous condition exists if there are less than \param{u}+1 items, each of which shall be an \param{orig} or \param{dest}, on the control-flow stack before \word{CS-ROLL} is executed. If the control-flow stack is implemented using the data stack, \param{u} shall be the topmost item on the data stack. \see \rref{tools:CS-ROLL}{}. \begin{rationale} % A.15.6.2.1020 CS-ROLL The intent is to modify the order in which the \param{orig}s and \param{dest}s on the control-flow stack are to be resolved by subsequent control-flow words. For example, \word[core]{WHILE} could be implemented in terms of \word[core]{IF} and \word{CS-ROLL}, as follows: \setwordlist{core} \begin{quote}\ttfamily \word{:} \word{WHILE} ~ \word{p} dest -{}- orig dest ) \\ \tab \word{POSTPONE} \word{IF} ~ 1 \word[tools]{CS-ROLL} \\ \word{;} \word{IMMEDIATE} \end{quote} \setwordlist{tools} \end{rationale} \begin{testing}\ttfamily \test{\word{:} ?DONE \word{p} dest -{}- orig dest ) \tab \word{bs} \textdf{Same as WHILE} \\ \tab[2.4] \word{POSTPONE} \word{IF} 1 \word{CS-ROLL} \\ \tab[1.2] \word{;} \word{IMMEDIATE}}{} \\ \test{\word{:} pt6 \\ \tab[2.4] \word{toR} \\ \tab[2.4] \word{BEGIN} \\ \tab[3.4] \word{R@} \\ \tab[2.4] ?DONE \\ \tab[3.4] \word{R@} \\ \tab[3.4] \word{Rfrom} \word{1-} \word{toR} \\ \tab[2.4] \word{REPEAT} \\ \tab[2.4] \word{Rfrom} \word{DROP} \\ \tab[1.2] \word{;}}{} \test{5 pt6}{5 4 3 2 1} \word{:} mix\_up 2 \word{CS-ROLL} \word{;} \word{IMMEDIATE} \tab \word{bs} \textdf{cs-rot} \word{:} pt7 \word{p} f3 f2 f1 -{}- ? ) \\ \tab \word{IF} 1111 \word{ROT} \word{ROT} \tab ( -{}- 1111 f3 f2 ) \tab[1.8] ( cs:\ -{}- o1 ) \\ \tab[2] \word{IF} 2222 \word{SWAP} \tab[0.6] ( -{}- 1111 2222 f3 ) \tab[0.6] ( cs:\ -{}- o1 o2 ) \\ \tab[3] \word{IF} \tab[18.8] ( cs:\ -{}- o1 o2 o3 ) \\ \tab[4] 3333 mix\_up ( -{}- 1111 2222 3333 ) \tab[-0.8] ( cs:\ -{}- o2 o3 o1 ) \\ \tab[3] \word{THEN} \tab[17.6] ( cs:\ -{}- o2 o3 ) \\ \tab[3] 4444 \tab[1] \word{bs} \textdf{Hence failure of first IF comes here and falls through} \\ \tab[2] \word{THEN} \tab[18.6] ( cs:\ -{}- o2 ) \\ \tab[2] 5555 \tab[2] \word{bs} \textdf{Failure of 3rd IF comes here} \\ \tab[1] \word{THEN} \tab[19.6] ( cs:\ -{}- ) \\ \tab[1] 6666 \tab[3] \word{bs} \textdf{Failure of 2nd IF comes here} \\ \tab \word{;} \test{-1 -1 -1 pt7}{1111 2222 3333 4444 5555 6666} \\ \test{ 0 -1 -1 pt7}{1111 2222 5555 6666 } \\ \test{ 0 0 -1 pt7}{1111 0 6666 } \\ \test{ 0 0 0 pt7}{0 0 4444 5555 6666 } \word{:} [1cs-roll] 1 \word{CS-ROLL} \word{;} \word{IMMEDIATE} \test{\word{:} pt8 \\ \tab[2.2] \word{toR} \\ \tab[2.2] \word{AHEAD} 111 \\ \tab[2.2] \word{BEGIN} 222 \\ \tab[3.2] [1cs-roll] \\ \tab[3.2] \word{THEN} \\ \tab[3.2] 333 \\ \tab[3.2] \word{Rfrom} \word{1-} \word{toR} \\ \tab[3.2] \word{R@} \word{0less} \\ \tab[2.2] \word{UNTIL} \\ \tab[2.2] \word{Rfrom} \word{DROP} \\ \tab[1.2] \word{;}}{} \test{1 pt8}{333 222 333} \end{testing} \end{worddef} \begin{worddef}{1300}{EDITOR} \item \stack{}{} Replace the first word list in the search order with the \word{EDITOR} word list. \see \xref[16. The Optional Search-Order Word Set]{wordlist:search}. \end{worddef} \begin{worddef}{1580}{FORGET} \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Find \param{name}, then delete \param{name} from the dictionary along with all words added to the dictionary after \param{name}. An ambiguous condition exists if \param{name} cannot be found. If the Search-Order word set is present, \word{FORGET} searches the compilation word list. An ambiguous condition exists if the compilation word list is deleted. An ambiguous condition exists if \word{FORGET} removes a word required for correct execution. \note This word is obsolescent and is included as a concession to existing implementations. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{tools:FORGET}{}. \begin{rationale} % A.15.6.2.1580 FORGET Typical use: {\ldots} \word{FORGET} \emph{name} {\ldots} \word{FORGET} \emph{name} tries to infer the previous dictionary state from \emph{name}; this is not always possible. As a consequence, \word{FORGET} \emph{name} removes \emph{name} and all following words in the name space. See \rref{core:MARKER}{}. \end{rationale} \end{worddef} % ------------------------------------------------------------------- \vspace*{-2ex} \begin{worddef}[NtoR]{1908}{N>R}[n-to-r][X:n-to-r] \interpret Interpretation semantics for this word are undefined. \execute \stack{i*n +n}{} \stack[R]{}{j*x +n} Remove \param{n}+1 items from the data stack and store them for later retrieval by \word{NRfrom}. The return stack may be used to store the data. Until this data has been retrieved by \word{NRfrom}: \begin{itemize} \item this data will not be overwritten by a subsequent invocation of \word{NtoR} and \item a program may not access data placed on the return stack before the invocation of \word{NtoR}. \end{itemize} \see \wref{tools:NRfrom}{}, \rref{tools:NtoR}{}. \begin{rationale} An implementation may store the stack items in any manner. It may store them on the return stack, in any order. A stack-constrained system may prefer to use a buffer to store the items and place a reference to the buffer on the return stack. \see \wref{core:SAVE-INPUT}{}, \wref{core:RESTORE-INPUT}{}, \wref{search:GET-ORDER}{}, \linebreak \wref{search:SET-ORDER}{}. \end{rationale} \begin{implement} \textdf{This implementation depends on the return address being on the return stack.} \begin{tabbing} \tab \= \tab \= \tab[11] \= \kill \word{:} \word{NtoR} \word{bs} xn .. x1 N -{}- ; R: -{}- x1 .. xn n \\ \word{bs} \textdf{Transfer N items and count to the return stack.} \+ \\ \word{DUP} \>\> \word{bs} xn .. x1 N N -{}- \\ \word{BEGIN} \+ \\ \word{DUP} \- \\ \word{WHILE} \+ \\ \word{ROT} \word{Rfrom} \word{SWAP} \word{toR} \word{toR} \>\word{bs} xn .. N N -{}- ; R: .. x1 -{}- \\ \word{1-} \> \word{bs} xn .. N 'N -{}- ; R: .. x1 -{}- \- \\ \word{REPEAT} \\ \word{DROP} \>\> \word{bs} N -{}- ; R: x1 .. xn -{}- \\ \word{Rfrom} \word{SWAP} \word{toR} \word{toR} \- \\ \word{;} \end{tabbing} \end{implement} \begin{testing} \word{:} TNR1 \word{NtoR} \word{SWAP} \word{NRfrom} \word{;} \\ \test{1 2 10 20 30 3 TNR1}{2 1 10 20 30 3} \word{:} TNR2 \word{NtoR} \word{NtoR} \word{SWAP} \word{NRfrom} \word{NRfrom} \word{;} \\ \test{1 2 10 20 30 3 40 50 2 TNR2}{2 1 10 20 30 3 40 50 2} \end{testing} \end{worddef} \vspace*{-2ex} \begin{worddef}[NAMEtoCOMPILE]{1909}[10]{NAME>COMPILE}[name-to-compile][X:traverse-wordlist] \item \stack{nt}{x xt} \param{x xt} represents the compilation semantics of the word \param{nt}. The returned \param{xt} has the stack effect \stack{i*x x}{j*x}. Executing \param{xt} consumes \param{x} and performs the compilation semantics of the word represented by \param{nt}. \see \rref{tools:NAMEtoCOMPILE}{}, \wref{tools:TRAVERSE-WORDLIST}{}. \begin{rationale} In a traditional \param{xt}+immediate-flag system, the \param{x xt} returned by \word{NAMEtoCOMPILE} is typically \param{xt1 xt2}, where \param{xt1} is the \param{xt} of the word under consideration, and \param{xt2} is the \param{xt} of \word{EXECUTE} (for immediate words) or \word{COMPILE,} (for words with default compilation semantics). If you want to \word{POSTPONE} \param{nt}, you can do so with \begin{quote}\ttfamily \word{NAMEtoCOMPILE} \word{SWAP} \word{POSTPONE} \word{LITERAL} \word{COMPILE,} \end{quote} \end{rationale} \end{worddef} \vspace*{-2ex} \enlargethispage{4ex} \begin{worddef}[NAMEtoINTERPRET]{1909}[20]{NAME>INTERPRET}[name-to-interpret][X:traverse-wordlist] \item \stack{nt}{xt|0} \param{xt} represents the interpretation semantics of the word \param{nt}. If \param{nt} has no interpretation semantics, \word{NAMEtoINTERPRET} returns 0. \note This standard does not define the interpretation semantics of some words, but systems are allowed to do so. \see \xref{tools:TRAVERSE-WORDLIST}{}. \end{worddef} \vspace*{-2ex} \begin{worddef}[NAMEtoSTRING]{1909}[40]{NAME>STRING}[name-to-string][X:traverse-wordlist] \item \stack{nt}{c-addr u} \word{NAMEtoSTRING} returns the name of the word \param{nt} in the character string \param{c-addr u}. The case of the characters in the string is implementation-dependent. The buffer containing \param{c-addr u} may be transient and valid until the next invocation of \word{NAMEtoSTRING}. A program shall not write into the buffer containing the resulting string. \see \wref{tools:TRAVERSE-WORDLIST}{}. \end{worddef} \begin{worddef}[NRfrom]{1940}{NR>}[n-r-from][X:n-to-r] \interpret Interpretation semantics for this word are undefined. \execute \stack{}{i*x +n} \stack[R]{j*x +n}{} Retrieve the items previously stored by an invocation of \word{NtoR}. \param{n} is the number of items placed on the data stack. It is an ambiguous condition if \word{NRfrom} is used with data not stored by \word{NtoR}. \see \wref{tools:NtoR}{}, \rref{tools:NtoR}{}. \begin{implement} \textdf{This implementation depends on the return address being on the return stack.} \begin{tabbing} \tab \= \tab \= \tab[11] \= \kill \word{:} \word{NRfrom} \word{bs} -{}- xn .. x1 N ; R: x1 .. xn N -{}- \\ \word{bs} \textdf{Pull N items and count off the return stack.} \+ \\ \word{Rfrom} \word{Rfrom} \word{SWAP} \word{toR} \word{DUP} \\ \word{BEGIN} \+ \\ \word{DUP} \- \\ \word{WHILE} \+ \\ \word{Rfrom} \word{Rfrom} \word{SWAP} \word{toR} -ROT \\ \word{1-} \- \\ \word{REPEAT} \\ \word{DROP} \- \\ \word{;} \end{tabbing} \end{implement} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{2250}{STATE} \item \stack{}{a-addr} Extend the semantics of \wref{core:STATE}{STATE} to allow \word{;CODE} to change the value in \word{STATE}. A program shall not directly alter the contents of \word{STATE}. \see \xref[3.4 The Forth text interpreter]{usage:command}, \wref{core::}{:}, \wref{core:;}{;}, \wref{core:ABORT}{ABORT}, \\ \wref{core:QUIT}{QUIT}, \wref{core:STATE}{STATE}, \wref{core:[}{[}, \wref{core:]}{]}, \wref{core::NONAME}{:NONAME}, \\ \wref{tools:;CODE}{;CODE}. \end{worddef} % ------------------------------------------------------------------- \enlargethispage{6ex} \begin{worddef}{2264}{SYNONYM}[][X:synonym] \item \stack{"newname" "oldname"}{} For both strings skip leading space delimiters. Parse \param{newname} and \param{oldname} delimited by a space. Create a definition for \param{newname} with the semantics defined below. \param{Newname} may be the same as \param{oldname}; when looking up \param{oldname}, \param{newname} shall not be found. An ambiguous conditions exists if \param{oldname} can not be found or \word{IMMEDIATE} is applied to \param{newname}. \item[\param{newname} interpretation] \stack{i*x}{j*x} \\ Perform the interpretation semantics of \param{oldname}. \item[\param{newname} compilation] \stack{i*x}{j*x} \\ Perform the compilation semantics of \param{oldname}. \see \wref{core:IMMEDIATE}{}. \begin{implement} \dffamily The implementation of \word{SYNONYM} requires detailed knowledge of the host implementation, which is one reason why it should be standardized. The implementation below is imperfect and specific to VFX Forth, in particular \texttt{HIDE}, \texttt{REVEAL} and \texttt{IMMEDIATE?} are non-standard words. \begin{quote}\ttfamily \word{:} \word{SYNONYM} \word{bs} "newname" "oldname" -{-} \\ \word{bs} \textdf{Create a new definition which redirects to an existing one.} \\ \tab \word{CREATE} \word{IMMEDIATE} \\ \tab[2] HIDE \word{'} \word{,} REVEAL \\ \tab \word{DOES} \\ \tab[2] \word{@} \word{STATE} \word{@} \word{0=} \word{OVER} IMMEDIATE? \word{OR} \\ \tab[2] \word{IF} \word{EXECUTE} \word{ELSE} \word{COMPILE,} \word{THEN} \\ \word{;} \end{quote} \end{implement} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{2297}{TRAVERSE-WORDLIST}[][X:traverse-wordlist] \item \stack{i*x xt wid}{j*x} Remove \param{wid} and \param{xt} from the stack. Execute \param{xt} once for every word in the wordlist \param{wid}, passing the name token \param{nt} of the word to \param{xt}, until the wordlist is exhausted or until \param{xt} returns false. The invoked \param{xt} has the stack effect \stack{k*x nt}{l*x flag}. If \param{flag} is true, \word{TRAVERSE-WORDLIST} will continue with the next name, otherwise it will return. \word{TRAVERSE-WORDLIST} does not put any items other than \param{nt} on the stack when calling \param{xt}, so that \param{xt} can access and modify the rest of the stack. \word{TRAVERSE-WORDLIST} may visit words in any order, with one exception: words with the same name are called in the order newest-to-oldest (possibly with other words in between). An ambiguous condition exists if words are added to or deleted from the wordlist \param{wid} during the execution of \word{TRAVERSE-WORDLIST}. \see \rref{tools:TRAVERSE-WORDLIST}{}, \wref{tools:NAMEtoSTRING}{}, \\ \wref{tools:NAMEtoINTERPRET}{}, \wref{tools:NAMEtoCOMPILE}{}. \begin{rationale} Typical use: \begin{quote}\ttfamily \word{:} WORDS-COUNT \word{p} x nt -- x' f ) \word{DROP} \word{1+} \word{TRUE} \word{;} \\ 0 \word{'} WORDS-COUNT \word[search]{FORTH-WORDLIST} \word{TRAVERSE-WORDLIST} \word{d} \end{quote} prints a count of the number of words in the \word[search]{FORTH-WORDLIST}. \begin{quote}\ttfamily \word{:} ALL-WORDS \word{NAMEtoSTRING} \word{CR} \word{TYPE} \word{TRUE} \word{;} \\ \word{'} ALL-WORDS \word[search]{GET-CURRENT} \word{TRAVERSE-WORDLIST} \end{quote} prints the names of words in the current compilation wordlist. \begin{quote}\ttfamily \word{:} CONTAINS-STRING \\ \tab \word{NAMEtoSTRING} \word{2OVER} \word[string]{SEARCH} \word{IF} \word{CR} \word{TYPE} \word{THEN} \word{FALSE} \word{;} \\ \word{Sq} COM" \word{'} CONTAINS-STRING \word[search]{GET-CURRENT} \word{TRAVERSE-WORDLIST} \end{quote} prints the name of a word containing the string ``COM'', if it exists, and then terminates. \end{rationale} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{2530}[30]{[DEFINED]}[bracket-defined][X:defined] \compile Perform the execution semantics given below. \execute \stack{"name {\ldots}"}{flag} Skip leading space delimiters. Parse name delimited by a space. Return a true flag if \param{name} is the name of a word that can be found (according to the rules in the system's \word{FIND}); otherwise return a false flag. \word{[DEFINED]} is an immediate word. \begin{implement} % I.15.6.2.---- [DEFINED] \word{:} \word{[DEFINED]} \word{BL} \word{WORD} \word{FIND} \word{NIP} \word{0ne} \word{;} \word{IMMEDIATE} \end{implement} \end{worddef} \begin{worddef}{2531}{[ELSE]}[bracket-else] \compile Perform the execution semantics given below. \execute \stack{"name {\ldots}"}{} Skipping leading spaces, parse and discard space-delimited words from the parse area, including nested occurrences of \word{[IF]} {\ldots} \word{[THEN]} and \word{[IF]} {\ldots} \word{[ELSE]} {\ldots} \linebreak \word{[THEN]}, until the word \word{[THEN]} has been parsed and discarded. If the parse area becomes exhausted, it is refilled as with \word[core]{REFILL}. \word{[ELSE]} is an immediate word. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{tools:[ELSE]}{}. \begin{rationale} % A.15.6.2.2531 [ELSE] Typical use: {\ldots} \emph{flag} \word[tools]{[IF]} {\ldots} \word[tools]{[ELSE]} {\ldots} \word[tools]{[THEN]} {\ldots} \end{rationale} \begin{implement} \begin{tabbing} \tab \= \tab \= \tab \= \tab \= \tab \= \tab \= \hspace*{17em} \= \kill \+ \word{:} \word{[ELSE]} \word{p} -{}- ) \\ \+ 1 \word{BEGIN} \>\>\>\>\>\>\word{bs}~level \\ \+ \word{BEGIN} ~ \word{BL} \word{WORD} \word{COUNT} ~ \word{DUP} ~ \word{WHILE} \>\>\>\>\> \word{bs}~level adr len \\ \word{2DUP} \word{Sq} [IF]" \word[string]{COMPARE} \word{0=} \word{IF} \>\>\>\> \word{bs}~level adr len \\ \> \word{2DROP} \word{1+} \>\>\> \word{bs}~level' \\ \+ \word{ELSE} \>\>\>\> \word{bs}~level adr len \\ \word{2DUP} \word{Sq} [ELSE]" \word[string]{COMPARE} \word{0=} \word{IF} \>\>\> \word{bs}~level adr len \\ \> \word{2DROP} \word{1-} \word{DUP} \word{IF} \word{1+} \word{THEN} \>\> \word{bs}~level' \\ \word{ELSE} \>\>\> \word{bs}~level adr len \\ \> \word{Sq} [THEN]" \word[string]{COMPARE} \word{0=} \word{IF} \>\> \word{bs}~level \\ \>\> \word{1-} \> \word{bs}~level' \\ \>\word{THEN} \\ \- \word{THEN} \\ \- \word{THEN} \word{qDUP} \word{0=} ~ \word{IF} \word{EXIT} \word{THEN} \>\>\>\> \word{bs}~level' \\ \- \word{REPEAT} \word{2DROP} \>\>\>\>\> \word{bs}~level \\ \word{REFILL} \word{0=} \word{UNTIL} \>\>\>\>\>\>\word{bs}~level \\ \- \word{DROP} \\ \word{;} \word{IMMEDIATE} \end{tabbing} \end{implement} \end{worddef} \begin{worddef}{2532}{[IF]}[bracket-if] \compile Perform the execution semantics given below. \execute \stack{flag|flag "name {\ldots}"}{} If \param{flag} is true, do nothing. Otherwise, skipping leading spaces, parse and discard space-delimited words from the parse area, including nested occurrences of \word{[IF]} {\ldots} \word{[THEN]} and \word{[IF]} {\ldots} \word{[ELSE]} {\ldots} \word{[THEN]}, until either the word \word{[ELSE]} or the word \word{[THEN]} has been parsed and discarded. If the parse area becomes exhausted, it is refilled as with \word[core]{REFILL}. \word{[IF]} is an immediate word. An ambiguous condition exists if \word{[IF]} is \word[core]{POSTPONE}d, or if the end of the input buffer is reached and cannot be refilled before the terminating \word{[ELSE]} or \word{[THEN]} is parsed. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{tools:[IF]}{}. \begin{rationale} % A.15.6.2.2532 [IF] Typical use: {\ldots} \emph{flag} \word[tools]{[IF]} {\ldots} \word[tools]{[ELSE]} {\ldots} \word[tools]{[THEN]} {\ldots} \end{rationale} \begin{implement} \word{:} \word[tools]{[IF]} \word{p} flag -{}- ) \\ \tab \word{0=} \word{IF} \word{POSTPONE} \word[tools]{[ELSE]} \word{THEN} \\ \word{;} \word{IMMEDIATE} \end{implement} \end{worddef} \begin{worddef}{2533}{[THEN]}[bracket-then] \compile Perform the execution semantics given below. \execute \stack{}{} Does nothing. \word{[THEN]} is an immediate word. \see \rref{tools:[THEN]}{}. \begin{rationale} % A.15.6.2.2533 [THEN] Typical use: {\ldots} \emph{flag} \word[tools]{[IF]} {\ldots} \word[tools]{[ELSE]} {\ldots} \word[tools]{[THEN]} {\ldots} Software that runs in several system environments often contains some source code that is environmentally dependent. Conditional compilation --- the selective inclusion or exclusion of portions of the source code at compile time --- is one technique that is often used to assist in the maintenance of such source code. Conditional compilation is sometimes done with ``smart comments'' --- definitions that either skip or do not skip the remainder of the line based on some test. For example: \setwordlist{core} \begin{quote}\ttfamily \word{bs} If 16-Bit? contains TRUE, lines preceded by 16BIT\bs \\ \word{bs} will be skipped. Otherwise, they will not be skipped. \word{VARIABLE} 16-BIT? \word{:} 16BIT\bs~~\word{p} -{}- ) ~ 16-BIT? \word{@} ~ \word{IF} ~ \word{POSTPONE} \word{bs} ~ \word{THEN} \\ \word{;} \word{IMMEDIATE} \end{quote} \setwordlist{tools} This technique works on a line by line basis, and is good for short, isolated variant code sequences. More complicated conditional compilation problems suggest a nestable method that can encompass more than one source line at a time. The words included in the optional Programming tools extensions word set are useful for this purpose. \end{rationale} \begin{implement} \word{:} \word{[THEN]} \word{p} -{}- ) \word{;} \word{IMMEDIATE} \end{implement} \begin{testing} \test{ \word{[IF]} 111 \word{[ELSE]} 222 \word{[THEN]}}{111} \\ \test{ \word{[IF]} 111 \word{[ELSE]} 222 \word{[THEN]}}{222} \word{bs} \textdf{Check words are immediate} \\ \word{:} tfind \word{BL} \word{WORD} \word{FIND} \word{;} \\ \test{tfind \word{[IF]} \word{NIP}}{1} \\ \test{tfind \word{[ELSE]} \word{NIP}}{1} \\ \test{tfind \word{[THEN]} \word{NIP}}{1} \test{\word{:} pt2 \word{[} 0 \word{]} \word{[IF]} 1111 \word{[ELSE]} 2222 \word{[THEN]} \word{;} pt2}{2222} \\ \test{\word{:} pt3 \word{[} -1 \word{]} \word{[IF]} 3333 \word{[ELSE]} 4444 \word{[THEN]} \word{;} pt3}{3333} \word{bs} \textdf{Code spread over more than 1 line} \\ \test{ \word{[IF]} 1 \\ \tab[8] 2 \\ \tab[6] \word{[ELSE]} \\ \tab[8] 3 \\ \tab[8] 4 \\ \tab[6] \word{[THEN]}}{1 2}\\ \test{ \word{[IF]} \\ \tab[8] 1 2 \\ \tab[6] \word{[ELSE]} \\ \tab[8] 3 4 \\ \tab[6] \word{[THEN]}}{3 4} \word{bs} \textdf{Nested} \\ \word{:} \word{;} \\ \word{:} \word{:} \\ \test{ \word{[IF]} 1 \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{1 2} \\ \test{ \word{[IF]} 1 \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{4} \\ \test{ \word{[IF]} 1 \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{1 3} \\ \test{ \word{[IF]} 1 \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{4} \end{testing} \end{worddef} \begin{worddef}{2534}{[UNDEFINED]}[bracket-undefined][X:defined] \compile Perform the execution semantics given below. \execute \stack{"name {\ldots}"}{flag} Skip leading space delimiters. Parse name delimited by a space. Return a false flag if \param{name} is the name of a word that can be found (according to the rules in the system's \word{FIND}); otherwise return a true flag. \word{[UNDEFINED]} is an immediate word. \begin{implement} % I.15.6.2.---- [UNDEFINED] \word{:} \word{[UNDEFINED]} \word{BL} \word{WORD} \word{FIND} \word{NIP} \word{0=} \word{;} \word{IMMEDIATE} \end{implement} \end{worddef}