% 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{Control} \label{control}

Nonlocal control constructs like \df{call/cc} are described in section
\ref{sec:nonlocal}.

\discuss{Since control structures are not a very interesting issue,
we followed existing Lisp dialects closely when designing this aspect
of Oaklisp. Every control structure in this chapter does just what you
would expect.}

\section{Simple Constructs}

These forms are compatible with both T \citep[chapter 5]{T-MAN} and the
Scheme standard \citep{R3RS}.

\sform{cond}{\dt clauses}
\doc{The \emph{clauses} are run through sequentially until one is
selected.  Each clause can be of four possible forms.  \emph{\lpar test
\dt body\rpar} evaluates \emph{body} if \emph{test} is true.
\emph{\lpar\df{else} \dt body\rpar} always evaluates \emph{body},
and if present must be the last clause.  \emph{\lpar test \texttt{=>}
operation\rpar} calls \emph{operation} on the result of \emph{test} if
the result of evaluating \emph{test} was not \emph{false}.  \emph{\lpar
test\rpar} is equivalent to \emph{\lpar test \texttt{=> identity}\rpar}.}

\sform{if}{test consequent $[$alternate$]$}
\pr{not}{object}
\sform{and}{\dt tests}
\sform{or}{\dt tests}
\sform{iterate}{variable specs \dt body}
\sform{block}{\dt body}
\doc{Evaluates the forms of \emph{body} sequentially, returning (tail
recursively) the value of the last one.}
\sform{block0}{form \dt body}
\doc{\meq{}{(let ((x \emph{form})) (block \dt \emph{body}) x)}}

\sform{dotimes}{\lpar variable number $[$rform$]$\rpar \dt body}
\doc{\meq{}{(let ((x (lambda (\emph{variable}) \dt \emph{body}))) (map x
(iota \emph{number})) \emph{rform})}}
\sform{dolist}{\lpar variable list $[$rform$]$\rpar \dt body}
\doc{\meq{}{(let ((x (lambda (\emph{variable}) \dt \emph{body}))) (map x
\emph{list}) \emph{rform})}}
\sform{dolist-count}{\lpar variable list count-var\rpar \dt body}
\doc{Just like \texttt{dolist} except that \emph{count-var} gives the
count of the current element in the list, starting at zero.}
\sform{while}{condition \dt body}
\doc{\meq{}{(let ((q (lambda () \emph{test}))(x (lambda () \dt
\emph{body}))) (iterate aux () (cond ((\emph{q}) (\emph{x}) (aux)))))}}
\sform{unless}{test \dt body}
\doc{\meq{}{(cond ((not \emph{test}) \dt \emph{body}))}}
\sform{do}{\lpar \lpar var initial step \rpar \ldots \rpar
 \lpar termination-test \dt termination-body \rpar \dt body}
\doc{\meq{}{(iterate aux ((\emph{var initial}) \ldots)
(cond (\emph{termination-test} \dt \emph{termination-body})
      (else (block \dt \emph{body}) (aux \emph{step} \ldots))))}}

\section{Mapping Constructs} \label{sec:controlmap}

Although these can be used as control constructs, they can also be
thought of as ways to manipulate data structures.  \df{map} maps an
operation over some sequences generating a sequence of results.
\df{for-each}, which doesn't save the results, is used when the
operation is called for effect only.  For all of these, the order of
evaluation is undefined; the system may apply the operation to the
various elements of the sequence in any order it desires.

\op{map}{operation \dt sequences}
\op{mapcdr}{operation \dt lists}
\doc{Applies \emph{operation} to successive ``cdrs'' rather than to
elements, and returns a list of the returned values.}
\op{for-each}{operation \dt sequences}
\op{for-each-cdr}{operation \dt lists}
\doc{Like \df{mapcdr} but for effect only.}
\op{map\protect\bang}{operation \dt sequences}
\doc{Like \df{map}, except that the retuned values are destructively
placed into the successive storage locations of the first \emph{sequence}.}
