% !TeX root = forth.tex \chapter{The optional Search-Order word set} % 16 \wordlist{search} \section{Introduction} % 16.1 \section{Additional terms and notation} % 16.2 \begin{description} \item[compilation word list:] The word list into which new definition names are placed. \item[search order:] A list of word lists specifying the order in which the dictionary will be searched. \end{description} \section{Additional usage requirements} % 16.3 \subsection{Data types} % 16.3.1 Word list identifiers are implementation-dependent single-cell values that identify word lists. Append table \ref{search:types} to table \ref{table:datatypes}. \begin{table}[h] \begin{center} \caption{Data types} \label{search:types} \begin{tabular}{llr} \hline\hline \emph{Symbol} & \emph{Data type} & \emph{Size on stack} \\ \hline \emph{wid} & word list identifiers & 1 cell \\ \hline\hline \end{tabular} \end{center} \end{table} See: \xref[3.1 Data types]{usage:data}, \xref[3.4.2 Finding definition names]{usage:find}, \xref[3.4 The Forth text interpreter]{usage:command}. \subsection{Environmental queries} % 16.3.2 Append table \ref{search:env} to table \ref{table:env}. See: \xref[3.2.6 Environmental queries]{usage:env}. \begin{table}[ht] \begin{center} \caption{Environmental Query Strings} \label{search:env} \begin{tabular}{p{10em}rcp{0.42\textwidth}} \hline\hline \multicolumn{2}{l}{String \hfill Value data type} & Constant? & Meaning \\ \hline \texttt{WORDLISTS} & \emph{n} & yes & maximum number of word lists usable in the search order\\ \hline\hline \end{tabular} \end{center} \end{table} \subsection{Finding definition names} % 16.3.3 \label{search:find} When searching a word list for a definition name, the system shall search each word list from its last definition to its first. The search may encompass only a single word list, as with \word{SEARCH-WORDLIST}, or all the word lists in the search order, as with the text interpreter and \word{FIND}. Changing the search order shall only affect the subsequent finding of definition names in the dictionary. A system with the Search-Order word set shall allow at least eight word lists in the search order. An ambiguous condition exists if a program changes the compilation word list during the compilation of a definition or before modification of the behavior of the most recently compiled definition with \word[tools]{;CODE}, \word[core]{DOES}, or \word[core]{IMMEDIATE}. A program that requires more than eight word lists in the search order has an environmental dependency. See: \xref[3.4.2 Finding definition names]{usage:find}. \subsection{Contiguous regions} % 16.3.4 The regions of data space produced by the operations described in \xref[3.3.3.2 Contiguous regions]{usage:contiguous} may be non-contiguous if \word{WORDLIST} is executed between allocations. \section{Additional documentation requirements} % 16.4 \subsection{System documentation} % 16.4.1 \subsubsection{Implementation-defined options} % 16.4.1.1 \begin{itemize} \item maximum number of word lists in the search order (\xref[16.3.3 Finding definition names]{search:find}, \wref{search:SET-ORDER}{SET-ORDER}); \item minimum search order (\wref{search:SET-ORDER}{SET-ORDER}, \wref{search:ONLY}{ONLY}). \end{itemize} \subsubsection{Ambiguous conditions} % 16.4.1.2 \begin{itemize} \item changing the compilation word list (\xref[16.3.3 Finding definition names]{search:find}); \item search order empty (\wref{search:PREVIOUS}{PREVIOUS}); \item too many word lists in search order (\wref{search:ALSO}{ALSO}). \end{itemize} \subsubsection{Other system documentation} % 16.4.1.3 \begin{itemize} \item no additional requirements. \end{itemize} \subsection{Program documentation} % 16.4.2 \subsubsection{Environmental dependencies} % 16.4.2.1 \begin{itemize} \item requiring more than eight word-lists in the search order (\xref[16.3.3 Finding definition names]{search:find}). \end{itemize} \subsubsection{Other program documentation} % 16.4.2.2 \begin{itemize} \item no additional requirements. \end{itemize} \section{Compliance and labeling} % 16.5 \subsection{Forth-\snapshot{} systems} % 16.5.1 The phrase ``Providing the Search-Order word set'' shall be appended to the label of any Standard System that provides all of the Search-Order word set. The phrase ``Providing \emph{name(s)} from the Search-Order Extensions word set'' shall be appended to the label of any Standard System that provides portions of the Search-Order Extensions word set. The phrase ``Providing the Search-Order Extensions word set'' shall be appended to the label of any Standard System that provides all of the Search-Order and Search-Order Extensions word sets. \subsection{Forth-\snapshot{} programs} % 16.5.2 The phrase ``Requiring the Search-Order word set'' shall be appended to the label of Standard Programs that require the system to provide the Search-Order word set. The phrase ``Requiring \emph{name(s)} from the Search-Order Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide portions of the Search-Order Extensions word set. The phrase ``Requiring the Search-Order Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide all of the Search-Order and Search-Order Extensions word sets. \section{Glossary} % 16.6 \subsection{Search-Order words} % 16.6.1 \begin{worddef}{1180}{DEFINITIONS} \item \stack{}{} Make the compilation word list the same as the first word list in the search order. Specifies that the names of subsequent definitions will be placed in the compilation word list. Subsequent changes in the search order will not affect the compilation word list. \see \xref[16.3.3 Finding Definition Names]{search:find}. \begin{implement} \word{:} discard \word{p} x1 {\ldots} xn u -{}- ) \bs{} \textdf{Drop u+1 stack items} \\ \tab 0 \word{qDO} \word{DROP} \word{LOOP} \\ \word{;} \word{:} \word{DEFINITIONS} \word{p} -{}- ) \\ \tab \word{GET-ORDER} \word{SWAP} \word{SET-CURRENT} discard \\ \word{;} \end{implement} \begin{testing}\ttfamily \test{\word{ONLY} \word{FORTH} \word{DEFINITIONS}}{} \\ \test{\word{GET-CURRENT}}{FORTH-WORDLIST} \test{\word{GET-ORDER} wid2 \word{@} \word{SWAP} \word{1+} \word{SET-ORDER} \word{DEFINITIONS} \word{GET-CURRENT}\\}{wid2 \word{@}} \\ \test{\word{GET-ORDER}}{get-orderlist wid2 \word{@} \word{SWAP} \word{1+}} \\ \test{\word{PREVIOUS} \word{GET-ORDER}}{get-orderlist} \\ \test{\word{DEFINITIONS} \word{GET-CURRENT}}{FORTH-WORDLIST} \word{:} alsowid2 \word{ALSO} \word{GET-ORDER} wid2 \word{@} \word{ROT} \word{DROP} \word{SWAP} \word{SET-ORDER} \word{;} \\ alsowid2 \\ \word{:} w1 1234 \word{;} \\ \word{DEFINITIONS} \word{:} w1 -9876 \word{;} \word{IMMEDIATE} \word{ONLY} \word{FORTH} \\ \test{w1}{1234} \\ \word{DEFINITIONS} \\ \test{w1}{1234} \\ alsowid2 \\ \test{w1}{-9876} \\ \word{DEFINITIONS} \test{w1}{-9876} \word{ONLY} \word{FORTH} \word{DEFINITIONS} \\ \word{:} so5 \word{DUP} \word{IF} \word{SWAP} \word{EXECUTE} \word{THEN} \word{;} \test{\word{Sq} w1" wid1 \word{@} \word{SEARCH-WORDLIST} so5}{-1 1234} \\ \test{\word{Sq} w1" wid2 \word{@} \word{SEARCH-WORDLIST} so5}{ 1 -9876} \word{:} c"w1" \word{Cq} w1" \word{;} \\ \test{alsowid2 c"w1" \word{FIND} so5}{ 1 -9876} \\ \test{\word{PREVIOUS} c"w1" \word{FIND} so5}{-1 1234} \end{testing} \end{worddef} \begin{worddef}{1550}{FIND} \item Extend the semantics of \wref{core:FIND}{FIND} to be: \stack{c-addr}{c-addr 0 | xt 1 | xt -1} Find the definition named in the counted string at \param{c-addr}. If the definition is not found after searching all the word lists in the search order, return \param{c-addr} and zero. If the definition is found, return \param{xt}. If the definition is immediate, also return one (\param{1}); otherwise also return minus-one (\param{-1}). For a given string, the values returned by \word{FIND} while compiling may differ from those returned while not compiling. \see \xref[3.4.2 Finding definition names]{usage:find}, \wref{core:'}{'}, \wref{core:FIND}{FIND}, \wref{core:POSTPONE}{POSTPONE}, \wref{core:[']}{[']}. \begin{implement} \textdf{Assuming {\tt\#order} and {\tt context} are defined as per \iref{search:GET-ORDER}{}.} \begin{tabbing} \tab \= \tab \= \tab \= \tab \= 2swap 2drop leave \tab \= \\\kill \word{:} \word{FIND} \word{p} c-addr -{}- c-addr 0 | xt 1 | xt -1 ) \+ \\ 0 \>\>\>\> \word{p} c-addr 0 ) \\ \#order \word{@} 0 \word{qDO} \+ \\ \word{OVER} \word{COUNT} \>\>\> \word{p} c-addr 0 c-addr' u ) \\ \word{I} \word{CELLS} context \word{+} \word{@} \>\>\> \word{p} c-addr 0 c-addr' u wid ) \\ \word{SEARCH-WORDLIST} \>\>\> \word{p} c-addr 0; 0 | w 1 | q -1 ) \\ \word{qDUP} \word{IF} \>\>\> \word{p} c-addr 0; w 1 | w -1 ) \+ \\ \> \word{2SWAP} \word{2DROP} \word{LEAVE} \> \word{p} w 1 | w -1 ) \\ \word{THEN} \>\> \word{p} c-addr 0 ) \- \\ \word{LOOP} \>\>\> \word{p} c-addr 0 | w 1 | w -1 ) \- \\ \word{;} \end{tabbing} \end{implement} \begin{testing}\ttfamily \word{:} c"dup" \word{Cq} DUP" \word{;} \\ \word{:} c".("~ \word{Cq} .("~ \word{;} \\ \word{:} c"x"~~ \word{Cq} unknown word" \word{;} \test{c"dup" \word{FIND}}{xt \word{@} -1} \\ \test{c".(" \word{FIND}}{xti \word{@} 1} \\ \test{c"x" \word{FIND}}{c"x" 0} \end{testing} \end{worddef} \begin{worddef}{1595}{FORTH-WORDLIST} \item \stack{}{wid} Return \param{wid}, the identifier of the word list that includes all standard words provided by the implementation. This word list is initially the compilation word list and is part of the initial search order. \begin{testing} \test{\word{FORTH-WORDLIST} wid1 \word{!}}{} \end{testing} \end{worddef} \begin{worddef}{1643}{GET-CURRENT} \item \stack{}{wid} Return \param{wid}, the identifier of the compilation word list. \end{worddef} \begin{worddef}{1647}{GET-ORDER} \item \stack{}{wid_n {\ldots} wid_1 n} Returns the number of word lists \param{n} in the search order and the word list identifiers \param{wid_n} {\ldots} \param{wid_1} identifying these word lists. \param{wid_1} identifies the word list that is searched first, and \param{wid_n} the word list that is searched last. The search order is unaffected. \begin{implement} \textdf{Here is a very simple search order implementation:} \word{VARIABLE} \#order \word{CREATE} context ~ 16 \word{p} wordlists ) \word{CELLS} \word{ALLOT} \word{:} \word{GET-ORDER} \word{p} -{}- wid1 {\ldots} widn n ) \\ \tab \#order \word{@} 0 \word{qDO} \\ \tab[2] \#order \word{@} \word{I} \word{-} \word{1-} \word{CELLS} context \word{+} \word{@} \\ \tab \word{LOOP} \\ \tab \#order \word{@} \\ \word{;} \end{implement} \end{worddef} \begin{worddef}{2192}{SEARCH-WORDLIST} \item \stack{c-addr u wid}{0 | xt 1 | xt -1} Find the definition identified by the string \param{c-addr u} in the word list identified by \param{wid}. If the definition is not found, return zero. If the definition is found, return its execution token \param{xt} and one (\param{1}) if the definition is immediate, minus-one (\param{-1}) otherwise. \see \rref{search:SEARCH-WORDLIST}{}. \begin{rationale} % A.16.6.1.219 SEARCH-WORDLIST When \word{SEARCH-WORDLIST} fails to find the word, it does not return the string, unlike \word{FIND}. This is in accordance with the general principle that Forth words consume their arguments. \end{rationale} \begin{testing}\ttfamily \word{ONLY} \word{FORTH} \word{DEFINITIONS} \\ \word{VARIABLE} xt~ \word{'} \word{DUP} xt~ \word{!} \\ \word{VARIABLE} xti \word{'} \word{.p}~ xti \word{!} \word{bs} \textdf{Immediate word} \test{\word{Sq} DUP" wid1 \word{@} \word{SEARCH-WORDLIST}}{xt \word{@} -1} \\ \test{\word{Sq} .(" wid1 \word{@} \word{SEARCH-WORDLIST}}{xti \word{@} 1} \\ \test{\word{Sq} DUP" wid2 \word{@} \word{SEARCH-WORDLIST}}{ 0} \end{testing} \end{worddef} \begin{worddef}{2195}{SET-CURRENT} \item \stack{wid}{} Set the compilation word list to the word list identified by \param{wid}. \begin{testing} \test{\word{GET-CURRENT}}{wid1 \word{@}} \test{\word{WORDLIST} wid2 \word{!}}{} \\ \test{wid2 \word{@} \word{SET-CURRENT}}{} \\ \test{\word{GET-CURRENT}}{wid2 \word{@}} \test{wid1 \word{@} \word{SET-CURRENT}}{} \end{testing} \end{worddef} \begin{worddef}{2197}{SET-ORDER} \item \stack{wid_n {\ldots} wid_1 n}{} Set the search order to the word lists identified by \param{wid_n} {\ldots} \param{wid_1}. Subsequently, word list \param{wid_1} will be searched first, and word list \param{wid_n} searched last. If \param{n} is zero, empty the search order. If \param{n} is minus one, set the search order to the implementation-defined minimum search order. The minimum search order shall include the words \word{FORTH-WORDLIST} and \word{SET-ORDER}. A system shall allow \param{n} to be at least eight. \begin{implement} \textdf{This is the complement of \iref{search:GET-ORDER}{}.} \word{:} \word{SET-ORDER} \word{p} wid1 {\ldots} widn n -{}0 ) \\ \tab \word{DUP} -1 \word{=} \word{IF} \\ \tab[2] \word{DROP} \arg{\textdf{push system default word lists and n}} \\ \tab \word{THEN} \\ \tab \word{DUP} \#order \word{!} \\ \tab 0 \word{qDO} ~ \word{I} \word{CELLS} context \word{+} \word{!} ~ \word{LOOP} \\ \word{;} \end{implement} \begin{testing}\ttfamily \test{\word{GET-ORDER} \word{OVER} }{\word{GET-ORDER} wid1 \word{@}} \\% \word{bs} \textdf{Forth wordlist at top} \\ \test{\word{GET-ORDER} \word{SET-ORDER}}{} \\% \tab \word{bs} \textdf{Effectively noop} \\ \test{\word{GET-ORDER} }{get-orderlist} % \tab \word{bs} \textdf{Check nothing changed} \\ \test{get-orderlist \word{DROP} get-orderList \word{2*} \word{SET-ORDER}}{} \\ \test{\word{GET-ORDER}}{get-orderlist \word{DROP} get-orderList \word{2*}} \\ \test{get-orderlist \word{SET-ORDER} \word{GET-ORDER}}{get-orderlist} \word{:} so2a \word{GET-ORDER} get-orderlist \word{SET-ORDER} \word{;} \\ \word{:} so2 0 \word{SET-ORDER} so2a \word{;} \test{so2}{0} \tab[1.5] \word{bs} \textdf{0 SET-ORDER leaves an empty search order} \word{:} so3 -1 \word{SET-ORDER} so2a \word{;} \\ \word{:} so4 \word{ONLY} so2a \word{;} \test{so3}{so4} \tab \word{bs} \textdf{-1 SET-ORDER is the same as ONLY} \end{testing} \end{worddef} \enlargethispage{2ex} \begin{worddef}{2460}{WORDLIST} \item \stack{}{wid} Create a new empty word list, returning its word list identifier \param{wid}. The new word list may be returned from a pool of preallocated word lists or may be dynamically allocated in data space. A system shall allow the creation of at least 8 new word lists in addition to any provided as part of the system. \end{worddef} \subsection{Search-Order extension words} % 16.6.2 \extended \begin{worddef}{0715}{ALSO} \item \stack{}{} Transform the search order consisting of \param{wid_n}, {\ldots} \param{wid_2}, \param{wid_1} (where \param{wid_1} is searched first) into \param{wid_n}, {\ldots} \param{wid_2}, \param{wid_1}, \param{wid_1}. An ambiguous condition exists if there are too many word lists in the search order. \begin{implement} \word{:} \word{ALSO} \word{p} -{}- ) \\ \tab \word{GET-ORDER} \word{OVER} \word{SWAP} \word{1+} \word{SET-ORDER} \\ \word{;} \end{implement} \begin{testing} \test{\word{ALSO} \word{GET-ORDER} \word{ONLY}}{get-orderlist \word{OVER} \word{SWAP} \word{1+}} \end{testing} \end{worddef} \begin{worddef}{1590}{FORTH} \item \stack{}{} Transform the search order consisting of \param{wid_n}, {\ldots} \param{wid_2}, \param{wid_1} (where \param{wid_1} is searched first) into \param{wid_n}, {\ldots} \param{wid_2}, \param{wid_{\word{FORTH-WORDLIST}}}. \begin{implement} \word{:} (wordlist) \word{p} wid "" -- ; ) \\ \tab \word{CREATE} \word{,} \\ \tab \word{DOES} \\ \tab[2] \word{@} \word{toR} \\ \tab[2] \word{GET-ORDER} \word{NIP} \\ \tab[2] \word{Rfrom} \word{SWAP} \word{SET-ORDER} \\ \word{;} \word{FORTH-WORDLIST} (wordlist) \word{FORTH} \end{implement} \end{worddef} \begin{worddef}{1965}{ONLY} \item \stack{}{} Set the search order to the implementation-defined minimum search order. The minimum search order shall include the words \word{FORTH-WORDLIST} and \word{SET-ORDER}. \begin{implement} \word{:} \word{ONLY} \word{p} -{}- ) -1 \word{SET-ORDER} \word{;} \end{implement} \begin{testing}\ttfamily \test{\word{ONLY} \word{FORTH} \word{GET-ORDER}}{get-orderlist} \word{:} so1 \word{SET-ORDER} {;} \word{bs} \textdf{In case it is unavailable in the forth wordlist} \test{\word{ONLY} \word{FORTH-WORDLIST} 1 \word{SET-ORDER} get-orderlist so1}{} \\ \test{\word{GET-ORDER}}{get-orderlist} \end{testing} \end{worddef} \begin{worddef}{1985}{ORDER} \item \stack{}{} Display the word lists in the search order in their search order sequence, from first searched to last searched. Also display the word list into which new definitions will be placed. The display format is implementation dependent. \word{ORDER} 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}. \begin{testing}\ttfamily \word{CR} \word{.p} ONLY FORTH DEFINITIONS search order and compilation list) \word{CR} \\ \test{\word{ONLY} \word{FORTH} \word{DEFINITIONS} \word{ORDER}}{} \word{CR} \word{.p} Plus another unnamed wordlist at head of search order) \word{CR} \\ \test{alsowid2 \word{DEFINITIONS} \word{ORDER}}{} \end{testing} \end{worddef} \begin{worddef}{2037}{PREVIOUS} \item \stack{}{} Transform the search order consisting of \param{wid_n}, {\ldots} \param{wid_2}, \param{wid_1} (where \param{wid_1} is searched first) into \param{wid_n}, {\ldots} \param{wid_2}. An ambiguous condition exists if the search order was empty before \word{PREVIOUS} was executed. \begin{implement} \word{:} \word{PREVIOUS} \word{p} -{}- ) \word{GET-ORDER} \word{NIP} \word{1-} \word{SET-ORDER} \word{;} \end{implement} \end{worddef}