From dfb9d2329d974c26425e2a85d7b030bd956b6193 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Fri, 29 Apr 2005 19:02:59 +0000 Subject: [PATCH] latest I/O and FFI changes --- doc/handbook.tex | 77 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/doc/handbook.tex b/doc/handbook.tex index 21b6dcd743..8239f8dbc2 100644 --- a/doc/handbook.tex +++ b/doc/handbook.tex @@ -125,6 +125,7 @@ The following abbreviations have conventional meaning in stack effect comments: \begin{description} \item[\texttt{[ x y z ]}] a list with elements whose types are hinted at by \texttt{x}, \texttt{y}, \texttt{z} \item[\texttt{[[ x y ]]}] a cons cell where the type of the cdr is hinted at by \texttt{x}, and the type of the cdr is hinted at by \texttt{y} +\item[\texttt{ch}] an integer representing a Unicode character \item[\texttt{elt}] an arbitrary object that happends to be an element of a collection \item[\texttt{i}] a loop counter or index \item[\texttt{j}] a loop counter or index @@ -990,7 +991,7 @@ The following diagram illustrates the nesting of exception handlers on the catch \end{center} \end{figure} -\subsubsection{Multitasking} +\subsubsection{\label{threads}Multitasking} Factor implements co-operative multitasking, where the thread of control switches between tasks at explicit calls to \texttt{yield}, as well as when blocking I/O is performed. Multitasking is implemented via continuations. \wordtable{ @@ -2865,7 +2866,14 @@ Cotangent&\texttt{cot}&\texttt{coth}&\texttt{acot}&\texttt{acoth} description={a source or sink of characters supporting some subset of the stream protocol, used as an end-point for input/output operations}} Input and output is centered around the concept of a \emph{stream}, which is a source or -sink of characters. +sink of characters. Streams also support formatted output, which may be used to present styled text in a manner independent of output medium. A few stream implementations are provided by the library. + +\begin{description} +\item[File streams] read and write local files. +\item[Network streams] connect to servers and accept connections from clients. +\item[HTML streams] implement the formatted output protocol to generate HTML from styled text attributes, then direct the HTML to an underlying stream. +\item[String streams] direct output to a string buffer. +\end{description} \subsection{Stream protocol} \glossary{name=input stream, @@ -2873,13 +2881,76 @@ description={a stream that implements the \texttt{stream-readln} and \texttt{str \glossary{name=output stream, description={a stream that implements the \texttt{stream-write-attr}, \texttt{stream-flush} and \texttt{stream-auto-flush} generic words and can be used for character output}} +There are various subsets of the stream protocol that a class can implement so that its instances may be used as streams. The following generic word is mandatory. + +\wordtable{ +\genericword{stream-close}{stream-close ( s -- )}{streams} +} +Releases any external resources associated with the stream, such as file handles and network connections. No further operations can be performed on the stream after this call. + +You must close streams after you are finished working with them. A convenient way to automate this is by using the \texttt{with-stream} word in \ref{stdio}. + +The following two words are optional, and should be implemented on input streams. +\wordtable{ +\genericword{stream-readln}{stream-readln ( s -- str/f )}{streams} +} +Reads a line of text and outputs it on the stack. If the end of the stream has been reached, outputs \texttt{f}. The precise meaning of a ``line'' depends on the stream; with file and network streams, it is a range of characters terminated by \verb|\n|, \verb|\r| or \verb|\r\n|. +\wordtable{ +\genericword{stream-read}{stream-read ( n s -- str )}{streams} +} +Reads \texttt{n} characters from the stream. If less than \texttt{n} characters are available before the end of the stream, a shorter string is output. + +The following three words are optional, and should be implemented on output streams. + +\wordtable{ +\genericword{stream-write-attr}{stream-write-attr ( str/ch attrs s -- )}{streams} +} +Outputs a character or string to the stream. This might not result in immediate output to the underlying resource if the stream performs buffering, like all file and network streams do. + +The \texttt{attrs} parameter is an association list holding style information, and it may be ignored. See \ref{style} for a full description. Foramtted output is a relatively rare case so most of the time either the \texttt{stream-write} or \texttt{stream-print} word is used. They are described in the next section. + +\wordtable{ +\genericword{stream-flush}{stream-flush ( s -- )}{streams} +} +Blocks until all pending output operations are been complete. +\wordtable{ +\genericword{stream-auto-flush}{stream-auto-flush ( s -- )}{streams} +} +Ensures the user sees prior output. It is not as strong as \texttt{stream-flush}. The contract is as follows: if the stream is connected to an interactive end-point such as a terminal, \texttt{stream-auto-flush} should execute \texttt{stream-flush}. If the stream is a file or network stream used for ``batch'' operations, this word should have an empty definition. + +The \texttt{stream-print} word executes \texttt{stream-auto-flush} after each line of output. + +With some streams, the above operations may suspend the current thread and execute other threads until input data is available (\ref{threads}). + +\subsection{Stream utilities} + +The following three words are implemented in terms of the stream protocol, and should work with any stream supporting the required underlying operations. +\wordtable{ +\ordinaryword{stream-read1}{stream-read1 ( stream -- ch/f )}{streams} +} +Reads a single character using \texttt{stream-read} and outputs the character. If the end of the stream has been reached, outputs \texttt{f}. +\wordtable{ +\ordinaryword{stream-write}{stream-write ( string stream -- )}{streams} +} +Outputs a character or string to the stream, without any specific style information. Implemented as follows: +\begin{verbatim} +: stream-write ( string stream -- ) + f swap stream-write-attr ; +\end{verbatim} +\wordtable{ +\ordinaryword{stream-print}{stream-print ( string stream -- )}{streams} +} +Outputs a character or string to the stream, followed by a newline, then executes \texttt{stream-auto-flush} to force the line to be displayed on interactive streams. + +\subsection{\label{stdio}The standard input/output stream} + \subsection{Reading and writing files} \subsubsection{File system metadata} \subsection{TCP/IP networking} -\subsection{Formatted output} +\subsection{\label{style}Formatted output} \subsection{Special streams}