1451 lines
46 KiB
TeX
1451 lines
46 KiB
TeX
%
|
|
% STk Reference manual (Part 1)
|
|
%
|
|
% Author: Erick Gallesio [eg@unice.fr]
|
|
% Creation date: ??-Nov-1993 ??:??
|
|
% Last file update: 18-Apr-1998 14:47
|
|
%
|
|
|
|
\section*{Introduction}
|
|
|
|
This document provides a complete list of procedures and special forms
|
|
implemented in version {\stkversion} of {\stk}. Since {\stk} is (nearly)
|
|
compliant with the language described in the {\em Revised$^{4}$ Report on the
|
|
Algorithmic Language Scheme} \mainindex{R4RS}(denoted {\rrrr} hereafter{\footnote{The {\em
|
|
Revised$^{4}$ Report on the Algorithmic Language Scheme} is available
|
|
through anonymous FTP from {\tt ftp.cs.indiana.edu} in the directory
|
|
{\tt /pub/scheme-repository/doc}}})\cite{R4RS}, the organization of
|
|
this manual follows the {\rrrr} and only describes extensions.
|
|
|
|
\section{Overview of \stk}
|
|
|
|
Today's graphical toolkits for applicative languages are often not
|
|
satisfactory. Most of the time, they ask the user to be an X window system
|
|
\mainindex{X window system} expert and force him/her to cope with arcane
|
|
details such as server connections and event queues. This is a real
|
|
problem, since programmers using this kind of languages are generally not
|
|
inclined to system programming, and few of them will bridge the gap between
|
|
the different abstraction levels.
|
|
|
|
~~~~Tk\index{Tk toolkit}\index{toolkit} is a powerful graphical tool\-kit
|
|
promising to fill that gap. It was developed at the University of Berkeley
|
|
by John Ousterhout~\cite{Ouster-Tk}. The toolkit offers high level widgets
|
|
such as buttons or menus and is easily programmable, requiring little
|
|
knowledge of X fundamentals. Tk relies on an interpretative shell-like
|
|
language named Tcl~\cite{Ouster-Tcl}.
|
|
|
|
~~~~{\stk} is an implementation of the Scheme programming language,
|
|
providing a full integration of the Tk toolkit. In this implementation,
|
|
Scheme establishes the link between the user and the Tk toolkit, replacing
|
|
Tcl.
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{Lexical conventions}
|
|
|
|
\subsection{Identifiers}
|
|
|
|
Syntactic keywords can be used as variables in \stk. Users must be
|
|
aware that this extension of the language could lead to ambiguities in
|
|
some situations.
|
|
|
|
\subsection{Comments}
|
|
|
|
There are three types of comments in {\stk}:
|
|
\begin{enumerate}
|
|
\item a semicolon (;) indicates the start of a comment.
|
|
This kind of comment extends to the end of the line (as described in \rrrr).
|
|
\item multi-lines comment use the classical Lisp convention: a comment
|
|
begins with \verb+#|+ and ends with \verb+|#+.
|
|
\item comments can also be introduced by \sharpsign$!$. This
|
|
extension is particularly useful for building {\stk} scripts. On most
|
|
Unix implementations, if the first line of a script looks like this:
|
|
\begin{scheme}
|
|
\sharpsign$!$/usr/local/bin/stk -file
|
|
\end{scheme}
|
|
then the script can be started directly as if it were a binary. {\stk}
|
|
is loaded behind the scenes and reads and executes the script as a
|
|
Scheme program. Of course this assumes that {\stk} is located in {\tt
|
|
/usr/local/bin}.
|
|
\end{enumerate}
|
|
|
|
|
|
\subsection{Other notations}
|
|
|
|
{\stk} accepts all the notations defined in {\rrrr} plus
|
|
|
|
\begin{description}{}{}
|
|
|
|
\setbox0\hbox{\tt \char"5B{} \char"5D{} }
|
|
\item[\copy0] Brackets are equivalent to parentheses. They are used
|
|
for grouping and to notate lists. A list opened with a left square
|
|
bracket must be closed with a right square bracket
|
|
(section~\ref{listsection}).
|
|
|
|
\item[\tt:] A colon at the beginning of a symbol introduces a keyword.
|
|
Keywords are described in section~\ref{keywords}.
|
|
|
|
\item[\tt\sharpsign.<expr>] is read as the evaluation of the Scheme
|
|
expression {\tt <expr>}. The evaluation is done during the
|
|
\ide{read} process, when the \var{\sharpsign.} is encountered.
|
|
Evaluation is done in the environment of the current module.
|
|
\begin{scheme}
|
|
(define foo 1)
|
|
\sharpsign.foo \lev 1
|
|
'(foo \sharpsign.foo \sharpsign.(+ foo foo)) \lev (foo 1 2)
|
|
(let ((foo 2))
|
|
\sharpsign.foo) \lev 1
|
|
\end{scheme}
|
|
\end{description}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{Basic concepts}
|
|
|
|
{\doc}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{Expressions}
|
|
|
|
\subsection{Primitive expression types}
|
|
|
|
\begin{entry}{%
|
|
\proto{quote}{ \hyper{datum}}{\exprtype}
|
|
\pproto{\singlequote\hyper{datum}}{\exprtype}}
|
|
\saut
|
|
The quoting mechanism is identical to {\rrrr}. Keywords (see
|
|
section~\ref{keywords}), as
|
|
numerical constants, string constants, character constants, and boolean
|
|
constants evaluate ``to themselves''; they need not be quoted.
|
|
\begin{scheme}
|
|
'"abc" \ev "abc"
|
|
"abc" \ev "abc"
|
|
'145932 \ev 145932
|
|
145932 \ev 145932
|
|
'\schtrue \ev \schtrue
|
|
\schtrue \ev \schtrue
|
|
':key \ev {:key}
|
|
:key \ev {:key}
|
|
\end{scheme}
|
|
\begin{note}
|
|
{\rrrr} requires to quote constant lists and constant vectors. This
|
|
is not necessary with {\stk}.
|
|
\end{note}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\pproto{(\hyper{operator} \hyperi{operand} \dotsfoo)}{\exprtype}}
|
|
\saut
|
|
{\doc} Furthermore, \hyper{operator} can be a macro (see section~\ref{macros}).
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{lambda}{ \hyper{formals} \hyper{body}}{\exprtype}
|
|
\proto{if}{ \hyper{test} \hyper{consequent} \hyper{alternate}} {\exprtype}
|
|
\proto{if}{ \hyper{test} \hyper{consequent}}{\exprtype}
|
|
\proto{set!}{ \hyper{variable} \hyper{expression}}{\exprtype}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\subsection{Derived expression types}
|
|
|
|
\begin{entry}{%
|
|
\proto{cond}{ \hyperi{clause} \hyperii{clause} \dotsfoo}{\exprtype}
|
|
\proto{case}{ \hyper{key} \hyperi{clause} \hyperii{clause} \dotsfoo}{\exprtype}
|
|
\proto{and}{ \hyperi{test} \dotsfoo}{\exprtype}
|
|
\proto{or}{ \hyperi{test} \dotsfoo}{\exprtype}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{when}{ \hyper{test} \hyperi{expression} \hyperii{expression} \dotsfoo}{\exprtype}}
|
|
\saut
|
|
If the \hyper{test} expression yields a true value, the \hyper{expression}s are
|
|
evaluated from left to right and the value of the last \hyper{expression} is
|
|
returned.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{unless}{ \hyper{test} \hyperi{expression} \hyperii{expression} \dotsfoo}
|
|
{\exprtype}}
|
|
\saut
|
|
If the \hyper{test} expression yields a false value, the \hyper{expression}s are
|
|
evaluated from left to right and the value of the last \hyper{expression} is
|
|
returned.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{let}{ \hyper{bindings} \hyper{body}}{\exprtype}
|
|
\proto{let}{ \hyper{variable} \hyper{bindings} \hyper{body}}{\exprtype}
|
|
\proto{let*}{ \hyper{bindings} \hyper{body}}{\exprtype}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{fluid-let}{ \hyper{bindings} \hyper{body}}{\exprtype}}
|
|
\saut
|
|
The \var{bindings} are evaluated in the current environment, in some
|
|
unspecified order, the current values of the variables present in
|
|
\var{bindings} are saved, and the new evaluated values are assigned to the
|
|
\var{bindings} variables. Once this is done, the expressions of \var{body}
|
|
are evaluated sequentially in the current environment; the value of the
|
|
last expression is the result of {\tt fluid-let}. Upon exit, the stored
|
|
variables values are restored. An error is signalled if any of the
|
|
\var{bindings} variable is unbound.
|
|
\begin{scheme}
|
|
(let* ((a 'out)
|
|
(f (lambda () a)))
|
|
(list a
|
|
(fluid-let ((a 'in)) (f))
|
|
a)) \lev (out in out)
|
|
\end{scheme}
|
|
When the body of a \ide{fluid-let} is exited by invoking a continuation,
|
|
the new variable values are saved, and the variables are set to their old
|
|
values. Then, if the body is reentered by invoking a continuation, the old
|
|
values are saved and new values are restored. The following example illustrates
|
|
this behaviour
|
|
\begin{scheme}
|
|
(let ((cont \schfalse)
|
|
(l '())
|
|
(a 'out))
|
|
|
|
(set! l (cons a l))
|
|
(fluid-let ((a 'in))
|
|
(set! cont (call/cc (lambda (k) k)))
|
|
(set! l (cons a l)))
|
|
(set! l (cons a l))
|
|
|
|
(if cont (cont \schfalse) l)) \lev (out in out in out)
|
|
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{letrec}{ \hyper{bindings} \hyper{body}}{\exprtype}
|
|
\proto{begin}{ \hyperi{expression} \hyperii{expression} \dotsfoo}{\exprtype}
|
|
\proto{do} { \hyper{inits} \hyper{test} \hyper{body}}{\exprtype}
|
|
\proto{delay}{ \hyper{expression}}{\exprtype}
|
|
\proto{quasiquote}{ \hyper{template}}{\exprtype} \nopagebreak
|
|
\pproto{\backquote\hyper{template}}{\exprtype}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{
|
|
\proto{dotimes}{ (var count) \hyperi{expression} \hyperii{expression} \dotsfoo} {\exprtype}
|
|
\proto{dotimes}{ (var count result) \hyperi{expression} \hyperii{expression} \dotsfoo} {\exprtype}}
|
|
\saut
|
|
|
|
\ide{Dotimes} evaluates the \var{count} form, which must return an
|
|
integer. It then evaluates the \hyper{expression}s once for each
|
|
integer from zero (inclusive) to \var{count} (exclusive), in order,
|
|
with the variable \var{var} bound to the integer; if the value of
|
|
\var{count} is zero or negative, then the \hyper{expression}s are not
|
|
evaluated. When the loop completes, \var{result} is evaluated and its
|
|
value is returned as the value of the \ide{dotimes} expression. If
|
|
\var{result} is omitted, \ide{dotimes} returns {\schfalse}.
|
|
|
|
\begin{scheme}
|
|
(let ((l '()))
|
|
(dotimes (i 4 l)
|
|
(set! l (cons i l)))) \lev (3 2 1 0)
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{
|
|
\proto{while} { \hyper{test} \hyperi{expression} \hyperii{expression} \dotsfoo}{\exprtype}}
|
|
\saut
|
|
\ide{While} evaluates the \hyper{expression}s until \hyper{test}
|
|
returns a false value. The value of a \ide{while} construct is unspecified.
|
|
\end{entry}
|
|
|
|
\begin{entry}{
|
|
\proto{until} { \hyper{test} \hyperi{expression} \hyperii{expression} \dotsfoo}{\exprtype}}
|
|
\saut
|
|
\ide{Until} evaluates the \hyper{expression}s while \hyper{test}
|
|
returns a false value. The value of an \ide{unless} construct is unspecified.
|
|
\end{entry}
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{Program structure}
|
|
|
|
\doc
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{Standard procedures}
|
|
\label{initialenv}
|
|
\label{builtinchapter}
|
|
|
|
\mainindex{initial environment}
|
|
\mainindex{top level environment}
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\subsection{Booleans}
|
|
\label{booleansection}
|
|
|
|
In {\stk} the boolean value {\schfalse} is different from the empty list, as
|
|
required by \rrrr.
|
|
|
|
\begin{entry}{%
|
|
\proto{not}{ obj}{procedure}
|
|
\proto{boolean?}{ obj}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\subsection{Equivalence predicates}
|
|
\label{equivalencesection}
|
|
|
|
\begin{entry}{%
|
|
\proto{eqv?}{ \vari{obj} \varii{obj}}{procedure}}
|
|
\saut
|
|
{\stk} extends the \ide{eqv?} predicate defined in the {\rrrr} to take
|
|
keywords into account: if \vari{obj} and \varii{obj} are both
|
|
keywords, the \ide{eqv?} predicate will yield {\schtrue} if and only
|
|
if
|
|
\begin{scheme}
|
|
(string=? (keyword->string obj1)
|
|
(keyword->string obj2))
|
|
\ev \schtrue%
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
%%%% EQ?
|
|
\begin{entry}{%
|
|
\proto{eq?}{ \vari{obj} \varii{obj}}{procedure}}
|
|
\saut
|
|
{\stk} extends the \ide{eq?} predicate defined in {\rrrr} to take
|
|
keywords into account. On keywords, \ide{eq?} behaves like \ide{eqv?}.
|
|
|
|
\begin{scheme}
|
|
(eq? :key :key) \ev \schtrue
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
%%%% EQUAL?
|
|
\begin{entry}{%
|
|
\proto{equal?}{ \vari{obj} \varii{obj}}{procedure}}
|
|
\saut
|
|
{\doc}
|
|
\end{entry}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\subsection{Pairs and lists}
|
|
\label{listsection}
|
|
|
|
\begin{entry}{%
|
|
\proto{pair?}{ obj}{procedure}
|
|
\proto{cons}{ \vari{obj} \varii{obj}}{procedure}
|
|
\proto{car}{ pair}{procedure}
|
|
\proto{cdr}{ pair}{procedure}
|
|
\proto{set-car!}{ pair obj}{procedure}
|
|
\proto{set-cdr!}{ pair obj}{procedure}
|
|
\setbox0\hbox{\tt(cadr \var{pair})}
|
|
\setbox1\hbox{procedure}
|
|
\proto{caar}{ pair}{procedure}
|
|
\proto{cadr}{ pair}{procedure}
|
|
\pproto{\hbox to 1\wd0 {\hfil$\vdots$\hfil}}{\hbox to 1\wd1 {\hfil$\vdots$\hfil}}
|
|
\proto{cdddar}{ pair}{procedure}
|
|
\proto{cddddr}{ pair}{procedure}
|
|
\proto{null?}{ obj}{procedure}
|
|
\proto{list?}{ obj}{procedure}
|
|
\proto{list}{ \var{obj} \dotsfoo}{procedure}
|
|
\proto{length}{ list}{procedure}
|
|
\proto{append}{ list \dotsfoo}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{append!}{ list \ldots}{procedure}}
|
|
\saut
|
|
|
|
Returns a list consisting of the elements of the first \var{list}
|
|
followed by the elements of the other lists, as with \texttt{append}.
|
|
The differenece with \texttt{append} is that the arguments are {\em
|
|
changed} rather than {\em copied}.
|
|
\begin{scheme}
|
|
(append! '(1 2) '(3 4) '(5 6)) \lev '(1 2 3 4 5 6)
|
|
(let ((l1 '(1 2))
|
|
(l2 '(3 4))
|
|
(l3 '(5 6)))
|
|
(append! l1 l2 l3)
|
|
(list l1 l2 l3)) \lev ((1 2 3 4 5 6) (3 4 5 6) (5 6))
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{reverse}{ list}{procedure}
|
|
\proto{list-tail}{ list \vr{k}}{procedure}
|
|
\proto{list-ref}{ list \vr{k}}{procedure}
|
|
\proto{memq}{ obj list}{procedure}
|
|
\proto{memv}{ obj list}{procedure}
|
|
\proto{member}{ obj list}{procedure}
|
|
\proto{assq}{ obj alist}{procedure}
|
|
\proto{assv}{ obj alist}{procedure}
|
|
\proto{assoc}{ obj alist}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{remq}{ obj list}{procedure}
|
|
\proto{remv}{ obj list}{procedure}
|
|
\proto{remove}{ obj list}{procedure}}
|
|
\saut
|
|
Each function return a copy of \var{list} where all the occurences of \var{obj}
|
|
have been deleted. The predicate used to test the presence of \var{obj} in
|
|
\var{list} is respectively \ide{eq}, \ide{eqv} and \ide{equal}.
|
|
|
|
\begin{note}
|
|
It is not an error if \var{obj} does not appear in \var{list}.
|
|
\end{note}
|
|
\begin{scheme}
|
|
(remq 1 '(1 2 3)) \ev (2 3)
|
|
(remq "foo" '("foo" "bar")) \ev ("foo" "bar")
|
|
(remove "foo" '("foo" "bar"))
|
|
\ev ("bar")
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{last-pair}{ list}{procedure}}
|
|
\saut
|
|
Returns the last pair of \var{list}\footnote{\ide{Last-pair} was a standard
|
|
procedure in {\rthree}.}.
|
|
\begin{scheme}
|
|
(last-pair '(1 2 3)) \lev 3
|
|
(last-pair '(1 2 . 3)) \lev (2 . 3)
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{list*}{ obj}{procedure}}
|
|
\saut
|
|
\ide{list*} is like \ide{list} except that the last argument to \ide{list*} is
|
|
used as the {\em cdr} of the last pair constructed.
|
|
\begin{scheme}
|
|
(list* 1 2 3) \ev (1 2 . 3)
|
|
(list* 1 2 3 '(4 5)) \ev (1 2 3 4 5)
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{copy-tree}{ obj}{procedure}}
|
|
\saut
|
|
\ide{Copy-tree} recursively copies trees of pairs. If \ide{obj} is not
|
|
a pair, it is returned; otherwise the result is a new pair whose {\em
|
|
car} and {\em cdr} are obtained by calling \ide{copy-tree} on the
|
|
{\em car} and {\em cdr} of \ide{obj}, respectively.
|
|
\end{entry}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\subsection{Symbols}
|
|
\label{symbolsection}
|
|
|
|
The {\stk} reader can cope with symbols whose names contain special
|
|
characters or letters in the non standard case. When a symbol is
|
|
read, the parts enclosed in bars (``\verb+|+'') will be entered
|
|
verbatim into the symbol's name. The ``\verb+|+'' characters are not
|
|
part of the symbol; they only serve to delimit the sequence of
|
|
characters that must be entered ``as is''. In order to maintain
|
|
read-write invariance, symbols containing such sequences of special
|
|
characters will be written between a pair of ``\verb+|+''
|
|
|
|
\begin{scheme}
|
|
'|x| \ev x
|
|
(string->symbol "X") \ev |X|
|
|
(symbol->string '|X|) \ev "X"
|
|
'|a b| \ev |a b|
|
|
'a|B|c \ev |aBc|
|
|
(write '|FoO|) \ev writes the string "|FoO|"
|
|
(display '|FoO|) \ev writes the string "FoO"
|
|
\end{scheme}
|
|
|
|
\begin{note}
|
|
This notation has been introduced because {\rrrr} states that case
|
|
must not be significant in symbols whereas the Tk toolkit is case
|
|
significant (or more precisely thinks it runs over Tcl which is case
|
|
significant). %% axe:
|
|
However, symbols containing the character ``\verb+|+'' itself still
|
|
can't be read in.
|
|
\end{note}
|
|
|
|
\begin{entry}{%
|
|
\proto{symbol?}{ obj}{procedure}}
|
|
\saut
|
|
Returns \schtrue{} if \var{obj} is a symbol, otherwise returns {\schfalse}.
|
|
|
|
\begin{scheme}
|
|
(symbol? 'foo) \ev \schtrue
|
|
(symbol? (car '(a b))) \ev \schtrue
|
|
(symbol? "bar") \ev \schfalse
|
|
(symbol? 'nil) \ev \schtrue
|
|
(symbol? '()) \ev \schfalse
|
|
(symbol? \schfalse) \ev \schfalse
|
|
(symbol? :key) \ev \schfalse
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{symbol->string}{ symbol}{procedure}
|
|
\proto{string->symbol}{ string}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{gensym}{}{procedure}
|
|
\proto{gensym}{ prefix}{procedure}}
|
|
\saut
|
|
\ide{Gensym} creates a new symbol. The print name of the generated symbol
|
|
consists of a prefix (which defaults to {\tt "G"}) followed by the decimal
|
|
representation of a number. If \var{prefix} is specified, it must be a
|
|
string.
|
|
\begin{scheme}
|
|
(gensym) \lev |G100|
|
|
(gensym "foo-") \lev foo-101
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\subsection {Numbers}
|
|
|
|
The only numbers recognized by {\stk} are integers (with arbitrary
|
|
precision) and reals (implemented as C {\tt double float}s).
|
|
|
|
\begin{entry}{%
|
|
\proto{number?}{ obj}{procedure}}
|
|
\saut
|
|
Returns {\schtrue} if \var{obj} is a number, otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{complex?}{ obj}{procedure}}
|
|
\saut
|
|
Returns the same result as \var{number?}. Note that complex numbers
|
|
are not implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{real?}{ obj}{procedure}}
|
|
\saut
|
|
Returns {\schtrue} if \var{obj} is a float number, otherwise returns
|
|
{\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{rational?}{ obj}{procedure}}
|
|
\saut
|
|
Returns the same result as \var{number?}. Note that rational numbers are not
|
|
implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{integer?}{ obj}{procedure}}
|
|
\saut
|
|
Returns {\schtrue} if \var{obj} is an integer, otherwise returns {\schfalse}.
|
|
\begin{note}
|
|
The {\stk} interpreter distinguishes between integers which fit in a
|
|
C {\tt long int} (minus 8 bits) and integers of arbitrary length
|
|
(aka ``bignums''). This should be transparent to the user, though.
|
|
%% shouldn't it? :-) axe
|
|
\end{note}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{exact?}{ \vr{z}}{procedure}
|
|
\proto{inexact?}{ \vr{z}}{procedure}}
|
|
\saut
|
|
In this implementation, integers (C {\tt long int} or ``bignums'') are exact
|
|
numbers and floats are inexact.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{=}{ \vri{z} \vrii{z} \vriii{z} \dotsfoo}{procedure}
|
|
\proto{<}{ \vri{x} \vrii{x} \vriii{x} \dotsfoo}{procedure}
|
|
\proto{>}{ \vri{x} \vrii{x} \vriii{x} \dotsfoo}{procedure}
|
|
\proto{<=}{ \vri{x} \vrii{x} \vriii{x} \dotsfoo}{procedure}
|
|
\proto{>=}{ \vri{x} \vrii{x} \vriii{x} \dotsfoo}{procedure}
|
|
\proto{zero?} { z}{procedure}
|
|
\proto{positive?} { z}{procedure}
|
|
\proto{negative?} { z}{procedure}
|
|
\proto{odd?} { z}{procedure}
|
|
\proto{even?} { z}{procedure}
|
|
\proto{max}{ \vri{x} \vrii{x} \dotsfoo}{procedure}
|
|
\proto{min}{ \vri{x} \vrii{x} \dotsfoo}{procedure}
|
|
\proto{+}{ \vri{z} \dotsfoo}{procedure}
|
|
\proto{*}{ \vri{z} \dotsfoo}{procedure}
|
|
\proto{-}{ \vri{z} \vrii{z}}{procedure}
|
|
\proto{-}{ \vr{z}}{procedure}
|
|
\proto{-}{ \vri{z} \vrii{z} \dotsfoo}{procedure}
|
|
\proto{/}{ \vri{z} \vrii{z}}{procedure}
|
|
\proto{/}{ \vr{z}}{procedure}
|
|
\proto{/}{ \vri{z} \vrii{z} \dotsfoo}{procedure}
|
|
\proto{abs}{ x}{procedure}
|
|
\proto{quotient}{ \vri{n} \vrii{n}}{procedure}
|
|
\proto{remainder}{ \vri{n} \vrii{n}}{procedure}
|
|
\proto{modulo}{ \vri{n} \vrii{n}}{procedure}
|
|
\proto{gcd}{ \vri{n} \dotsfoo}{procedure}
|
|
\proto{lcm}{ \vri{n} \dotsfoo}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{numerator}{ \vr{q}}{procedure}
|
|
\proto{denominator}{ \vr{q}}{procedure}}
|
|
\saut
|
|
Not implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{floor}{ x}{procedure}
|
|
\proto{ceiling}{ x}{procedure}
|
|
\proto{truncate}{ x}{procedure}
|
|
\proto{round}{ x}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{rationalize}{ x y}{procedure}}
|
|
\saut
|
|
not yet implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{exp}{ \vr{z}}{procedure}
|
|
\proto{log}{ \vr{z}}{procedure}
|
|
\proto{sin}{ \vr{z}}{procedure}
|
|
\proto{cos}{ \vr{z}}{procedure}
|
|
\proto{tan}{ \vr{z}}{procedure}
|
|
\proto{asin}{ \vr{z}}{procedure}
|
|
\proto{acos}{ \vr{z}}{procedure}
|
|
\proto{atan}{ \vr{z}}{procedure}
|
|
\proto{atan}{ \vr{y} \vr{x}}{procedure}
|
|
\proto{sqrt}{ \vr{z}}{procedure}
|
|
\proto{expt}{ \vri{z} \vrii{z}}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{
|
|
\proto{make-rectangular}{ \vri{x} \vrii{x}}{procedure}
|
|
\proto{make-polar}{ \vri{x} \vrii{x}}{procedure}
|
|
\proto{real-part}{ \vr{z}}{procedure}
|
|
\proto{imag-part}{ \vr{z}}{procedure}
|
|
\proto{magnitude}{ \vr{z}}{procedure}
|
|
\proto{angle}{ \vr{z}}{procedure}}
|
|
\saut
|
|
These procedures are not implemented since complex numbers are not defined.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{exact->inexact}{ \vr{z}}{procedure}
|
|
\proto{inexact->exact}{ \vr{z}}{procedure}
|
|
\proto{number->string}{ number}{procedure}
|
|
\proto{number->string}{ number radix}{procedure}
|
|
\proto{string->number}{ string}{procedure}
|
|
\proto{string->number}{ string radix}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\subsection{Characters}
|
|
|
|
\mainindex{characters}
|
|
Table 1 gives the list of allowed character names together with their ASCII
|
|
equivalent expressed in octal.
|
|
|
|
\begin{table}[t]
|
|
{\small
|
|
\begin{center}
|
|
% \begin{tabular}{|c|c|c|} \hline
|
|
% {\em name}&{\em value}&{\em alternate name} \\
|
|
% \hline
|
|
% nul &000 & null\\
|
|
% soh &001&\\
|
|
% stx &002&\\
|
|
% etx &003&\\
|
|
% eot &004&\\
|
|
% enq &005&\\
|
|
% ack &006&\\
|
|
% bel &007 & bell\\[2mm]
|
|
% bs &010 & backspace\\
|
|
% ht &011&\\
|
|
% tab &011&\\
|
|
% nl &012 & newline\\
|
|
% vt &013&\\
|
|
% np &014 & page\\
|
|
% cr &015 & return\\
|
|
% so &016&\\
|
|
% si &017&\\[2mm]
|
|
% dle &020&\\
|
|
% dc1 &021&\\
|
|
% dc2 &022&\\
|
|
% dc3 &023&\\
|
|
% dc4 &024&\\
|
|
% nak &025&\\
|
|
% syn &026&\\
|
|
% etb &027&\\[2mm]
|
|
% can &030&\\
|
|
% em &031&\\
|
|
% sub &032&\\
|
|
% esc &033 & escape\\
|
|
% fs &034&\\
|
|
% gs &035&\\
|
|
% rs &036&\\
|
|
% us &037&\\[2mm]
|
|
% sp &040 & space\\[2mm]
|
|
% del &177 & delete\\
|
|
\begin{tabular}{|c|c|c||c|c|c|} \hline
|
|
{\em name}&{\em value}&{\em alternate name}&{\em name}&{\em value}&{\em alternate name} \\
|
|
\hline
|
|
nul &000 & null & bs &010 & backspace\\
|
|
soh &001& & ht &011 & tab\\
|
|
stx &002& & nl &012 & newline\\
|
|
etx &003& & vt &013&\\
|
|
eot &004& & np &014 & page\\
|
|
enq &005& & cr &015 & return\\
|
|
ack &006& & so &016&\\
|
|
bel &007 & bell & si &017&\\[2mm]
|
|
%%%%%
|
|
dle &020& & can &030&\\
|
|
dc1 &021& & em &031&\\
|
|
dc2 &022& & sub &032&\\
|
|
dc3 &023& & esc &033 & escape\\
|
|
dc4 &024& & fs &034&\\
|
|
nak &025& & gs &035&\\
|
|
syn &026& & rs &036&\\
|
|
etb &027& & us &037&\\[2mm]
|
|
%%%%%
|
|
sp &040 & space&&&\\[2mm]
|
|
%%%%%
|
|
del &177 & delete&&&\\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
}
|
|
\caption {Valid character names }
|
|
\end{table}
|
|
|
|
\begin{entry}{%
|
|
\proto{char?}{ obj}{procedure}
|
|
\proto{char=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char<?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char>?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char<=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char>=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-ci=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-ci<?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-ci>?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-ci<=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-ci>=?}{ \vari{char} \varii{char}}{procedure}
|
|
\proto{char-alphabetic?}{ char}{procedure}
|
|
\proto{char-numeric?}{ char}{procedure}
|
|
\proto{char-whitespace?}{ char}{procedure}
|
|
\proto{char-upper-case?}{ letter}{procedure}
|
|
\proto{char-lower-case?}{ letter}{procedure}
|
|
\proto{char->integer}{ char}{procedure}
|
|
\proto{integer->char}{ \vr{n}}{procedure}
|
|
\proto{char-upcase}{ char}{procedure}
|
|
\proto{char-downcase}{ char}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\subsection{Strings}
|
|
|
|
{\stk} string constants allow the insertion of arbitrary characters by
|
|
encoding them as escape sequences, introduced by a backslash
|
|
(\backwhack{}). The valid escape sequences are shown in Table 2. For
|
|
instance, the string
|
|
|
|
\begin{scheme}
|
|
"ab\backwhack{}040c\backwhack{}nd\backwhack{}
|
|
e"
|
|
\end{scheme}
|
|
is the string consisting of the characters \sharpsign\backwhack{a},
|
|
\sharpsign\backwhack{b},\sharpsign\backwhack{space}, \sharpsign\backwhack{c},
|
|
\sharpsign\backwhack{newline}, \sharpsign\backwhack{d} and \sharpsign\backwhack{e}.
|
|
|
|
\begin{table}[t]
|
|
{\small
|
|
\begin{center}
|
|
\begin{tabular}{|l|l|} \hline
|
|
\multicolumn{1}{|c|}{\em Sequence}&\multicolumn{1}{|c|}{\em Character inserted}\\
|
|
\hline
|
|
\backwhack{b}& Backspace \\
|
|
\backwhack{e}& Escape \\
|
|
\backwhack{n}& Newline \\
|
|
\backwhack{t}& Horizontal Tab \\
|
|
\backwhack{n}& Carriage Return \\
|
|
\backwhack{0abc}& ASCII character with octal value abc \\
|
|
\backwhack{\tt<newline>}& None (permits to enter a string on several lines)\\
|
|
\backwhack{\tt<other>}& {\tt<other>}\\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
}
|
|
\caption {String escape sequences}
|
|
\end{table}
|
|
|
|
\begin{entry}{%
|
|
\proto{string?}{ obj}{procedure}
|
|
\proto{make-string}{ \vr{k}}{procedure}
|
|
\proto{make-string}{ \vr{k} char}{procedure}
|
|
\proto{string}{ char \dotsfoo}{procedure}
|
|
\proto{string-length}{ string}{procedure}
|
|
\proto{string-ref}{ string \vr{k}}{procedure}
|
|
\proto{string-set!}{ string k char}{procedure}
|
|
\proto{string=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string-ci=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string<?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string>?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string<=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string>=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string-ci<?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string-ci>?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string-ci<=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{string-ci>=?}{ \vari{string} \varii{string}}{procedure}
|
|
\proto{substring}{ string start end}{procedure}
|
|
\proto{string-append}{ \var{string} \dotsfoo}{procedure}
|
|
\proto{string->list}{ string}{procedure}
|
|
\proto{list->string}{ chars}{procedure}
|
|
\proto{string-copy}{ string}{procedure}
|
|
\proto{string-fill!}{ string char}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{string-find?}{ \vari{string} \varii{string}}{procedure}}
|
|
\saut
|
|
Returns {\schtrue} if \vari{string} appears somewhere in
|
|
\varii{string}; otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{string-index}{ \vari{string} \varii{string}}{procedure}}
|
|
\saut
|
|
Returns the index of where \vari{string} is a substring of
|
|
\varii{string} if it exists; returns {\schfalse} otherwise.
|
|
\begin{scheme}
|
|
(string-index "ca" "abracadabra") \lev 4
|
|
(string-index "ba" "abracadabra") \lev \schfalse
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{split-string}{ string}{procedure}
|
|
\proto{split-string}{ string delimiters}{procedure}}
|
|
\saut
|
|
This function parses \vari{string} and returns a list of tokens ended by
|
|
a character of the \vari{delimiters} string. If \vari{delimiters} is omitted,
|
|
it defaults to a string containing a space, a tabulation and a newline
|
|
characters.
|
|
\begin{scheme}
|
|
(split-string "/usr/local/bin" "/") \ev ("usr" "local" "bin")
|
|
(split-string "once upon a time") \ev ("once" "upon" "a" "time")
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{string-lower}{ string}{procedure}}
|
|
\saut
|
|
Returns a string in which all upper case letters of \ide{string} have been
|
|
replaced by their lower case equivalent.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{string-upper}{ string}{procedure}}
|
|
\saut
|
|
Returns a string in which all lower case letters of \ide{string} have been
|
|
replaced by their upper case equivalent.
|
|
\end{entry}
|
|
|
|
|
|
\subsection {Vectors}
|
|
|
|
\begin{entry}{%
|
|
\proto{vector?}{ obj}{procedure}
|
|
\proto{make-vector}{ k}{procedure}
|
|
\proto{make-vector}{ k fill}{procedure}
|
|
\proto{vector}{ obj \dotsfoo}{procedure}
|
|
\proto{vector-length}{ vector}{procedure}
|
|
\proto{vector-ref}{ vector k}{procedure}
|
|
\proto{vector-set!}{ vector k obj}{procedure}
|
|
\proto{vector->list}{ vector}{procedure}
|
|
\proto{list->vector}{ list}{procedure}
|
|
\proto{vector-fill!}{ vector fill}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{vector-copy}{ vector}{procedure}}
|
|
\saut
|
|
returns a copy of \var{vector}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{vector-resize}{ vector size}{procedure}}
|
|
\saut
|
|
\var{vector-resize} physically changes the size of \var{vector}. If
|
|
\var{size} is greater than the old vector size, the contents of the
|
|
newly allocated cells are undefined.
|
|
\end{entry}
|
|
|
|
\subsection{Control features}
|
|
|
|
\begin{entry}{%
|
|
\proto{procedure?}{ obj}{procedure}
|
|
\proto{apply}{ proc args}{procedure}
|
|
\proto{apply}{ proc \vari{arg} $\ldots$ args}{procedure}
|
|
\proto{map}{ proc \vari{list} \varii{list} \dotsfoo}{procedure}
|
|
\proto{for-each}{ proc \vari{list} \varii{list} \dotsfoo}{procedure}
|
|
\proto{force}{ promise}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{call-with-current-continuation}{ proc}{procedure}
|
|
\proto{call/cc} { proc}{procedure}}
|
|
\saut
|
|
\ide{Call/cc} is a shorter name for \ide{call-with-current-continuation}.
|
|
\mainindex{continuation}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{closure?}{ obj}{procedure}}
|
|
\saut
|
|
returns {\schtrue} if \var{obj} is a procedure created by evaluating a
|
|
lambda expression, otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{primitive?}{ obj}{procedure}}
|
|
\saut
|
|
returns {\schtrue} if \var{obj} is a procedure and is not a closure,
|
|
otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{promise?} { obj}{procedure}}
|
|
\saut
|
|
returns {\schtrue} if \var{obj} is an object returned by the
|
|
application of \ide{delay}, otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{continuation?} { obj} {procedure}}
|
|
\saut
|
|
\mainindex{continuation}
|
|
returns {\schtrue} if \var{obj} is a continuation obtained by
|
|
\ide{call/cc}, otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{dynamic-wind}{ \hyperi{thunk} \hyperii{thunk} \hyperiii{thunk}} {procedure}}
|
|
\saut
|
|
\hyperi{Thunk}, \hyperii{thunk} and \hyperiii{thunk} are called in
|
|
order. The result of \ide{dynamic-wind} is the value returned by
|
|
\hyperii{thunk}. If \hyperii{thunk} escapes from its continuation
|
|
during evaluation (by calling a continuation obtained by \ide{call/cc}
|
|
or on error), \hyperiii{thunk} is called. If \hyperii{thunk} is later
|
|
reentered, \hyperi{thunk} is called.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{catch} { \hyperi{expression} \hyperii{expression} \dotsfoo} {\exprtype}}
|
|
\saut
|
|
The \hyper{expression}s are evaluated from left to right. If an error
|
|
occurs, evaluation of the \hyper{expression}s is aborted, and {\schtrue}
|
|
is returned to \ide{catch}'s caller. If evaluation finishes without
|
|
an error, \ide{catch} returns {\schfalse}.
|
|
%% axe: why isn't this a procedure taking a thunk?
|
|
\begin {scheme}
|
|
(let* ((x 0)
|
|
(y (catch
|
|
(set! x 1)
|
|
(/ 0) ; causes a "division by 0" error
|
|
(set! x 2))))
|
|
(cons x y)) \lev (1 . {\schtrue})
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
|
|
\begin{entry}{%
|
|
\proto{procedure-body}{ \hyper{procedure}} {procedure}}
|
|
\saut
|
|
returns the body of \hyper{procedure}. If \hyper{procedure} is not a closure,
|
|
\ide{procedure-body} returns {\schfalse}.
|
|
\begin{scheme}
|
|
(define (f a b)
|
|
(+ a (* b 2)))
|
|
|
|
(procedure-body f) \ev (lambda (a b)
|
|
(+ a (* b 2)))
|
|
(procedure-body car) \ev \schfalse
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\subsection{Input and output}
|
|
|
|
\label{inputoutput}
|
|
The {\rrrr} states that ports represent input and output devices.
|
|
However, it defines only ports which are attached to files. In
|
|
{\stk}, ports can also be attached to strings or to a external command
|
|
input or output. String ports are similar to file ports, except that
|
|
characters are read from (or written to) a string rather than a file.
|
|
External command input or output ports are implemented with Unix pipes
|
|
and are called pipe ports. A pipe port is created by specifying the
|
|
command to execute prefixed with the string {\tt "|~"}. Specification
|
|
of a pipe port can occur everywhere a file name is needed.
|
|
|
|
|
|
\begin{entry}{%
|
|
\proto{call-with-input-file}{ string proc}{procedure}
|
|
\proto{call-with-output-file}{ string proc}{procedure}}
|
|
\saut
|
|
\begin{note}
|
|
if {\var string} starts with the two characters {\tt "| "}, these procedures
|
|
return a pipe port. Consequently, it is not possible to open a file
|
|
whose name starts with those two characters.
|
|
\end{note}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{call-with-input-string}{ string proc}{procedure}}
|
|
\saut
|
|
behaves exactly as \ide{call-with-input-file} except that the port passed to
|
|
\var{proc} is the string port obtained from \var{string}.
|
|
|
|
\begin{scheme}
|
|
(call-with-input-string "123 456" (lambda (x) (read x))) \lev 123
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{call-with-output-string}{ proc}{procedure}}
|
|
\saut
|
|
\var{Proc} should be a procedure of one argument.
|
|
\ide{Call-with-output-string} calls \var{proc} with a freshly opened
|
|
output string port. The result of this procedure is a string
|
|
containing all the text that has been written on the string port.
|
|
\begin{scheme}
|
|
(call-with-output-string
|
|
(lambda (x) (write 123 x) (display "Hello" x))) \lev "123Hello"
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{input-port?}{ obj}{procedure}
|
|
\proto{output-port?}{ obj}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{input-string-port?}{ obj}{procedure}
|
|
\proto{output-string-port?}{ obj}{procedure}}
|
|
\saut
|
|
Returns \schtrue{} if \var{obj} is either an input or an output string port,
|
|
otherwise returns {\schfalse}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{current-input-port}{}{procedure}
|
|
\proto{current-output-port}{}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{current-error-port}{}{procedure}}
|
|
\saut
|
|
Returns the current default error port.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{with-input-from-file}{ string thunk}{procedure}
|
|
\proto{with-output-to-file}{ string thunk}{procedure}}
|
|
\saut
|
|
\doc
|
|
|
|
The following example uses a pipe port opened for reading. It permits
|
|
to read all the lines produced by an external {\tt ls} command
|
|
(i.e. the ouput of the {\tt ls} command is {\em redirected} to the
|
|
Scheme pipe port).
|
|
|
|
\begin{scheme}
|
|
(with-input-from-file "\verb+|+ ls -ls"
|
|
(lambda ()
|
|
(do ((l (read-line) (read-line)))
|
|
((eof-object? l))
|
|
(display l)
|
|
(newline))))
|
|
\end{scheme}
|
|
|
|
Hereafter is another example of Unix command redirection. This time,
|
|
it is the standard input of the Unix command which is redirected.
|
|
\begin{scheme}
|
|
(with-output-to-file "| mail root"
|
|
(lambda()
|
|
(format {\schtrue} "A simple mail sent from STk\verb+\+n")))
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{with-input-from-string}{ string thunk}{procedure}}
|
|
\saut
|
|
A string port is opened for input from \var{string}. \ide{Current-input-port}
|
|
is set to the port and \var{thunk} is called. When \var{thunk} returns,
|
|
the previous default input port is restored.
|
|
\ide{With-input-from-string} returns the value yielded by \var{thunk}.
|
|
|
|
\begin{scheme}
|
|
(with-input-from-string "123 456" (lambda () (read))) \lev 123
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{with-output-to-string}{ thunk}{procedure}}
|
|
\saut
|
|
A string port is opened for output. \ide{Current-output-port}
|
|
is set to it and \var{thunk} is called. When the \var{thunk} returns,
|
|
the previous default output port is restored. \ide{With-output-to-string}
|
|
returns the string containing all the text written on the string port.
|
|
|
|
\begin{scheme}
|
|
(with-output-to-string (lambda () (write 123) (write "Hello"))) \lev "123Hello"
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{open-input-file}{ filename}{procedure}
|
|
\proto{open-output-file}{ filename}{procedure}}
|
|
\saut
|
|
\doc
|
|
|
|
\begin{note}
|
|
if {\var filename} starts with the string {\tt "| "}, these procedure
|
|
return a pipe port. Consequently, it is not possible to open a file
|
|
whose name starts with those two characters.
|
|
\end{note}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{open-input-string}{ string}{procedure}}
|
|
\saut
|
|
Returns an input string port capable of delivering characters from
|
|
\var{string}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{open-output-string}{}{procedure}}
|
|
\saut
|
|
Returns an output string port capable of receiving and collecting characters.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{get-output-string}{ port}{procedure}}
|
|
\saut
|
|
Returns a string containing all the text that has been written on the
|
|
output string \var{port}.
|
|
\begin{scheme}
|
|
(let ((p (open-output-string)))
|
|
(display "Hello, world" p)
|
|
(get-output-string p)) \lev "Hello, world"
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
|
|
\begin{entry}{%
|
|
\proto{close-input-port}{ port}{procedure}
|
|
\proto{close-output-port}{ port}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{read}{}{procedure}
|
|
\proto{read}{ port}{procedure}
|
|
\proto{read-char}{}{procedure}
|
|
\proto{read-char}{ port}{procedure}
|
|
\proto{peek-char}{}{procedure}
|
|
\proto{peek-char}{ port}{procedure}
|
|
\proto{char-ready?}{}{procedure}
|
|
\proto{char-ready?}{ port}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
%% axe: the question of `new line or not new line?' was left open
|
|
\begin{entry}{%
|
|
\proto{read-line}{}{procedure}
|
|
\proto{read-line}{ port}{procedure}}
|
|
\saut
|
|
Reads the next line available from the input port \var{port} and
|
|
returns it as a string. The terminating newline is not included in the
|
|
string. If no more characters are available, an end of file object is
|
|
returned. \var{Port} may be omitted, in which case it defaults to the
|
|
value returned by \ide{current-input-port}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{write}{ obj}{procedure}
|
|
\proto{write}{ obj port}{procedure}
|
|
\proto{display}{ obj}{procedure}
|
|
\proto{display}{ obj port}{procedure}
|
|
\proto{newline}{}{procedure}
|
|
\proto{newline}{ port}{procedure}
|
|
\proto{write-char}{ char}{procedure}
|
|
\proto{write-char}{ char port}{procedure}}
|
|
\saut
|
|
\doc
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{format}{ port string \vri{obj} \vrii{obj} \dotsfoo}{procedure}}
|
|
\saut
|
|
\label{format}
|
|
Writes the \var{obj}s to the given \var{port}, according to the format
|
|
string \var{string}. \var{String} is written literally, except for
|
|
the following sequences:
|
|
%
|
|
\begin{itemize}
|
|
\item \tilda{}a or \tilda{}A is replaced by the printed representation of the
|
|
next \var{obj}.
|
|
\item \tilda{}s or \tilda{}S is replaced by the ``slashified'' printed
|
|
representation of the next \var{obj}.
|
|
\item \tilda{}\tilda{} is replaced by a single tilde.
|
|
\item \tilda{}\% is replaced by a newline
|
|
\end{itemize}
|
|
|
|
\var{Port} can be a boolean, a port or a string port. If \var{port}
|
|
is {\schtrue}, output goes to the current output port; if \var{port}
|
|
is {\schfalse}, the output is returned as a string. Otherwise, the output is
|
|
printed on the specified port.
|
|
%
|
|
\begin{scheme}
|
|
(format {\schfalse} "A test.") \lev "A test."
|
|
(format {\schfalse} "A \tilda{}a." "test") \lev "A test."
|
|
(format {\schfalse} "A \tilda{}s." "test") \lev "A \backwhack{}"test\backwhack{}"."
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{get-output-string}{ port}{procedure}}
|
|
\saut
|
|
Returns the string associated with the output string \var{port}.
|
|
\begin{scheme}
|
|
(let ((p (open-output-string)))
|
|
(display "Hello, world" p)
|
|
(get-output-string p)) \lev "Hello, world"
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{flush}{}{procedure}
|
|
\proto{flush}{ port}{procedure}}
|
|
\saut
|
|
Flushes the buffer associated with the given \var{port}. The
|
|
\var{port} argument may be omitted, in which case it defaults to the value
|
|
returned by \ide{current-output-port}.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{when-port-readable}{ port handler}{procedure}
|
|
\proto{when-port-readable}{ port}{procedure}}
|
|
\saut
|
|
When \var{port} is ready for reading, \var{handler}, which must be a
|
|
thunk, is called leaving the current evaluation suspended. When
|
|
\var{handler} execution is terminated, normal evaluation is resumed at
|
|
its suspension point. If the special value \schfalse{} is provided as
|
|
\var{handler}, the current handler for \var{port} is deleted. If a
|
|
handler is provided, the value returned by \ide{when-port-readable} is
|
|
undefined. Otherwise, it returns the handler currently associated to
|
|
\var{port}.
|
|
|
|
The example below shows a simple usage of the \ide{when-port-readable} procedure:
|
|
the command \var{cmd} is run with its output redirected in a pipe associated to the
|
|
\var{p} Scheme port.
|
|
\begin{scheme}
|
|
(define p (open-input-file "| cmd"))
|
|
(when-port-readable p
|
|
(lambda()
|
|
(let (( l (read-line p)))
|
|
(if (eof-object? l)
|
|
(begin
|
|
;; delete handler
|
|
(when-port-readable p \schfalse)
|
|
;; and close port
|
|
(close-input-port p))
|
|
(format \schtrue{} "Line read: \tilda{}A\verb+\+n" l)))))
|
|
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{when-port-writable}{ port handler}{procedure}
|
|
\proto{when-port-writable}{ port}{procedure}}
|
|
\saut
|
|
When \var{port} is ready for writing, \var{handler}, which must be a
|
|
thunk, is called leaving the current evaluation suspended. When
|
|
\var{handler} execution is terminated, normal evaluation is resumed at
|
|
its suspension point. If the special value \schfalse{} is provided as
|
|
\var{handler}, the current handler for \var{port} is deleted. If a
|
|
handler is provided, the value returned by \ide{when-port-writable} is
|
|
undefined. Otherwise, it returns the handler currently associated to
|
|
\var{port}.
|
|
\end{entry}
|
|
|
|
|
|
\begin{entry}{%
|
|
\proto{load}{ filename}{procedure}
|
|
\proto{load}{ filename module}{procedure}}
|
|
\saut
|
|
|
|
The first form is identical to \rrrr{}. The second one loads the
|
|
content of \var{filename} in the given \var{module} environment.
|
|
\begin{note}
|
|
The \var{load} primitive has been extended to allow loading of
|
|
object files, though this is not implemented on all systems.
|
|
This extension uses dynamic loading on systems which support it
|
|
\footnote{Current version (\stkversion) allows dynamic loading
|
|
only on some platforms: SunOs~4.1.x, SunOs~5.x, NetBSD~1.0,
|
|
Linux~2.0, HPUX, Irix 5.3}. See~\cite{STkExtension} for more details.
|
|
\end{note}
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{try-load}{ filename}{procedure}
|
|
\proto{try-load}{ filename module}{procedure}}
|
|
\saut
|
|
Tries to load the file named \var{filename}. If \var{filename} exists and is
|
|
readable, it is loaded, and \ide{try-load} returns {\schtrue}.
|
|
Otherwise, the result of the call is {\schfalse}.
|
|
The second form of \var{try-load} tries to load the content of \var{filename}
|
|
in the given \var{module} environment.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{autoload}{ filename \hyperi{symbol} \hyperii{symbol} \dotsfoo}{\exprtype}}
|
|
\saut
|
|
Defines \hyper{symbol}s as autoload symbols associated to file
|
|
\var{filename}.
|
|
First evaluation of an autoload symbol will cause the loading of its
|
|
associated file in the module environment in which the autoload was done.
|
|
\var{Filename} must provide a definition for the symbol which
|
|
lead to its loading, otherwise an error is signaled.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{autoload?}{ symbol module}{procedure}}
|
|
\saut
|
|
Returns {\schtrue} if \var{symbol} is an autoload symbol in \var{module}
|
|
environment ; returns {\schfalse} otherwise.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{require}{ string}{procedure}
|
|
\proto{provide}{ string}{procedure}
|
|
\proto{provided?}{ string}{procedure}}
|
|
\saut
|
|
\ide{Require} loads the file whose name is \var{string} if it was not
|
|
previously ``provided''.\ide{Provide} permits to store \var{string} in
|
|
the list of already provided files. Providing a file permits to avoid
|
|
subsequent loads of this file. \ide{Provided?} returns {\schtrue} if
|
|
\var{string} was already provided; it returns {\schfalse} otherwise.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{transcript-on}{ filename}{procedure}\nopagebreak{}
|
|
\proto{transcript-off}{}{procedure}}
|
|
\saut
|
|
Not implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{open-file}{ filename mode}{procedure}}
|
|
\saut
|
|
Opens the file whose name is \var{filename} with the specified
|
|
\var{mode}. \var{Mode} must be ``r'' to open for reading or ``w''
|
|
to open for writing. If the file can be opened, \var{open-file}
|
|
returns the port associated with the given file, otherwise it returns
|
|
{\schfalse}. Here again, the ``magic'' string {\tt "|~``} permit to
|
|
open a pipe port.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{close-port}{ port}{procedure}}
|
|
\saut
|
|
Closes \var{port}. If \var{port} denotes a string port, further
|
|
reading or writing on this port is disallowed.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{transcript-on}{ filename}{procedure}\nopagebreak{}
|
|
\proto{transcript-off}{}{procedure}}
|
|
\saut
|
|
Not implemented.
|
|
\end{entry}
|
|
|
|
\begin{entry}{%
|
|
\proto{port->string}{ port}{procedure}
|
|
\proto{port->list}{ reader port}{procedure}
|
|
\proto{port->string-list}{ port}{procedure}
|
|
\proto{port->sexp-list}{ port}{procedure}}
|
|
\saut
|
|
Those procedures are utility for generally parsing input streams. Their
|
|
specification has been stolen from {\tt scsh}.
|
|
|
|
\ide{Port->string} reads the input port until eof, then returns the
|
|
accumulated string.
|
|
\begin{scheme}
|
|
(port->string (open-input-file "\verb+|+ (echo AAA; echo BBB)"))
|
|
\ev "AAA\verb+\+nBBB\verb+\+n"
|
|
(define exec
|
|
(lambda (command)
|
|
(call-with-input-file
|
|
(string-append "\verb+|+ " command) port->string)))
|
|
|
|
(exec "ls -l") \ev a string which contains the result of "ls -l"
|
|
\end{scheme}
|
|
|
|
\ide{Port->list} uses the \var{reader} function to repeatedly read
|
|
objects from \var{port}. Thes objects are accumulated in a list which
|
|
is returned upon eof.
|
|
\begin{scheme}
|
|
(port->list read-line (open-input-file "\verb+|+ (echo AAA; echo BBB)"))
|
|
\ev ("AAA" "BBB")
|
|
\end{scheme}
|
|
|
|
\ide{Port->string-list} reads the input port line by line until eof,
|
|
then returns the accumulated list of lines. This procedure is defined as
|
|
\begin{scheme}
|
|
(define port->string-list (lambda (p)(port->list read-line p)))
|
|
\end{scheme}
|
|
|
|
\ide{Port->sexp-list} repeatedly reads data from the port until eof,
|
|
then returns the accumulated list of items. This procedure is defined as
|
|
\begin{scheme}
|
|
(define port->sexp-list (lambda (p) (port->list read p)))
|
|
\end{scheme}
|
|
For instance, the following expression gives the list of users currently
|
|
connected on the machine running the {\stk} interpreter.
|
|
\begin{scheme}
|
|
(port->sexp-list (open-input-file "| users"))
|
|
\end{scheme}
|
|
\end{entry}
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "manual"
|
|
%%% End:
|