% This file is part of Oaklisp.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% The GNU GPL is available at http://www.gnu.org/licenses/gpl.html
% or from the Free Software Foundation, 59 Temple Place - Suite 330,
% Boston, MA 02111-1307, USA


\chapter{Miscellaneous} \label{misc}

\section{Tables}

The types are \df{generic-hash-table} and \df{eq-hash-table}.  The
access interface is \df{present?}, which returns a \df{pair} whose
\df{car} is the key and whose \df{cdr} is the associated value.  A
different interface to hash tables is provided by the T-style
\df{table-entry} operation which returns the associated value or
\df{\#f} if the key isn't in the table.  The setter of either
operation can be used to add, modify, and remove associations.

\makin{generic-hash-table}{key-hash-op equal-op}
\makin{eq-hash-table}{}

\so{present?}{table key}
\doc{Returns \texttt{(\emph{key \dt val})} pair, or \df{\#f} if not present.}

\so{table-entry}{table key}
\doc{Returns value indexed by \emph{key} or \df{\#f} if not present.}




\section{Delays}

Oaklisp's delays are compatible with the facility defined in R3RS, but
extend those primitive facilities in two ways.  First, the system will
automatically force promises when appropriate.  For instance, \texttt{(+
2 (delay 3))} does not signal an error; it returns \texttt{5}.
Similarly, delays are printed transparently, slightly violating
read/print consistency.  Secondly, the delay facility is user
extensible.  Users can create new kinds of delays that have special
protocols, for instance numeric delays that do not force themselves
upon arithmetic operations, but instead make more and more complicated
delays.


\sform{delay}{expression}
\doc{This immediately returns a \emph{promise} for \emph{expression},
without actually computing \emph{expression}.  This promise does not
compute \emph{expression} until it is forced, at which point it
returns the value of \emph{expression}, computing it if it hasn't
already done so.}

\op{force}{x}
\doc{If \emph{x} is a promise, it is forced to compute its value, which
is returned.  If \emph{x} is not a promise, it itself is returned.}

\ty{promise}
\doc{This is the type of the objects returned by \df{delay}.}

\ty{forcible}
\doc{This is an abstract type, of which \df{promise} is a concrete
subtype.  Subtypes of \df{forcible} are expected to respond to the
\df{force} operation in a sensible fashion.  Oaklisp's system
internals sometimes force instances of \df{forcible} automatically,
for instance when sending them messages for which no appropriate
method can otherwise be found.}

\fv{forcible-print-magic}
\doc{Controls how delays are printed.  This is how \texttt{(delay 'foo)}
would print under various settings of \texttt{forcible-print-magic}.
\begin{center}
\begin{tabular}{|l|l|}\hline
value             & print style             \\ \hline
\texttt{\#f}          & \texttt{\#<DELAY 3462>}     \\
\texttt{indicate}    & \texttt{\#[DELAY FOO 3462]} \\
\texttt{transparent} & \texttt{FOO}               \\ \hline
\end{tabular}
\end{center}
The default is \df{transparent}.  A setting of \df{indicate} is more
instructive if you encounter odd behavior that might be due to
delays.}
