facility.tex

% !TeX root = forth.tex
% !TeX spellcheck = en_US
% !TeX program = pdflatex

\chapter{The optional Facility word set} % 10
\wordlist{facility}

\section{Introduction} % 10.1

\section{Additional terms and notation} % 10.2
None.

\section{Additional usage requirements} % 10.3


\subsection{Data types} % 10.3.1

Append table \ref{facility:types} to table \ref{table:datatypes}.

\begin{table}[h]
  \begin{center}
	\caption{Data types}
	\label{facility:types}
	\begin{tabular}{llr}
	\hline\hline
	\emph{Symbol} & \emph{Data type} & \emph{Size on stack} \\
	\hline
	\emph{struct-sys}
	& data structures
	& implementation dependent \\
	\hline\hline
	\end{tabular}
  \end{center}
\end{table}

\subsubsection{Structure type} % 10.3.1.1

The implementation-dependent data generated upon beginning to compile
a \word{BEGIN-STRUCTURE} {\ldots} \word{END-STRUCTURE} structure and
consumed at its close is represented by the symbol \param{struct-sys}
throughout this standard.

\subsubsection{Character types} % 10.3.1.2
Programs that use more than seven bits of a character by
\word{EKEY} have an environmental dependency.

See: \xref[3.1.2 Character types]{usage:char}.


\section{Additional documentation requirements} % 10.4

\subsection{System documentation} % 10.4.1

\subsubsection{Implementation-defined options} % 10.4.1.1

\begin{itemize}
\item encoding of keyboard events \wref{facility:EKEY}{EKEY});
\item duration of a system clock tick;
\item repeatability to be expected from execution of
	\wref{facility:MS}{MS}.
\end{itemize}

\subsubsection{Ambiguous conditions} % 10.4.1.2

\begin{itemize}
\item \wref{facility:AT-XY}{AT-XY} operation can't be performed on
	user output device;

\item A \param{name} defined by
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}
	is executed before the corresponding \linebreak
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}
	has been executed.
\end{itemize}

\subsubsection{Other system documentation} % 10.4.1.3

\begin{itemize}
\item no additional requirements.
\end{itemize}

\subsection{Program documentation} % 10.4.2

\subsubsection{Environmental dependencies} % 10.4.2.1

\begin{itemize}
\item using more than seven bits of a character in
	\wref{facility:EKEY}{EKEY}.
\end{itemize}

\subsubsection{Other program documentation} % 10.4.2.2

\begin{itemize}
\item no additional requirements.
\end{itemize}

\section{Compliance and labeling} % 10.5

\subsection{Forth-\snapshot{} systems} % 10.5.1

The phrase ``Providing the Facility word set'' shall be appended to
the label of any Standard System that provides all of the Facility
word set.

The phrase ``Providing \emph{name(s)} from the Facility Extensions
word set'' shall be appended to the label of any Standard System
that provides portions of the Facility Extensions word set.

The phrase ``Providing the Facility Extensions word set'' shall be
appended to the label of any Standard System that provides all of
the Facility and Facility Extensions word sets.

\subsection{Forth-\snapshot{} programs} % 10.5.2

The phrase ``Requiring the Facility word set'' shall be appended to
the label of Standard Programs that require the system to provide
the Facility word set.

The phrase ``Requiring \emph{name(s)} from the Facility Extensions
word set'' shall be appended to the label of Standard Programs that
require the system to provide portions of the Facility Extensions
word set.

The phrase ``Requiring the Facility Extensions word set'' shall be
appended to the label of Standard Programs that require the system
to provide all of the Facility and Facility Extensions word sets.

\section{Glossary} % 10.6

\subsection{Facility words} % 10.6.1

\begin{worddef}{0742}{AT-XY}[at-x-y]
\item \stack{u_1 u_2}{}

	Perform implementation-dependent steps so that the next
	character displayed will appear in column \param{u_1}, row
	\param{u_2} of the user output device, the upper left corner
	of which is column zero, row zero. An ambiguous condition exists
	if the operation cannot be performed on the user output device
	with the specified parameters.
\end{worddef}

\vspace*{-3ex}
\begin{worddef}[KEYq]{1755}{KEY?}[key-question]
\item \stack{}{flag}

	If a character is available, return \emph{true}. Otherwise,
	return \emph{false}. If non-character keyboard events are
	available before the first valid character, they are discarded
	and are subsequently unavailable. The character shall be
	returned by the next execution of \word[core]{KEY}.

	After \word{KEYq} returns with a value of \emph{true},
	subsequent executions of \word{KEYq} prior to the execution
	of \word[core]{KEY} or \word{EKEY} also return \emph{true},
	without discarding keyboard events.

\see \rref{facility:KEYq}{}.

	\begin{rationale} % A.10.6.1.1755 KEY?
		The committee has gone around several times on the
		stack effects. Whatever is decided will violate somebody's
		practice and penalize some machine. This way doesn't interfere
		with type-ahead on some systems, while requiring the
		implementation of a single-character buffer on machines where
		polling the keyboard inevitably results in the destruction of
		the character.

		Use of \word[core]{KEY} or \word{KEYq} indicates that the
		application does not wish to process non-character events,
		so they are discarded, in anticipation of eventually receiving
		a valid character. Applications wishing to handle non-character
		events must use \word{EKEY} and \word{EKEYq}. It is possible
		to mix uses of \word{KEYq}/\word[core]{KEY} and
		\word{EKEYq}/\word{EKEY} within a single application, but
		the application must use \word{KEYq} and \word[core]{KEY} only
		when it wishes to discard non-character events until a valid
		character is received.
		\newpage
	\end{rationale}
\end{worddef}

\vspace*{-3ex}
\enlargethispage{4ex}
\begin{worddef}{2005}{PAGE}
\item \stack{}{}

	Move to another page for output. Actual function depends on the
	output device. On a terminal, \word{PAGE} clears the screen and
	resets the cursor position to the upper left corner. On a
	printer, \word{PAGE} performs a form feed.
\end{worddef}


\subsection{Facility extension words} % 10.6.2
\extended

% -------------------------------------

\begin{worddef}{0135}{+FIELD}[plus-field]%[X:structures]
\item \stack{n_1 n_2 "<spaces>name"}{n_3}

	Skip leading space delimiters.  Parse \param{name} delimited
	by a space.  Create a definition for \param{name} with the
	execution semantics defined below.  Return \param{n_3} =
	\param{n_1} + \param{n_2} where \param{n_1} is the offset
	in the data structure before \word{+FIELD} executes, and
	\param{n_2} is the size of the data to be added to the data
	structure. \param{n_1} and \param{n_2} are in address units.

\execute[name]
	\stack{addr_1}{addr_2}

	Add \param{n_1} to \param{addr_1} giving \param{addr_2}.

\see \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE},
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\
	\wref{facility:CFIELD:}{CFIELD:},
	\wref{facility:FIELD:}{FIELD:},
	\wref{floating:FFIELD:}{FFIELD:}, \\
	\wref{floating:SFFIELD:}{SFFIELD:},
	\wref{floating:DFFIELD:}{DFFIELD:},
	\rref{facility:+FIELD}{}.

	\begin{rationale} % A.10.6.2.0135 +FIELD
		\word{+FIELD} is not required to align items.  This is
		deliberate and allows the construction of unaligned data
		structures for communication with external elements such
		as a hardware register map or protocol packet.
		Field alignment has been left to the appropriate
		\emph{x}\texttt{FIELD:} definition.
	\end{rationale}

	\begin{implement} % I.10.6.2.0135 +FIELD
		\textdf{Create a new field within a structure definition
			of size \param{n} bytes.}

		\word{:} +FIELD\tab\word{bs} n <"name"> -{}- ; Exec: addr -{}- 'addr \\
		\tab \word{CREATE} \word{OVER} \word{,} \word{+} \\
		\tab \word{DOES} \word{@} \word{+} \\
		\word{;}
	\end{implement}
\end{worddef}


\begin{worddef}{0763}{BEGIN-STRUCTURE}[]%[X:structures]
\item \stack{"<spaces>name"}{struct-sys 0}

	Skip leading space delimiters. Parse \param{name} delimited
	by a space. Create a definition for \param{name} with the
	execution semantics defined below.  Return a \param{struct-sys}
	(zero or more implementation dependent items) that will be
	used by \word{END-STRUCTURE} and an initial offset of 0.

\execute[name]
	\stack{}{+n}

	\param{+n} is the size in memory expressed in address units of
	the data structure.  An ambiguous condition exists if
	\param{name} is executed prior to the associated
	\word{END-STRUCTURE} being executed.

\see \wref{facility:+FIELD}{+FIELD},
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\
	\rref{facility:BEGIN-STRUCTURE}{}.


	\begin{rationale} % A.10.6.2.0763 BEGIN-STRUCTURE
		There are two schools of thought regarding named data
		structures: name first and name last.  The name last
		school can define a named data structure as follows:

		\begin{quote}\ttfamily
		0 \tab[11.5] \word{bs} initial total byte count \\
		\tab 1 \word{CELLS} \word{+FIELD} p.x	\tab \word{bs} A single cell filed named p.x \\
		\tab 1 \word{CELLS} \word{+FIELD} p.y   \tab \word{bs} A single cell field named p.y \\
		\word{CONSTANT} point \tab[3.8] \word{bs} save structure size
		\end{quote}

		While the name first school would define the same data
		structure as:

		\begin{quote}\ttfamily
		\word{BEGIN-STRUCTURE} point \tab[-.3] \word{bs} create the named structure \\
		\tab 1 \word{CELLS} \word{+FIELD} p.x	\tab \word{bs} A single cell filed named p.x \\
		\tab 1 \word{CELLS} \word{+FIELD} p.y   \tab \word{bs} A single cell field named p.y \\
		\word{END-STRUCTURE}
		\end{quote}

		Although many systems provide a name first structure there
		is no common practice to the words used.  The words
		\word{BEGIN-STRUCTURE} and \word{END-STRUCTURE} have been
		defied as a means of providing a portable notation that does
		not conflict with existing systems.

		The field defining words (\emph{x}\texttt{FIELD:} and
		\word{+FIELD}) are defined so they can be used by both
		schools.  Compatibility between the two schools comes from
		defining a new stack item \param{struct-sys}, which is
		implementation dependent and can be 0 or more cells.
		The name first school would provide an address (\param{addr})
		as the \param{struct-sys} parameter, while the name last
		school would defined \param{struct-sys} as being empty.

		Executing the name of the data structure, returns the size of
		the data structure.  This allows the data stricture to be used
		within another data structure:

		\begin{quote}\ttfamily
		\word{BEGIN-STRUCTURE} point \tab[-0.1] \word{bs} -{}- a-addr 0 ; -{}- lenp \\
		\tab \word{FIELD:} p.x		\tab[5.5] \word{bs} -{}- a-addr cell \\
		\tab \word{FIELD:} p.y      \tab[5.5] \word{bs} -{}- a-addr cell*2 \\
		\word{END-STRUCTURE} \\

		\word{BEGIN-STRUCTURE} rect  \tab[1.3]\word{bs} -{}- a-addr 0 ; -{}- lenr \\
		\tab point \word{+FIELD} r.tlhc   \tab \word{bs} -{}- a-addr cell*2 \\
		\tab point \word{+FIELD} r.brhc   \tab \word{bs} -{}- a-addr cell*4 \\
		\word{END-STRUCTURE}
		\end{quote}

	\item[Alignment] ~\\
		In practice, structures are used for two different purposes
		with incompatible requirements:
		\begin{enumerate}
		\item For collecting related internal-use data into a
			convenient ``package'' that can be referred to by a
			single ``handle''. For this use, alignment is important,
			so that efficient native fetch and store instructions
			can be used.

		\item For mapping external data structures like hardware
			register maps and protocol packets. For this use,
			automatic alignment is inappropriate, because the
			alignment of the external data structure often doesn't
			match the rules for a given processor.
		\end{enumerate}

		Many languages cater for the first use, but ignore the
		second.  This leads to various customized solutions, usage
		requirements, portability problems, bugs, etc.
		\word{+FIELD} is defined to be non-a\-lign\-ing, while the
		named field defining words (\emph{x}\texttt{FIELD:}) are
		aligning.  This is intentional and allows for both uses.

		The standard currently defines an aligned field defining
		word for each of the standard data types:

		\begin{center}
			\begin{tabular}{rl}
		\word{CFIELD:}					& a character \\
		\word{FIELD:}					& a native integer (single cell) \\
		\word[floating]{FFIELD:}	& a native float \\
		\word[floating]{SFFIELD:}	& a 32 bit float \\
		\word[floating]{DFFIELD:}	& a 64 bit float
			\end{tabular}
		\end{center}

		Although this is a sufficient set, most systems provide
		facilities to define field defining words for standard
		data types.
		% Note that these also satisfy the alignment requirements of
		% the host system, whereas \word{+FIELD} does not.

	\item[Future] ~\\
		The following cannot be defined until the required addressing
		has been defined. The names should be considered reserved
		until then.

		\begin{center}
			\begin{tabular}{rl}
			\texttt{BFIELD:} & 1 byte (8 bit) field \\
			\texttt{WFIELD:} & 16 bit field \\
			\texttt{LFIELD:} & 32 bit field \\
			\texttt{XFIELD:} & 64 bit field \\
			\end{tabular}
		\end{center}
	\end{rationale}

	\begin{implement} % I.10.6.2.0763 BEGIN-STRUCTURE
		\textdf{Begin definition of a new structure. Use in the
		form \word{BEGIN-STRUCTURE} \arg{name}.  At run time
		\arg{name} returns the size of the structure.}

		\word{:} \word{BEGIN-STRUCTURE}\tab\word{bs} -{}- addr 0 ; -{}- size \\
		\tab \word{CREATE} \\
		\tab[2] \word{HERE} 0  0 \word{,} \tab[2] \word{bs}  mark stack, lay dummy \\
		\tab \word{DOES} \word{@} \tab[6]\word{bs} -{}- rec-len \\
		\word{;}
	\end{implement}
\end{worddef}

\enlargethispage{4ex}
\begin{worddef}{0893}{CFIELD:}[c-field-colon]%[X:structures]
\item \stack{n_1 "<spaces>name"}{n_2}

	Skip leading space delimiters. Parse \param{name} delimited by
	a space. \param{Offset} is the first character aligned value
	greater than or equal to \param{n_1}.  \param{n_2 = offset + 1}
	character.

	Create a definition for \param{name} with the execution semantics
	given below.

\execute[name]
	\stack{addr_1}{addr_2}

	Add the \param{offset} calculated during the compile-time action to
	\param{addr_1} giving the address \param{addr_2}.

\see \wref{facility:+FIELD}{+FIELD},
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\
	\wref{facility:END-STRUCTURE}{END-STRUCTURE},
	\rref{facility:FIELD:}{}.
\end{worddef}

% -------------------------------------

\begin{worddef}{1305}{EKEY}[e-key]
\item \stack{}{x}

	Receive one keyboard event \param{x}. The encoding of keyboard events
	is implementation defined.

\see \wref{core:KEY}{KEY},
	\wref{facility:KEYq}{KEY?},
	\rref{facility:EKEY}{}.


	\begin{rationale} % A.10.6.2.1305 EKEY
		For some input devices, such as keyboards, more information is
		available than can be returned by a single execution of
		\word{KEY}.  \word{EKEY} provides a standard word to access a
		system-dependent set of events.

		\word{EKEY} and \word{EKEYq} are implementation specific; no
		assumption can be made regarding the interaction between the
		pairs \word{EKEY}/\word{EKEYq} and \word{KEY}/\word{KEYq}.
		This standard does not define a timing relationship between
		\word{KEYq} and \word{EKEYq}.  Undefined results may be
		avoided by using only one pairing of \word{KEY}/ \word{KEYq}
		or \word{EKEY}/\word{EKEYq} in a program for each input
		stream.

		\word{EKEY} assumes no particular numerical correspondence
		between particular event code values and the values
		representing standard characters.  On some systems, this may
		allow two separate keys that correspond to the same standard
		character to be distinguished from one another.  A standard
		program may only interpret the results of \word{EKEY} via the
		translation words provided for that purpose
		(\word{EKEYtoCHAR} and \word{EKEYtoFKEY}).

		See: \rref{core:KEY}{}, \wref{facility:EKEYtoCHAR}{} and
		\wref{facility:EKEYtoFKEY}{}.
	\end{rationale}
\end{worddef}


\begin{worddef}[EKEYtoCHAR]{1306}{EKEY>CHAR}[e-key-to-char]
\item \stack{x}{x false | char true}

	If the keyboard event \param{x} corresponds to a character in the
	implementation-defined character set, return that character and
	\emph{true}. Otherwise return \param{x} and \emph{false}.

\see \rref{facility:EKEYtoCHAR}{}.

	\begin{rationale} % A.10.6.2.1306 EKEY>CHAR
		\word{EKEYtoCHAR} translates a keyboard event into the
		corresponding member of the character set, if such a
		correspondence exists for that event.

		It is possible that several different keyboard events may
		correspond to the same character, and other keyboard events
		may correspond to no character.
	\end{rationale}
\end{worddef}


% -------------------------------------------------------------------

\begin{worddef}[EKEYtoFKEY]{1306}[40]{EKEY>FKEY}[e-key-to-f-key]%[X:ekeys]
\item \stack{x}{u flag}

	If the keyboard event \param{x} corresponds to a keypress in the
	implementation-defined special key set, return that key's id
	\param{u} and \param{true}. Otherwise return \param{x} and
	\param{false}.

\note
	The keyboard may lack some of the keys, or the capability to report
	them. Programs should be written such that they also work (although
	less conveniently or with less functionality) if these key numbers
	cannot be produced.

\see
	\wref{facility:EKEY}{EKEY},
	\wref{facility:K-ALT-MASK}{K-ALT-MASK},
	\wref{facility:K-CTRL-MASK}{K-CTRL-MASK}, \linebreak
	\wref{facility:K-DELETE}{K-DELETE},
	\wref{facility:K-DOWN}{K-DOWN},
	\wref{facility:K-END}{K-END}, \linebreak
	\wref{facility:K-F1}{K-F1},
	\wref{facility:K-F10}{K-F10},
	\wref{facility:K-F11}{K-F11}, \linebreak
	\wref{facility:K-F12}{K-F12},
	\wref{facility:K-F2}{K-F2},
	\wref{facility:K-F3}{K-F3}, \linebreak
	\wref{facility:K-F4}{K-F4},
	\wref{facility:K-F5}{K-F5},
	\wref{facility:K-F6}{K-F6}, \linebreak
	\wref{facility:K-F7}{K-F7},
	\wref{facility:K-F8}{K-F8},
	\wref{facility:K-F9}{K-F9}, \linebreak
	\wref{facility:K-HOME}{K-HOME},
	\wref{facility:K-INSERT}{K-INSERT},
	\wref{facility:K-LEFT}{K-LEFT}, \linebreak
	\wref{facility:K-NEXT}{K-NEXT},
	\wref{facility:K-PRIOR}{K-PRIOR},
	\wref{facility:K-RIGHT}{K-RIGHT}, \linebreak
	\wref{facility:K-SHIFT-MASK}{K-SHIFT-MASK},
	\wref{facility:K-UP}{K-UP}, \linebreak
	\rref{facility:EKEYtoFKEY}{}.


	\begin{rationale} % A.10.6.2.1306.40 EKEY>FKEY
		\word{EKEY} produces an abstract cell type for a keyboard
		event (e.g., a keyboard scan code).  \word{EKEYtoFKEY} checks
		if such an event corresponds to a special (non-graphic) key
		press, and if so, returns a code for the special key press.
		The encoding of special keys (returned by \word{EKEYtoFKEY})
		may be different from the encoding of these keys as keyboard
		events (input to \word{EKEYtoFKEY}).

		Typical Use:

		\begin{quote}
			{\ldots} \word{EKEY} \word{EKEYtoFKEY} \word{IF} \\
			\tab \word{CASE} \\
			\tab[2] \word{K-UP} \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] \word{K-F1} \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] \word{K-LEFT} \word{K-SHIFT-MASK} \word{OR}
			                      \word{K-CTRL-MASK} \word{OR}
			                    \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] {\ldots} \\
			\tab \word{ENDCASE} \\
			\word{ELSE} \\
			\tab {\ldots} \\
			\word{THEN}
		\end{quote}

		The codes for the special keys are system-dependent, but this
		standard provides words for getting the key codes for a number
		of keys:

		\begin{center}
			\begin{tabular}{llcll}
			\hline
			Word & Key & \hspace{2em} & Word & Key \\ \hline\hline
			\word{K-F1}		& F1	& & \word{K-LEFT}	& cursor left	\\
			\word{K-F2}		& F2	& & \word{K-RIGHT}	& cursor right	\\
			\word{K-F3}		& F3	& & \word{K-UP}		& cursor up		\\
			\word{K-F4}		& F4	& & \word{K-DOWN}	& cursor down	\\
			\word{K-F5}		& F5	& & \word{K-HOME}	& home or Pos1	\\
			\word{K-F6}		& F6	& & \word{K-END}	& End			\\
			\word{K-F7}		& F7	& & \word{K-PRIOR}	& PgUp or Prior	\\
			\word{K-F8}		& F8	& & \word{K-NEXT}	& PgDn or Next	\\
			\word{K-F9}		& F9	& & \word{K-INSERT}	& Insert		\\
			\word{K-F10}	& F10	& & \word{K-DELETE}	& Delete		\\
			\word{K-F11}	& F11	\\
			\word{K-F12}	& F12	\\ \hline
			\end{tabular}
		\end{center}

		In addition, you can get codes for shifted variants of these
		keys by \word{OR}ing with \word{K-SHIFT-MASK}, \word{K-CTRL-MASK}
		and/or \word{K-ALT-MASK}, e.g. \word{K-CTRL-MASK}
		\word{K-ALT-MASK} \word{OR} \word{K-DELETE} \word{OR}.
		The masks for the shift keys are:

		\begin{center}
			\begin{tabular}{ll}
			\hline
			Word 				& Key	\\ \hline\hline
			\word{K-SHIFT-MASK}	& Shift	\\
			\word{K-CTRL-MASK}	& Ctrl	\\
			\word{K-ALT-MASK}	& Alt	\\ \hline
			\end{tabular}
		\end{center}

		Note that not all of these keys are available on all systems, and not
		all combinations of keys and shift keys are available.  Therefore
		programs should be written such that they continue to work (although
		less conveniently or with less functionality) if these key combinations
		cannot be produced.
	\end{rationale}

	\begin{implement} % I.10.6.2.1306.40 EKEY>FKEY
		\textdf{The implementation is closely tied to the implementation
			of \word{EKEY} and therefore unportable.}
	\end{implement}

	\begin{testing} % T.10.6.2.1306.40 EKEY>FKEY
		\ttfamily
		\word{:} TFKEY" \word{p} "ccc<quote>" -{}- u flag ) \\
		\tab[1.2] \word{CR} \word{.q} Please press " \word{POSTPONE} \word[file]{.q} \word{EKEY} \word{EKEYtoFKEY} \word{;}

		\test{TFKEY" <left>" }{\word{K-LEFT}  <TRUE>} \\
		\test{TFKEY" <right>"}{\word{K-RIGHT} <TRUE>} \\
		\test{TFKEY" <up>"   }{\word{K-UP}    <TRUE>} \\
		\test{TFKEY" <down>" }{\word{K-DOWN}  <TRUE>} \\
		\test{TFKEY" <home>" }{\word{K-HOME}  <TRUE>} \\
		\test{TFKEY" <end>"  }{\word{K-END}   <TRUE>} \\
		\test{TFKEY" <prior>"}{\word{K-PRIOR} <TRUE>} \\
		\test{TFKEY" <next>" }{\word{K-NEXT}  <TRUE>}

		\test{TFKEY" <F1>" }{\word{K-F1}  <TRUE>} \\
		\test{TFKEY" <F2>" }{\word{K-F2}  <TRUE>} \\
		\test{TFKEY" <F3>" }{\word{K-F3}  <TRUE>} \\
		\test{TFKEY" <F4>" }{\word{K-F4}  <TRUE>} \\
		\test{TFKEY" <F5>" }{\word{K-F5}  <TRUE>} \\
		\test{TFKEY" <F6>" }{\word{K-F6}  <TRUE>} \\
		\test{TFKEY" <F7>" }{\word{K-F7}  <TRUE>} \\
		\test{TFKEY" <F8>" }{\word{K-F8}  <TRUE>} \\
		\test{TFKEY" <F9>" }{\word{K-F9}  <TRUE>} \\
		\test{TFKEY" <F10>"}{\word{K-F10} <TRUE>} \\
		\test{TFKEY" <F11>"}{\word{K-F11} <TRUE>} \\
		\test{TFKEY" <F11>"}{\word{K-F12} <TRUE>}

		\test{TFKEY" <shift-left>"}{\word{K-LEFT} \word{K-SHIFT-MASK} \word{OR} <TRUE>} \\
		\test{TFKEY" <ctrl-left>" }{\word{K-LEFT} \word{K-CTRL-MASK}  \word{OR} <TRUE>} \\
		\test{TFKEY" <alt-left>"  }{\word{K-LEFT} \word{K-ALT-MASK}   \word{OR} <TRUE>}

		\test{TFKEY" <a>" \word{SWAP} \word{EKEYtoCHAR}}{<FALSE> CHAR a <TRUE>} \\
	\end{testing}
\end{worddef}


% -------------------------------------------------------------------

\begin{worddef}[EKEYq]{1307}{EKEY?}[e-key-question]
\item \stack{}{flag}

	If a keyboard event is available, return \emph{true}. Otherwise
	return \emph{false}. The event shall be returned by the next
	execution of \word{EKEY}.

	After \word{EKEYq} returns with a value of \emph{true},
	subsequent executions of \word{EKEYq} prior to the execution of
	\word[core]{KEY}, \word{KEYq} or \word{EKEY} also return
	\emph{true}, referring to the same event.
\end{worddef}


\begin{worddef}[EMITq]{1325}{EMIT?}[emit-question]
\item \stack{}{flag}

	\param{flag} is true if the user output device is ready to
	accept data and the execution of \word[core]{EMIT} in place of
	\word{EMITq} would not have suffered an indefinite delay. If
	the device status is indeterminate, \emph{flag} is true.

\see \rref{facility:EMITq}{}.

	\begin{rationale} % A.10.6.2.1325 EMIT?
		An indefinite delay is a device related condition, such as
		printer off-line, that requires operator intervention before
		the device will accept new data.
	\end{rationale}
\end{worddef}

% -------------------------------------
\vspace*{-2ex}
\begin{worddef}{1336}{END-STRUCTURE}[]%[X:structures]
\item \stack{struct-sys +n}{}

	Terminate definition of a structure started by
	\word{BEGIN-STRUCTURE}.

\see \wref{facility:+FIELD}{+FIELD},
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}.

	\begin{implement} % I.10.6.2.1336 END-STRUCTURE
		\textdf{Terminate definition of a structure.}

		\word{:} \word{END-STRUCTURE}\tab\word{bs} addr n -{}- \\
		\tab \word{SWAP} \word{!} \word{;} \tab[4.2]\word{bs} set len
	\end{implement}
\end{worddef}

\vspace*{-2ex}
\begin{worddef}{1518}{FIELD:}[field-colon]%[X:structures]
\item \stack{n_1 "<spaces>name"}{n_2}

	Skip leading space delimiters. Parse \param{name} delimited by
	a space. \param{Offset} is the first cell aligned value greater
	than or equal to \param{n_1}.  \param{n_2 = offset + 1} cell.

	Create a definition for \param{name} with the execution semantics
	given below.

\execute[name]
	\stack{addr_1}{addr_2}

	Add the \param{offset} calculated during the compile-time action
	to \param{addr_1} giving the address \param{addr_2}.

\see \wref{facility:+FIELD}{+FIELD},
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\
	\wref{facility:END-STRUCTURE}{END-STRUCTURE},
	\rref{facility:FIELD:}{}.

	\begin{rationale}
		Create an aligned single-cell field in a data structure.

		The various \emph{x}\texttt{FIELD:} words provide for different
		alignment and size allocation.

		The \emph{x}\texttt{FIELD:} words could be defined as:

		\begin{tabbing}
			\tab \= \tab[6] \= \tab[22] \= \tab[5] \= \tab[5.2] \= \kill
			\> \word{:} \word{FIELD:}   \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{ALIGNED}   \' 1 \word{CELLS}   \> \word{+FIELD} \word{;} \\
			\> \word{:} \word{CFIELD:}  \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\>                  \' 1 \word{CHARS}   \> \word{+FIELD} \word{;} \\
		\setwordlist{floating}
			\> \word{:} \word{FFIELD:}  \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{FALIGNED}  \' 1 \word{FLOATS}  \> \word[facility]{+FIELD} \word{;} \\
			\> \word{:} \word{SFFIELD:} \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{SFALIGNED} \' 1 \word{SFLOATS} \> \word[facility]{+FIELD} \word{;} \\
			\> \word{:} \word{DFFIELD:} \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{DFALIGNED} \' 1 \word{DFLOATS} \> \word[facility]{+FIELD} \word{;}
		\setwordlist{facility}
		\end{tabbing}
	\end{rationale}
\end{worddef}

% -------------------------------------------------------------------

\vspace*{-2ex}
\begin{worddef}{1740}[01]{K-ALT-MASK}[]%[X:ekeys]
\item \stack{}{u}

	Mask for the \textsc{Alt} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\vspace*{-2ex}
\enlargethispage{4ex}
\begin{worddef}{1740}[02]{K-CTRL-MASK}[]%[X:ekeys]
\item \stack{}{u}

	Mask for the \textsc{Ctrl} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[03]{K-DELETE}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``Delete'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[04]{K-DOWN}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor down'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[05]{K-END}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``End'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[06]{K-F1}[k-f-1]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F1'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[07]{K-F10}[k-f-10]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F10'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[08]{K-F11}[k-f-11]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F11'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[09]{K-F12}[k-f-12]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F12'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[10]{K-F2}[k-f-2]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F2'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[11]{K-F3}[k-f-3]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F3'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[12]{K-F4}[k-f-4]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F4'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[13]{K-F5}[k-f-5]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F5'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[14]{K-F6}[k-f-6]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F6'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[15]{K-F7}[k-f-7]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F7'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[16]{K-F8}[k-f-8]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F8'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[17]{K-F9}[k-f-9]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F9'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[18]{K-HOME}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``home'' or ``Pos1'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[19]{K-INSERT}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``Insert'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[20]{K-LEFT}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor left'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[21]{K-NEXT}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``PgDn'' (Page Down) or ``Next'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[22]{K-PRIOR}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``PgUp'' (Page Up) or ``Prior'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[23]{K-RIGHT}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor right'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[24]{K-SHIFT-MASK}[]%[X:ekeys]
\item \stack{}{u}

	Mask for the \textsc{Shift} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


\begin{worddef}{1740}[25]{K-UP}[]%[X:ekeys]
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor up'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
\end{worddef}


% -------------------------------------------------------------------


\begin{worddef}{1905}{MS}
\item \stack{u}{}

	Wait at least \param{u} milliseconds.

\note
	The actual length and variability of the time period depends
	upon the {im\-ple\-ment\-ation-de\-fin\-ed} resolution of the system clock
	and upon other system and computer characteristics beyond the
	scope of this standard.

\see \rref{facility:MS}{}.

	\begin{rationale} % A.10.6.2.1905 MS
		Although their frequencies vary, every system has a clock.
		Since many programs need to time intervals, this word is
		offered. Use of milliseconds as an internal unit of time is
		a practical ``least common denominator'' external unit. It
		is assumed implementors will use ``clock ticks'' (whatever
		size they are) as an internal unit and convert as appropriate.
	\end{rationale}
\end{worddef}

\enlargethispage{4ex}
\begin{worddef}[TIMEandDATE]{2292}{TIME\&DATE}[time-and-date]
\item \stack{}{+n_1 +n_2 +n_3 +n_4 +n_5 +n_6}

	Return the current time and date.
	\param{+n_1} is the second \{0{\ldots}59\},
	\param{+n_2} is the minute \{0{\ldots}59\},
	\param{+n_3} is the hour \{0{\ldots}23\},
	\param{+n_4} is the day \{1{\ldots}31\},
	\param{+n_5} is the month \{1{\ldots}12\} and
	\param{+n_6} is the year (e.g., 1991).

\see \rref{facility:TIMEandDATE}{}.

	\begin{rationale} % A.10.6.2.2292 TIME&DATE
		Most systems have a real-time clock/calendar.
		This word gives portable access to it.
	\end{rationale}
\end{worddef}