Commit 5ddf0fa4 authored by pknaggs's avatar pknaggs

*** empty log message ***

parent e536fab7
\chapter{The optional Legacy word set} % x
\wordlist{legacy}
\section{Introduction} % x.1
This Standard adopts certain words and practices that cause
some previously used words and practices to become obsolescent.
Due to the widespread use of some of these words in legacy code,
they have been collected into this word set to preserve the
definition of these words. These words should \emph{not} be
used in new developments.
\section{Additional terms and notation} % x.2
None.
\section{Additional usage requirements} % x.3
None.
\section{Additional documentation requirements} % x.4
\subsection{System documentation} % x.4.1
\subsubsection{Implementation-defined options} % x.4.1.1
\begin{itemize}
\item character editing of \wref{legacy:EXPECT}{EXPECT};
\item display after input terminates in \wref{legacy:EXPECT}{EXPECT};
\end{itemize}
\subsubsection{Ambiguous conditions} % x.4.1.2
\begin{itemize}
\item producing a result out of range, e.g., multiplication
(using \word{*}) results in a value too big to be represented by
a single-cell integer
(\wref{legacy:CONVERT}{CONVERT};
\item deleting the compilation word-list (\wref{legacy:FORGET}{FORGET});
\item \emph{name} can't be found (\wref{legacy:FORGET}{FORGET});
\item removing a needed definition (\wref{legacy:FORGET}{FORGET}).
\end{itemize}
\subsubsection{Other system documentation} % x.4.1.3
\begin{itemize}
\item no additional requirements.
\end{itemize}
\subsection{Program documentation} % x.4.2
\subsubsection{Environmental dependencies} % x.4.2.1
\begin{itemize}
\item depending on the presence or absence of non-graphic characters
in a received string (\wref{legacy:EXPECT}{EXPECT});
\end{itemize}
\section{Compliance and labeling} % x.5
\cbstart\patch{F94}
\subsection[Forth systems]{ANS\strike{3.5}{25} Forth systems} % x.5.1
\cbend
The phrase ``Providing the Legacy word set'' shall be appended to
the label of any Standard System that provides all of the Legacy
word set.
The phrase ``Providing \emph{name(s)} from the Legacy Extensions
word set'' shall be appended to the label of any Standard System
that provides portions of the Legacy Extensions word set.
The phrase ``Providing the Legacy Extensions word set'' shall be
appended to the label of any Standard System that provides all of
the Legacy and Legacy Extensions word sets.
\cbstart\patch{F94}
\subsection[Forth programs]{ANS\strike{3.5}{25} Forth programs} % x.5.2
\cbend
The phrase ``Requiring the Legacy word set'' shall be appended to
the label of Standard Programs that require the system to provide
the Legacy word set.
The phrase ``Requiring \emph{name(s)} from the Legacy Extensions
word set'' shall be appended to the label of Standard Programs that
require the system to provide portions of the Legacy Extensions
word set.
The phrase ``Requiring the Legacy Extensions word set'' shall be
appended to the label of Standard Programs that require the system
to provide all of the Legacy and Legacy Extensions word sets.
\section{Glossary} % x.6
\subsection{Legacy words} % x.6.1
\begin{worddef}[numTIB]{0060}{\num{}TIB}[number-t-i-b]
\item \stack{}{a-addr}
\param{a-addr} is the address of a cell containing the number
of characters in the terminal input buffer.
\note
This function has been superseded by \word{SOURCE}.
\begin{rationale} % A.x.1.0060 #TIB
The function of \word{numTIB} has been superseded by
\wref{core:SOURCE}{SOURCE}.
\end{rationale}
\end{worddef}
\begin{worddef}{0970}{CONVERT}
\item \stack{ud_1 c-addr_1}{ud_2 c-addr_2}
\param{ud_2} is the result of converting the characters within
the text beginning at the first character after \param{c-addr_1}
into digits, using the number in \word{BASE}, and adding each
digit to \param{ud_1} after multiplying \param{ud_1} by the
number in \word{BASE}. Conversion continues until a character
that is not convertible is encountered. \param{c-addr_2} is
the location of the first unconverted character. An ambiguous
condition exists if \param{ud_2} overflows.
\note
This function is superseded by \wref{core:toNUMBER}{>NUMBER}.
\see \xref[3.2.1.2 Digit conversion]{usage:digits}.
\begin{rationale} % A.6.2.0970 CONVERT
\word{CONVERT} may be defined as follows:
\tab \word{:} \word{CONVERT}~
\word{CHAR+} \texttt{65535} \word{toNUMBER} \word{DROP}
\word{;}
\end{rationale}
\begin{testing}\ttfamily
\textdf{Create two large integers, small enough to not
cause overflow}
MAX-INT 3 \word{/} \word{CONSTANT} cvi1 \\
MAX-INT 5 \word{/} \word{CONSTANT} cvi2
\textsf{Create a string of the form ``(n1digits.n2digits)''}
\word{:} 2n>str \word{p} +n1 +n2 -{}- caddr u ) \\
\tab \word{num-start} \word{[CHAR]} ) \word{HOLD} \word{StoD} \word{numS} \word{2DROP} \tab \word{p} -{}- +n1 ) \\
\tab[2.3] \word{[CHAR]} . \word{HOLD} \word{StoD} \word{numS} \\
\tab[2.3] \word{[CHAR]} ( \word{HOLD} \word{num-end} \tab[6] \word{p} -{}- caddr1 u ) \\
\tab \word{HERE} \word{SWAP} \word{2DUP} \word{2toR} \word{CHARS} \word{DUP} \word{ALLOT} \word{MOVE} \word{2Rfrom} \\
\word{;}
cvi1 cvi2 2n>str \word{CONSTANT} cv\$len \word{CONSTANT} cv\$ad
\test{0 0 cv\$ad \word{CONVERT} \word{C@}}{cvi1 \word{StoD} \word{CHAR} .} \\
\test{0 0 cv\$ad \word{CONVERT} \word{CONVERT} \word{C@}}{ \\
\tab[1.2] 0 0 cv\$ad \word{CHAR+} cv\$len 1- \word{toNUMBER} \\
\tab[1.2] \word{1-} \word{SWAP} \word{CHAR+} \word{SWAP} \word{toNUMBER} \word{2DROP} \word{CHAR} )}
\end{testing}
\end{worddef}
\begin{worddef}{1390}{EXPECT}
\item \stack{c-addr +n}{}
Receive a string of at most \param{+n} characters. Display graphic
characters as they are received. A program that depends on
the presence or absence of non-graphic characters in the
string has an environmental dependency. The editing functions,
if any, that the system performs in order to construct the
string of characters are implementation-defined.
Input terminates when an implementation-defined line terminator
is received or when the string is \param{+n} characters long. When
input terminates, nothing is appended to the string and the
display is maintained in an implementation-defined way.
Store the string at \param{c-addr} and its length in \word{SPAN}.
\note
This function is superseded by \wref{core:ACCEPT}{ACCEPT}.
\begin{rationale} % A.6.2.1390 EXPECT
Specification of positive integer counts (\param{+n}) for
\word{EXPECT} allows some implementors to continue their
practice of using a zero or negative value as a flag to
trigger special behavior. Insofar as such behavior is outside
the Standard, Standard Programs cannot depend upon it, but
the Technical Committee doesn't wish to preclude it
unnecessarily. Since actual values are almost always small
integers, no functionality is impaired by this restriction.
\end{rationale}
\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.
\see \xref[3.4.1 Parsing]{usage:parsing}.
\begin{rationale} % A.15.6.2.1580 FORGET
Typical use:
{\ldots} \word{FORGET} \emph{name} {\ldots}
\word{FORGET} assumes that all the information needed to
restore the dictionary to its previous state is inferable
somehow from the forgotten word. While this may be true in
simple linear dictionary models, it is difficult to implement
in other Forth systems; e.g., those with multiple address
spaces. For example, if Forth is embedded in ROM, how does
\word{FORGET} know how much RAM to recover when an array
is forgotten? A general and preferred solution is provided by
\word[core]{MARKER}.
\end{rationale}
\end{worddef}
\begin{worddef}{2040}{QUERY}
\item \stack{}{}
Make the user input device the input source. Receive input into
the terminal input buffer, replacing any previous contents. Make
the result, whose address is returned by \word{TIB}, the input
buffer. Set \word{toIN} to zero.
\begin{rationale} % A.6.2.2040 QUERY
The function of \word{QUERY} may be performed with \word{ACCEPT}
and \word{EVALUATE}.
\end{rationale}
\end{worddef}
\begin{worddef}{2240}{SPAN}
\item \stack{}{a-addr}
\param{a-addr} is the address of a cell containing the count of
characters stored by the last execution of \word{EXPECT}.
\end{worddef}
\begin{worddef}{2290}{TIB}[t-i-b]
\item \stack{}{c-addr}
\param{c-addr} is the address of the terminal input buffer.
\note
This function has been superseded by \wref{core:SOURCE}{SOURCE}.
\begin{rationale} % A.6.2.2290 TIB
The function of \word{TIB} has been superseded by
\word{SOURCE}.
\end{rationale}
\end{worddef}
\subsection{Legacy extension words} % x.x.2
\extended
None.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment