% !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{"<spaces>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{"<spaces>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{"<spaces>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{"<spaces>newname" "<spaces>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{"<spaces>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{"<spaces>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 "<spaces>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{<TRUE>  \word{[IF]} 111 \word{[ELSE]} 222 \word{[THEN]}}{111} \\
		\test{<FALSE> \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{<TRUE>  \word{[IF]} 1 \\
		\tab[8] 2 \\
		\tab[6] \word{[ELSE]} \\
		\tab[8] 3 \\
		\tab[8] 4 \\
		\tab[6] \word{[THEN]}}{1 2}\\
		\test{<FALSE> \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{:} <T> <TRUE>  \word{;} \\
		\word{:} <F> <FALSE> \word{:} \\
		\test{<T> \word{[IF]} 1 <T> \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{1 2} \\
		\test{<F> \word{[IF]} 1 <T> \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{4} \\
		\test{<T> \word{[IF]} 1 <F> \word{[IF]} 2 \word{[ELSE]} 3 \word{[THEN]} \word{[ELSE]} 4 \word{[THEN]}}{1 3} \\
		\test{<F> \word{[IF]} 1 <F> \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{"<spaces>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}
