Loading legacy.texdeleted 100644 → 0 +0 −277 Original line number Diff line number Diff line \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. Loading
legacy.texdeleted 100644 → 0 +0 −277 Original line number Diff line number Diff line \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.
