Convert manual to Texinfo.
Thu Jul 13 07:29:15 PDT 2006 Luis Oliveira <loliveira@common-lisp.net>
* Convert manual to Texinfo.
diff -rN -u old-iterate/doc/GNUmakefile new-iterate/doc/GNUmakefile
--- old-iterate/doc/GNUmakefile 2014-04-17 15:33:25.000000000 -0700
+++ new-iterate/doc/GNUmakefile 1969-12-31 16:00:00.000000000 -0800
@@ -1,27 +0,0 @@
-SOURCES=iterate-bare.tex iterate-manual.tex
-DUMMY_INDEXES=iterate-manual.ind
-MKIDX=makeindex
-MKIDXFLAGS=-l
-LATEX=latex
-
-all: iterate-bare.pdf iterate-manual.pdf iterate-bare.ps iterate-manual.ps
-
-%.dvi: %.tex
- touch $*.ind $*.idx
- ${LATEX} $<
- ${MKIDX} ${MKIDXFLAGS} $*.idx
- ${LATEX} $<
-
-%.ps: %.dvi
- dvips -o $@ $*.dvi
-
-%.pdf: %.dvi
- dvipdf $*.dvi $@
-
-clean:
- rm -f *.dvi *.log *.aux *.ind *.idx *.toc *.auxs *.ilg
-
-shiny: clean
- rm -f *.ps *.pdf
-
-# arch-tag: "c8f080e3-313c-11d8-abb9-000c76244c24"
diff -rN -u old-iterate/doc/Makefile new-iterate/doc/Makefile
--- old-iterate/doc/Makefile 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/Makefile 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,41 @@
+# -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t -*-
+#
+# Makefile --- Make targets for generating the documentation.
+#
+# Copyright (C) 2005-2006, Luis Oliveira <loliveira at common-lisp.net>
+#
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use, copy,
+# modify, merge, publish, distribute, sublicense, and/or sell copies
+# of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+#
+
+all: docs
+
+docs:
+ sh gendocs.sh -o manual --html "--css-include=style.css" iterate "The Iterate Manual"
+
+clean:
+ find . \( -name "*.info" -o -name "*.aux" -o -name "*.cp" -o -name "*.fn" -o -name "*.fns" -o -name "*.ky" -o -name "*.log" -o -name "*.pg" -o -name "*.toc" -o -name "*.tp" -o -name "*.vr" -o -name "*.dvi" -o -name "*.cps" -o -name "*.vrs" \) -exec rm {} \;
+ rm -rf manual
+
+upload-docs:
+ rsync -av --delete -e ssh manual common-lisp.net:/project/iterate/public_html/
+# scp -r manual spec common-lisp.net:/project/cells/public_html/
+
+# vim: ft=make ts=4 noet
diff -rN -u old-iterate/doc/aimemo.sty new-iterate/doc/aimemo.sty
--- old-iterate/doc/aimemo.sty 2014-04-17 15:33:25.000000000 -0700
+++ new-iterate/doc/aimemo.sty 1969-12-31 16:00:00.000000000 -0800
@@ -1,250 +0,0 @@
-% Use the full page
-%
-\oddsidemargin 18pt
-\evensidemargin 18pt
-\topmargin 0pt
-\textheight 595pt
-\textwidth 432pt
-
-% Topheading supplies left and right flushed headings for the
-% lrheading command.
-%
-\def\topheadings#1#2{\def\@toplefthead{#1}\def\@toprighthead{#2}}
-
-% Page style: lrheadings
-% put text suplied by the topheadings command in the left and
-% right corners of the topheading.
-%
-\def\ps@lrheadings{%
-\def\@oddhead{\hbox{}\sl\@toplefthead\hfil\sl\@toprighthead}%
-\def\@evenhead{\sl\@toplefthead\hfil\sl\@toprighthead\hbox{}}%
-\def\@oddfoot{\hbox{}\hfil\rm\thepage\hfil}%
-\def\@evenfoot{\hbox{}\hfil\rm\thepage\hfil}}
-
-% Page style: footpagenumber
-% put nothing in header and center the page number in the footer.
-%
-\def\ps@footpagenumber{%
-\def\@oddhead{}\def\@evenhead{}%
-\def\@oddfoot{\hbox{}\hfil\rm\thepage\hfil}%
-\def\@evenfoot{\hbox{}\hfil\rm\thepage\hfil}}
-
-% \skipline leaves a blank line realitive to the size of the current
-% font.
-%
-\def\skipline{\vskip 2em}
-
-
-%
-% get the title page correct
-%
-
-% set these to do something
-\def\writtenby{Sundar Narasimhan}
-\def\contractno{Fill in appropriate ARPA/ONR contract no.}
-\def\AIMEMO #1#2#3{ %
-\begin{titlepage}
-\begin{center}
-MASSACHUSETTS INSTITUTE OF TECHNOLOGY\\
-ARTIFICIAL INTELLIGENCE LABORATORY
-\end{center}
-\vskip 1in
-\hbox to \hsize{A.I.Memo No. #1 \hfill \shortdate}
-\vskip 1in
-\begin{center}
-{\bf #2}
-\end{center}
-\vskip 0.5in
-\begin{center}
-\writtenby
-\end{center}
-\vskip 1in
-{\bf Abstract: } #3
-\hbox to \hsize{\hrulefill} % draw a line
-\contractno
-\end{titlepage}
-}
-
-%
-% Argument convention - same as before
-%
-\def\AIWORKINGPAPER #1#2#3{ %
-\begin{titlepage}
-\begin{center}
-MASSACHUSETTS INSTITUTE OF TECHNOLOGY\\
-ARTIFICIAL INTELLIGENCE LABORATORY
-\end{center}
-\vskip 1in
-\hbox to \hsize{Working Paper No. #1 \hfill \shortdate}
-\vskip 1in
-\begin{center}
-{\bf #2}
-\end{center}
-\vskip 0.5in
-\begin{center}
-\writtenby
-\end{center}
-\vskip 1.5in
-{\bf Abstract: } #3
-\hbox to \hsize{\hrulefill} % draw a line
-A.I.Lab Working Papers are produced for internal circulation and may
-contain information that is, for example, too preliminary or too detailed
-for formal publication. It is not intended that they should be considered
-papers to which reference can be made in the literature.
-\end{titlepage}
-}
-
-% stuff to change the format of figures
-%
-% change parameters to position floats
-%
-\renewcommand{\topfraction}{.9}
-\renewcommand{\bottomfraction}{.9}
-\renewcommand{\textfraction}{.1}
-\renewcommand{\floatpagefraction}{.8}
-\setcounter{totalnumber}{10}
-\setcounter{topnumber}{10}
-\setcounter{bottomnumber}{10}
-
-%
-% The new definition for chapterhead
-%
-%\def\@chapapp{\sf Section}
-\def\@makechapterhead#1{ \vspace*{10pt} { \parindent 0pt \raggedright
-\hfill \bf \hfill \thechapter. \ #1\par
-\nobreak \vskip 5pt \hrule
-\nobreak \vskip 40pt }}
-
-%
-% new section commands
-%
-\def\section{\@startsection {section}{1}{\z@}{3.5ex plus 1ex minus
- .2ex}{2.3ex plus .2ex}{\bf}}
-\def\subsection{\@startsection{subsection}{2}{\z@}{3.25ex plus 1ex minus
- .2ex}{1.5ex plus .2ex}{\bf}}
-\def\subsubsection{\@startsection{subsubsection}{3}{\z@}{3.25ex plus 1ex minus
- .2ex}{1.5ex plus .2ex}{\normalsize\bf}}
-\def\paragraph{\@startsection
- {paragraph}{4}{\z@}{3.25ex plus 1ex minus .2ex}{-1em}{\normalsize\bf}}
-\def\subparagraph{\@startsection
- {subparagraph}{4}{\parindent}{3.25ex plus 1ex minus
- .2ex}{-1em}{\normalsize\bf}}
-
-%
-% The new quotation environment
-%
-% we use the peni font that looks rather nice.
-%\font\peni=peni10
-%\def\myquot#1{{\hbox{}
-%\hfill\parbox{3.5in}{\raggedright{\peni #1}}
-% \\*[\parskip]}\par}
-
-
-%\def\quotauth#1{\hbox to \hsize{\hfill \small #1 \\} \par}
-
-% Date and time macros
-\newcount\hour \newcount\minute
-\hour=\the\time \minute=\the\time
-\divide\hour by 60 \multiply\hour by 60%
-\advance\minute by -\hour \divide\hour by 60%
-\def\daytime{\number\hour:\ifnum \minute<10 0\fi\number\minute}%
-\def\monthname {\ifcase\month \or
- Jan\or Feb\or Mar\or Apr\or May\or Jun\or
- Jul\or Aug\or Sep\or Oct\or Nov\or Dec\fi}%
-\def\date{\monthname~\number\day,~\number\year}%
-\def\datetime{\monthname~\number\day,~\number\year~[\daytime]}%
-\def\slashdate{\number\month/\number\day/\number\year}%
-\def\slashdatetime{\number\month/\number\day/\number\year~[\daytime]}%
-
-% the new list environments - works only for top level environments
-\newenvironment{alphenumerate}{\def\labelenumi{(\alph{enumi})}\begin{enumerate}}{\end{enumerate}}
-
-\newenvironment{romanenumerate}{\def\labelenumi{\roman{enumi}.}\begin{enumerate}}{\end{enumerate}}
-
-\newenvironment{Romanenumerate}{\def\labelenumi{\Roman{enumi}.}\begin{enumerate}}{\end{enumerate}}
-
-\newenvironment{Alphenumerate}{\def\labelenumi{(\Alph{enumi})}\begin{enumerate}}{\end{enumerate}}
-
-% Date and time macros
-\newcount\hour \newcount\minute
-\hour=\the\time \minute=\the\time
-\divide\hour by 60 \multiply\hour by 60%
-\advance\minute by -\hour \divide\hour by 60%
-\def\daytime{\number\hour:\ifnum \minute<10 0\fi\number\minute}%
-\def\monthname {\ifcase\month \or
- Jan\or Feb\or Mar\or Apr\or May\or Jun\or
- Jul\or Aug\or Sep\or Oct\or Nov\or Dec\fi}%
-\def\longmonthname {\ifcase\month \or
- January\or February\or March\or April\or May\or June\or
- July\or August\or September\or October\or November\or December\fi}%
-\def\date{\monthname~\number\day,~\number\year~[\daytime]}%
-\def\slashdate{\number\month/\number\day/\number\year}%
-\def\shortdate{\longmonthname,~\number\year}%
-
-% Math macros
-\def\v#1{\mbox{$\bf #1$}}
-\def\cross{\times}
-\def\jac_t{{\bf J}^{T}}
-\def\jac_inv{{\bf J}^{-1}}
-\def\jac{{\bf J}}
-
-% Float stuff
-%\def\@float#1{\@ifnextchar[{\@xfloat{#1}}{\edef\@tempa{\noexpand\@xfloat
-% {#1}[\csname fps@#1\endcsname]}\@tempa}}
-%
-%\def\@xfloat#1[#2]{\ifhmode \@bsphack\@floatpenalty -\@Mii\else
-% \@floatpenalty-\@Miii\fi\def\@captype{#1}\ifinner
-% \@parmoderr\@floatpenalty\z@
-% \else\@next\@currbox\@freelist{\@tempcnta\csname ftype@#1\endcsname
-% \multiply\@tempcnta\@xxxii\advance\@tempcnta\sixt@@n
-% \@tfor \@tempa :=#2\do
-% {\if\@tempa h\advance\@tempcnta \@ne\fi
-% \if\@tempa t\advance\@tempcnta \tw@\fi
-% \if\@tempa b\advance\@tempcnta 4\relax\fi
-% \if\@tempa p\advance\@tempcnta 8\relax\fi
-% }\global\count\@currbox\@tempcnta}\@fltovf\fi
-% \global\setbox\@currbox\vbox\bgroup
-% \boxmaxdepth\z@
-% \hsize\columnwidth \@parboxrestore}
-%
-%\def\end@float{\egroup
-% \ifnum\@floatpenalty <\z@
-% \@cons\@currlist\@currbox
-% \ifdim \ht\@currbox >\textheight
-% \ht\@currbox\textheight \fi
-% \global\@outputdonefalse
-% \ifnum\@floatpenalty < -\@Mii
-% \penalty\@floatpenalty
-% \if@outputdone\else\global\@outputdonetrue
-% \vbox{}\penalty\@floatpenalty\fi
-% \else \vadjust{\penalty \@floatpenalty}\@esphack\fi\fi}
-%
-%\def\@dblfloat#1{\if@twocolumn\else\@latexerr{Two-column float
-%on one-column page}\@ehd\fi
-%\@ifnextchar[{\@xdblfloat{#1}}{\@xdblfloat{#1}[tp]}}
-
-% line space commands (from dms.sty)
-\def\varspace#1{\def\baselinestretch{#1}\large\normalsize}
-\def\dspace{\def\baselinestretch{1.5}\large\normalsize}
-\def\mspace{\def\baselinestretch{1.25}\large\normalsize}
-\def\sspace{\def\baselinestretch{1.0}\large\normalsize}
-\def\tspace{\def\baselinestretch{.85}\large\normalsize}
-\let\double=\dspace
-\let\single=\sspace
-
-% Illustrate macros for latex - see GLR's working paper on the subject
-\newcommand{\psbox}[3]{%
- \makebox[#1][l]{%
- \parbox[b]{0.0in}{\vspace*{#2}}%
- \special{psfile=#3}}}
-
-% 4.25in=306 ps points, 5.50 in = 396 ps points
-\newlength{\illheight}
-\newcommand{\illustratefile}[3]{%
- \makebox[#1]{%
- \setlength{\illheight}{#2}%
- \raisebox{0.5\illheight}[\illheight][0.0in]{%
- \special{psfile=#3 hoffset=-306 voffset=-396}}}}
-\endinput
-
-% arch-tag: "185f1ce2-313d-11d8-abb9-000c76244c24"
diff -rN -u old-iterate/doc/gendocs.sh new-iterate/doc/gendocs.sh
--- old-iterate/doc/gendocs.sh 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/gendocs.sh 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,285 @@
+#!/bin/sh
+# gendocs.sh -- generate a GNU manual in many formats. This script is
+# mentioned in maintain.texi. See the help message below for usage details.
+# $Id: gendocs.sh,v 1.17 2006/05/19 00:07:52 karl Exp $
+#
+# Copyright (C) 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+#
+# 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, 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, you can either send email to this
+# program's maintainer or write to: The Free Software Foundation,
+# Inc.; 51 Franklin Street, Fifth Floor; Boston, MA 02110-1301, USA.
+#
+# Original author: Mohit Agarwal.
+# Send bug reports and any other correspondence to bug-texinfo@gnu.org.
+
+prog=`basename "$0"`
+srcdir=`pwd`
+
+scripturl="http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh"
+templateurl="http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template"
+
+: ${MAKEINFO="makeinfo"}
+: ${TEXI2DVI="texi2dvi -t @finalout"}
+: ${DVIPS="dvips"}
+: ${DOCBOOK2TXT="docbook2txt"}
+: ${DOCBOOK2HTML="docbook2html"}
+: ${DOCBOOK2PDF="docbook2pdf"}
+: ${DOCBOOK2PS="docbook2ps"}
+: ${GENDOCS_TEMPLATE_DIR="."}
+unset CDPATH
+
+rcs_revision='$Revision: 1.17 $'
+rcs_version=`set - $rcs_revision; echo $2`
+program=`echo "$0" | sed -e 's!.*/!!'`
+version="gendocs.sh $rcs_version
+
+Copyright (C) 2006 Free Software Foundation, Inc.
+There is NO warranty. You may redistribute this software
+under the terms of the GNU General Public License.
+For more information about these matters, see the files named COPYING."
+
+usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE
+
+Generate various output formats from PACKAGE.texinfo (or .texi or .txi) source.
+See the GNU Maintainers document for a more extensive discussion:
+ http://www.gnu.org/prep/maintain_toc.html
+
+Options:
+ -o OUTDIR write files into OUTDIR, instead of manual/.
+ --docbook convert to DocBook too (xml, txt, html, pdf and ps).
+ --html ARG pass indicated ARG to makeinfo for HTML targets.
+ --help display this help and exit successfully.
+ --version display version information and exit successfully.
+
+Simple example: $prog emacs \"GNU Emacs Manual\"
+
+Typical sequence:
+ cd YOURPACKAGESOURCE/doc
+ wget \"$scripturl\"
+ wget \"$templateurl\"
+ $prog YOURMANUAL \"GNU YOURMANUAL - One-line description\"
+
+Output will be in a new subdirectory \"manual\" (by default, use -o OUTDIR
+to override). Move all the new files into your web CVS tree, as
+explained in the Web Pages node of maintain.texi.
+
+MANUAL-TITLE is included as part of the HTML <title> of the overall
+manual/index.html file. It should include the name of the package being
+documented. manual/index.html is created by substitution from the file
+$GENDOCS_TEMPLATE_DIR/gendocs_template. (Feel free to modify the
+generic template for your own purposes.)
+
+If you have several manuals, you'll need to run this script several
+times with different YOURMANUAL values, specifying a different output
+directory with -o each time. Then write (by hand) an overall index.html
+with links to them all.
+
+You can set the environment variables MAKEINFO, TEXI2DVI, and DVIPS to
+control the programs that get executed, and GENDOCS_TEMPLATE_DIR to
+control where the gendocs_template file is looked for.
+
+Email bug reports or enhancement requests to bug-texinfo@gnu.org.
+"
+
+calcsize()
+{
+ size=`ls -ksl $1 | awk '{print $1}'`
+ echo $size
+}
+
+outdir=manual
+html=
+PACKAGE=
+MANUAL_TITLE=
+
+while test $# -gt 0; do
+ case $1 in
+ --help) echo "$usage"; exit 0;;
+ --version) echo "$version"; exit 0;;
+ -o) shift; outdir=$1;;
+ --docbook) docbook=yes;;
+ --html) shift; html=$1;;
+ -*)
+ echo "$0: Unknown or ambiguous option \`$1'." >&2
+ echo "$0: Try \`--help' for more information." >&2
+ exit 1;;
+ *)
+ if test -z "$PACKAGE"; then
+ PACKAGE=$1
+ elif test -z "$MANUAL_TITLE"; then
+ MANUAL_TITLE=$1
+ else
+ echo "$0: extra non-option argument \`$1'." >&2
+ exit 1
+ fi;;
+ esac
+ shift
+done
+
+if test -s "$srcdir/$PACKAGE.texinfo"; then
+ srcfile=$srcdir/$PACKAGE.texinfo
+elif test -s "$srcdir/$PACKAGE.texi"; then
+ srcfile=$srcdir/$PACKAGE.texi
+elif test -s "$srcdir/$PACKAGE.txi"; then
+ srcfile=$srcdir/$PACKAGE.txi
+else
+ echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2
+ exit 1
+fi
+
+if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then
+ echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2
+ echo "$0: it is available from $templateurl." >&2
+ exit 1
+fi
+
+echo Generating output formats for $srcfile
+
+cmd="${MAKEINFO} -o $PACKAGE.info \"$srcfile\""
+echo "Generating info files... ($cmd)"
+eval "$cmd"
+mkdir -p $outdir/
+tar czf $outdir/$PACKAGE.info.tar.gz $PACKAGE.info*
+info_tgz_size=`calcsize $outdir/$PACKAGE.info.tar.gz`
+# do not mv the info files, there's no point in having them available
+# separately on the web.
+
+cmd="${TEXI2DVI} \"$srcfile\""
+echo "Generating dvi ... ($cmd)"
+eval "$cmd"
+
+# now, before we compress dvi:
+echo Generating postscript...
+${DVIPS} $PACKAGE -o
+gzip -f -9 $PACKAGE.ps
+ps_gz_size=`calcsize $PACKAGE.ps.gz`
+mv $PACKAGE.ps.gz $outdir/
+
+# compress/finish dvi:
+gzip -f -9 $PACKAGE.dvi
+dvi_gz_size=`calcsize $PACKAGE.dvi.gz`
+mv $PACKAGE.dvi.gz $outdir/
+
+cmd="${TEXI2DVI} --pdf \"$srcfile\""
+echo "Generating pdf ... ($cmd)"
+eval "$cmd"
+pdf_size=`calcsize $PACKAGE.pdf`
+mv $PACKAGE.pdf $outdir/
+
+cmd="${MAKEINFO} -o $PACKAGE.txt --no-split --no-headers \"$srcfile\""
+echo "Generating ASCII... ($cmd)"
+eval "$cmd"
+ascii_size=`calcsize $PACKAGE.txt`
+gzip -f -9 -c $PACKAGE.txt >$outdir/$PACKAGE.txt.gz
+ascii_gz_size=`calcsize $outdir/$PACKAGE.txt.gz`
+mv $PACKAGE.txt $outdir/
+
+cmd="${MAKEINFO} --no-split --html -o $PACKAGE.html $html \"$srcfile\""
+echo "Generating monolithic html... ($cmd)"
+rm -rf $PACKAGE.html # in case a directory is left over
+eval "$cmd"
+html_mono_size=`calcsize $PACKAGE.html`
+gzip -f -9 -c $PACKAGE.html >$outdir/$PACKAGE.html.gz
+html_mono_gz_size=`calcsize $outdir/$PACKAGE.html.gz`
+mv $PACKAGE.html $outdir/
+
+cmd="${MAKEINFO} --html -o $PACKAGE.html $html \"$srcfile\""
+echo "Generating html by node... ($cmd)"
+eval "$cmd"
+split_html_dir=$PACKAGE.html
+(
+ cd ${split_html_dir} || exit 1
+ tar -czf ../$outdir/${PACKAGE}.html_node.tar.gz -- *.html
+)
+html_node_tgz_size=`calcsize $outdir/${PACKAGE}.html_node.tar.gz`
+rm -f $outdir/html_node/*.html
+mkdir -p $outdir/html_node/
+mv ${split_html_dir}/*.html $outdir/html_node/
+rmdir ${split_html_dir}
+
+echo Making .tar.gz for sources...
+srcfiles=`ls *.texinfo *.texi *.txi *.eps 2>/dev/null`
+tar cvzfh $outdir/$PACKAGE.texi.tar.gz $srcfiles
+texi_tgz_size=`calcsize $outdir/$PACKAGE.texi.tar.gz`
+
+if test -n "$docbook"; then
+ cmd="${MAKEINFO} -o - --docbook \"$srcfile\" > ${srcdir}/$PACKAGE-db.xml"
+ echo "Generating docbook XML... $(cmd)"
+ eval "$cmd"
+ docbook_xml_size=`calcsize $PACKAGE-db.xml`
+ gzip -f -9 -c $PACKAGE-db.xml >$outdir/$PACKAGE-db.xml.gz
+ docbook_xml_gz_size=`calcsize $outdir/$PACKAGE-db.xml.gz`
+ mv $PACKAGE-db.xml $outdir/
+
+ cmd="${DOCBOOK2HTML} -o $split_html_db_dir ${outdir}/$PACKAGE-db.xml"
+ echo "Generating docbook HTML... ($cmd)"
+ eval "$cmd"
+ split_html_db_dir=html_node_db
+ (
+ cd ${split_html_db_dir} || exit 1
+ tar -czf ../$outdir/${PACKAGE}.html_node_db.tar.gz -- *.html
+ )
+ html_node_db_tgz_size=`calcsize $outdir/${PACKAGE}.html_node_db.tar.gz`
+ rm -f $outdir/html_node_db/*.html
+ mkdir -p $outdir/html_node_db
+ mv ${split_html_db_dir}/*.html $outdir/html_node_db/
+ rmdir ${split_html_db_dir}
+
+ cmd="${DOCBOOK2TXT} ${outdir}/$PACKAGE-db.xml"
+ echo "Generating docbook ASCII... ($cmd)"
+ eval "$cmd"
+ docbook_ascii_size=`calcsize $PACKAGE-db.txt`
+ mv $PACKAGE-db.txt $outdir/
+
+ cmd="${DOCBOOK2PS} ${outdir}/$PACKAGE-db.xml"
+ echo "Generating docbook PS... $(cmd)"
+ eval "$cmd"
+ gzip -f -9 -c $PACKAGE-db.ps >$outdir/$PACKAGE-db.ps.gz
+ docbook_ps_gz_size=`calcsize $outdir/$PACKAGE-db.ps.gz`
+ mv $PACKAGE-db.ps $outdir/
+
+ cmd="${DOCBOOK2PDF} ${outdir}/$PACKAGE-db.xml"
+ echo "Generating docbook PDF... ($cmd)"
+ eval "$cmd"
+ docbook_pdf_size=`calcsize $PACKAGE-db.pdf`
+ mv $PACKAGE-db.pdf $outdir/
+fi
+
+echo Writing index file...
+curdate=`date '+%B %d, %Y'`
+sed \
+ -e "s!%%TITLE%%!$MANUAL_TITLE!g" \
+ -e "s!%%DATE%%!$curdate!g" \
+ -e "s!%%PACKAGE%%!$PACKAGE!g" \
+ -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \
+ -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \
+ -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \
+ -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \
+ -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \
+ -e "s!%%PDF_SIZE%%!$pdf_size!g" \
+ -e "s!%%PS_GZ_SIZE%%!$ps_gz_size!g" \
+ -e "s!%%ASCII_SIZE%%!$ascii_size!g" \
+ -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \
+ -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \
+ -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \
+ -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \
+ -e "s!%%DOCBOOK_PS_GZ_SIZE%%!$docbook_ps_gz_size!g" \
+ -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \
+ -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \
+ -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \
+ -e "s,%%SCRIPTURL%%,$scripturl,g" \
+ -e "s!%%SCRIPTNAME%%!$prog!g" \
+$GENDOCS_TEMPLATE_DIR/gendocs_template >$outdir/index.html
+
+echo "Done! See $outdir/ subdirectory for new files."
diff -rN -u old-iterate/doc/gendocs_template new-iterate/doc/gendocs_template
--- old-iterate/doc/gendocs_template 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/gendocs_template 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!-- $Id: gendocs_template,v 1.7 2005/05/15 00:00:08 karl Exp $ -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+
+<!--
+
+ This template was adapted from Texinfo:
+ http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template
+
+-->
+
+
+<head>
+<title>%%TITLE%%</title>
+<meta http-equiv="content-type" content='text/html; charset=utf-8' />
+<!-- <link rel="stylesheet" type="text/css" href="/gnu.css" /> -->
+<!-- <link rev="made" href="webmasters@gnu.org" /> -->
+<style>
+/* CSS style taken from http://gnu.org/gnu.css */
+
+html, body {
+ background-color: #FFFFFF;
+ color: #000000;
+ font-family: sans-serif;
+}
+
+a:link {
+ color: #1f00ff;
+ background-color: transparent;
+ text-decoration: underline;
+ }
+
+a:visited {
+ color: #9900dd;
+ background-color: transparent;
+ text-decoration: underline;
+ }
+
+a:hover {
+ color: #9900dd;
+ background-color: transparent;
+ text-decoration: none;
+ }
+
+.center {
+ text-align: center;
+}
+
+.italic {
+ font-style: italic;
+ }
+
+.bold {
+ font-weight: bold;
+ }
+
+.quote {
+ margin-left: 40px;
+ margin-right: 40px;
+}
+
+.hrsmall {
+ width: 80px;
+ height: 1px;
+ margin-left: 20px;
+}
+
+.td_title {
+ border-color: #3366cc;
+ border-style: solid;
+ border-width: thin;
+ color: #3366cc;
+ background-color : #f2f2f9;
+ font-weight: bold;
+}
+
+.td_con {
+ padding-top: 3px;
+ padding-left: 8px;
+ padding-bottom: 3px;
+ color : #303030;
+ background-color : #fefefe;
+ font-size: smaller;
+}
+
+.translations {
+ background-color: transparent;
+ color: black;
+ font-family: serif;
+ font-size: smaller;
+}
+
+.fsflink {
+ font-size: smaller;
+ font-family: monospace;
+ color : #000000;
+ border-left: #3366cc thin solid;
+ border-bottom: #3366cc thin solid;
+ padding-left: 5px;
+ padding-bottom: 5px;
+}
+
+/*
+ * rtl stands for right-to-left layout, as in farsi/persian,
+ * arabic, etc. See also trans_rtl.
+ */
+.fsflink_rtl {
+ font-size: smaller;
+ font-family: monospace;
+ color : #000000;
+ border-right: #3366cc thin solid;
+ border-bottom: #3366cc thin solid;
+ padding-right: 5px;
+ padding-bottom: 5px;
+}
+
+.trans {
+ font-size: smaller;
+ color : #000000;
+ border-left: #3366cc thin solid;
+ padding-left: 20px;
+}
+
+.trans_rtl {
+ font-size: smaller;
+ color : #000000;
+ border-right: #3366cc thin solid;
+ padding-right: 20px;
+}
+
+img {
+ border: none 0;
+}
+
+td.side {
+ color: #3366cc;
+/* background: #f2f2f9;
+ border-color: #3366cc;
+ border-style: solid;
+ border-width: thin; */
+ border-color: white;
+ border-style: none;
+ vertical-align: top;
+ width: 150px;
+}
+
+div.copyright {
+ font-size: 80%;
+ border: 2px solid #3366cc;
+ padding: 4px;
+ background: #f2f2f9;
+ border-style: solid;
+ border-width: thin;
+}
+
+.footnoteref {
+ font-size: smaller;
+ vertical-align: text-top;
+}
+</style>
+</head>
+
+<!-- This document is in XML, and xhtml 1.0 -->
+<!-- Please make sure to properly nest your tags -->
+<!-- and ensure that your final document validates -->
+<!-- consistent with W3C xhtml 1.0 and CSS standards -->
+<!-- See validator.w3.org -->
+
+<body>
+
+<h3>%%TITLE%%</h3>
+
+<!-- <address>Free Software Foundation</address> -->
+<address>last updated %%DATE%%</address>
+
+<!--
+<p>
+<a href="/graphics/gnu-head.jpg">
+ <img src="/graphics/gnu-head-sm.jpg"
+ alt=" [image of the head of a GNU] "
+ width="129" height="122" />
+</a>
+<a href="/philosophy/gif.html">(no gifs due to patent problems)</a>
+</p>
+-->
+
+<hr />
+
+<p>This document <!--(%%PACKAGE%%)--> is available in the following formats:</p>
+
+<ul>
+ <li><a href="%%PACKAGE%%.html">HTML
+ (%%HTML_MONO_SIZE%%K characters)</a> - entirely on one web page.</li>
+ <li><a href="html_node/index.html">HTML</a> - with one web page per
+ node.</li>
+ <li><a href="%%PACKAGE%%.html.gz">HTML compressed
+ (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+ one web page.</li>
+ <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+ (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per node.</li>
+ <li><a href="%%PACKAGE%%.info.tar.gz">Info document
+ (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
+ <li><a href="%%PACKAGE%%.txt">ASCII text
+ (%%ASCII_SIZE%%K characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+ (%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+ (%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li>
+ <li><a href="%%PACKAGE%%.ps.gz">PostScript file
+ (%%PS_GZ_SIZE%%K characters gzipped)</a>.</li>
+ <li><a href="%%PACKAGE%%.pdf">PDF file
+ (%%PDF_SIZE%%K characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+ (%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li>
+</ul>
+
+<p>(This page was generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
+script</a>.)</p>
+
+<div class="copyright">
+<p>
+Return to <a href="/project/iterate/">Iterate's home page</a>.
+</p>
+
+<!--
+<p>
+Please send FSF &amp; GNU inquiries to
+<a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>.
+There are also <a href="/home.html#ContactInfo">other ways to contact</a>
+the FSF.
+<br />
+Please send broken links and other corrections (or suggestions) to
+<a href="mailto:webmasters@gnu.org"><em>webmasters@gnu.org</em></a>.
+</p>
+-->
+
+<p>
+<!--
+Copyright (C) 2006 Lu&iacute;s Oliveira &lt;loliveira at common-lisp.net&gt;
+<br />
+Verbatim copying and distribution of this entire article is
+permitted in any medium, provided this notice is preserved.
+-->
+</p>
+
+<p>
+Updated: %%DATE%%
+<!-- timestamp start -->
+<!-- $Date: 2005/05/15 00:00:08 $ $Author: karl $ -->
+<!-- timestamp end -->
+</p>
+</div>
+
+</body>
+</html>
Binary files old-iterate/doc/iterate-bare.pdf and new-iterate/doc/iterate-bare.pdf differ
diff -rN -u old-iterate/doc/iterate-bare.tex new-iterate/doc/iterate-bare.tex
--- old-iterate/doc/iterate-bare.tex 2014-04-17 15:33:25.000000000 -0700
+++ new-iterate/doc/iterate-bare.tex 1969-12-31 16:00:00.000000000 -0800
@@ -1,474 +0,0 @@
-\documentclass[12pt]{article}
-
-\newcommand{\lisp}{\tt}
-\newcommand{\iter}{{\lisp iterate}}
-\newcommand{\Iter}{{\lisp Iterate}}
-\newcommand{\Do}{{\lisp do}}
-\newcommand{\Doing}{{\lisp doing}}
-\newcommand{\looP}{{\lisp loop}}
-\newcommand{\LooP}{{\lisp Loop}}
-\newcommand{\setf}{{\lisp setf}}
-\newcommand{\iman}{{\em The Iterate Manual\/}}
-
-\begin{document}
-
-
-\title{Don't Loop, Iterate}
-\author{Jonathan Amsterdam}
-
-\maketitle
-
-\section{Introduction}
-
-Above all the wonders of Lisp's pantheon stand its metalinguistic
-tools; by their grace have Lisp's acolytes been liberated from the
-rigid asceticism of lesser faiths. Thanks to Macro and kin, the
-jolly, complacent Lisp hacker can gaze through a fragrant cloud of
-setfs and defstructs at the emaciated unfortunates below, scraping out
-their meager code in inflexible notation, and sneer superciliously.
-It's a good feeling.
-
-But all's not joy in Consville. For---I beg your pardon, but---there
-really is no good way to {\em iterate\/} in Lisp. Now, some are happy
-to map their way about, whether for real with {\lisp mapcar} and
-friends, or with the make-believe of Series; others are so satisfied
-with \Do\ it's a wonder they're not C hackers.\footnote{Hey, don't get
-mad---I'll be much more polite later, when the real paper starts.}
-Still others have gotten by with \looP, but are getting tired of
-looking up the syntax in the manual over and over again. And in the
-elegant schemes of some, only tail recursion and lambdas figure. But
-that still leaves a sizeable majority of folk---well, me, at
-least---who would simply like to {\em iterate,} thank you, but in a
-way that provides nice abstractions, is extensible, and looks like
-honest-to-God Lisp.
-
-In what follows I describe a macro package, called \iter, that
-provides the power and convenient abstractions of \looP\ but in a more
-syntactically palatable way. \iter\ also has many features that
-\looP\ lacks, like generators and better support for nested loops.
-\iter\ generates inline code, so it's more efficient than using the
-higher-order function approach. And \iter\ is also extensible---it's
-easy to add new clauses to its vocabulary in order to express new
-patterns of iteration in a convenient way.
-
-\iter\ is fully documented in AI Lab Memo No. 1236, \iman.
-
-\section{More about \Iter}
-
-A Common Lisp programmer who wonders what's lacking with present-day
-iteration features would do well to consider \setf. Of course,
-\setf\ doesn't iterate, but it has some other nice properties. It's
-easy to use, for one thing. It's extensible---you can define new
-\setf\ methods very easily, so that \setf\ will work with new forms.
-\setf\ is also efficient, turning into code that's as good as anyone
-could write by hand. Arguably, \setf\ provides a nice abstraction:
-it allows you to view value-returning forms, like {\lisp (car ...)} or
-{\lisp (get ...)} as locations that can be stored into. Finally and
-most obviously, \setf\ {\em looks\/} like Lisp; it's got a syntax
-right out of {\lisp setq}.
-
-\iter\ attempts to provide all of these properties. Here is a simple
-use of \iter\ that returns all the elements of {\lisp num-list}
-that are greater than three:
-
-\pagebreak[4]
-
-\begin{verbatim}
-(iterate (for el in num-list)
- (when (> el 3)
- (collect el)))
-\end{verbatim}
-
-An \iter\ form consists of the symbol \iter\ followed by some Lisp
-forms. Any legal Lisp form is allowed, as well as certain forms that
-\iter\ treats specially, called {\em clauses}. {\lisp for...in} and
-{\lisp collect} are the two clauses in the above example. An \iter\
-clause can appear anywhere a Lisp form can appear; \iter\ walks its
-body, looking inside every form, processing \iter\ clauses when it
-finds them. It even expands macros, so you can write macros that
-contain \iter\ clauses. Almost all clauses use the syntax of function
-keyword-argument lists: alternating keywords and arguments. \iter\
-keywords don't require a preceding colon, but you can use one if you
-like.
-
-\iter\ provides many convenient iteration abstractions, most of
-them familiar to \looP\ users. Iteration-driving clauses (those
-beginning with {\lisp for}) can iterate over numbers, lists, arrays,
-hashtables, packages and files. There are clauses for collecting
-values into a list, summing and counting, maximizing, finding maximal
-elements, and various other things. Here are a few examples, for
-extra flavor.
-
-\pagebreak[2]
-To sum a list of numbers:
-\begin{verbatim}
-(iterate (for i in list)
- (sum i))
-\end{verbatim}
-
-\pagebreak[2]
-To find the length of the shortest element in a list:
-\begin{verbatim}
-(iterate (for el in list)
- (minimize (length el)))
-\end{verbatim}
-
-\pagebreak[2]
-To find the shortest element in a list:
-\begin{verbatim}
-(iterate (for el in list)
- (finding el minimizing (length el)))
-\end{verbatim}
-
-\pagebreak[2]
-To return {\lisp t} only if every other element of a list is odd:
-\begin{verbatim}
-(iterate (for els on list by #'cddr)
- (always (oddp (car els))))
-\end{verbatim}
-
-\pagebreak[2]
-To split an association list into two separate lists (this example
-uses \iter's ability to do destructuring):
-\begin{verbatim}
-(iterate (for (key . item) in alist)
- (collect key into keys)
- (collect item into items)
- (finally (return (values keys items))))
-\end{verbatim}
-
-
-\section{Comparisons With Other Iteration Methods}
-
-As with any aspect of coding, how to iterate is a matter of taste. I
-do not wish to dictate taste or even to suggest that \iter\ is a
-``better'' way to iterate than other methods. I would, however, like
-to examine the options, and explain why I prefer \iter\ to its
-competitors.
-
-\subsection{\Do, {\lisp dotimes} and {\lisp dolist}}
-
-The \Do\ form has long been a Lisp iteration staple. It provides for
-binding of iteration variables, an end-test, and a body of arbitrary
-code. It can be a bit cumbersome for simple applications, but
-the most common special cases---iterating over the integers
-from zero and over the members of a list---appear more conveniently as
-{\lisp dotimes} and {\lisp dolist}.
-
-\Do's major problem is that it provides no abstraction. For example,
-collection is typically handled by binding a variable to {\lisp nil},
-pushing elements onto the variable, and {\lisp nreverse}ing the
-result before returning it. Such a common iteration pattern should be
-easier to write. (It is, using {\lisp mapcar}---but see below.)
-
-Another problem with \Do, for me at least, is that it's hard to read.
-The crucial end-test is buried between the bindings and the body,
-marked off only by an extra set of parens (and some indentation). It
-is also unclear, until after a moment of recollection, whether the
-end-test has the sense of a ``while'' or an ``until.''
-
-Despite its flaws, \Do\ is superior to the iteration facilities of
-every other major programming language except CLU. Perhaps that is
-the reason many Lisp programmers don't mind using it.
-
-
-\subsection{Tail Recursion}
-% (check hyphenation)
-
-Tail-recursive implementations of loops, like those found in Scheme
-code \cite{SchemeBook}, are parsimonious and illuminating. They have
-the advantage of looking like recursion, hence unifying the notation
-for two different types of processes. For example, if only
-tail-recursion is used, a loop that operates on list elements from
-front to back looks very much like a recursion that operates on them
-from back to front.
-
-However, using tail-recursion exclusively can lead to cumbersome code
-and a proliferation of functions, especially when one would like to
-embed a loop inside a function. Tail-recursion also provides no
-abstraction for iteration; in Scheme, that is typically done with
-higher-order functions.
-
-
-\subsection{Higher-order Functions}
-
-Lisp's age-old mapping functions, recently revamped for Common Lisp
-\cite{CLM}, are another favorite for iteration. They provide a
-pleasing abstraction, and it's easy to write new higher-order
-functions to express common iteration patterns. Common Lisp already
-comes with many such useful functions, for removing, searching, and
-performing reductions on lists. Another Common Lisp advantage is that
-these functions work on any sequence---vectors as well as lists.
-
-One problem with higher-order functions is that they are inefficient,
-requiring multiple calls on their argument function. While the the
-built-ins, like {\lisp map} and {\lisp mapcar}, can be open-coded,
-that cannot be so easily done for user-written functions. Also, using
-higher-order functions often results in the creation of intermediate
-sequences that could be avoided if the iteration were written out
-explicitly.
-
-The second problem with higher-order functions is very much a matter
-of personal taste. While higher-order functions are theoretically
-elegant, they are often cumbersome to read and write. The unpleasant
-sharp-quote required by Common Lisp is particularly annoying here, and
-even in Scheme, I find the presence of a lambda with its argument list
-visually distracting.
-
-Another problem is that it's difficult to express iteration of
-sequences of integers without creating such sequences explicitly as
-lists or arrays. One could resort to tail-recursion or {\lisp
-dotimes}---but then it becomes very messy to express double
-iterations where one driver is over integers. Multiple iteration is
-easy in \iter, as illustrated by the following example, which creates
-an alist of list elements and their positions:
-
-{\samepage
-\begin{verbatim}
-(iterate (for el in list)
- (for i from 0)
- (collect (cons el i)))
-\end{verbatim}
-}
-
-
-\subsection{Streams and Generators}
-
-For really heavy-duty iteration jobs, nothing less than a
-coroutine-like mechanism will do. Such mechanisms hide the state of
-the iteration behind a convenient abstraction. A {\em generator\/} is
-a procedure that returns the next element in the iteration each time
-it is called. A {\em stream\/} (in the terminology of
-\cite{SchemeBook}) is a data structure which represents the iteration,
-but which computes the next element only on demand. Generators and
-streams support a similar style of programming. Here, for example, is
-how you might enumerate the leaves of a tree (represented as a Lisp
-list with atoms at the leaves) using streams:
-\begin{verbatim}
-(defun tree-leaves (tree)
- (if (atom tree)
- (stream-cons tree empty-stream)
- (stream-append (tree-leaves (car tree))
- (tree-leaves (cdr tree)))))
-\end{verbatim}
-
-Although {\lisp tree-leaves} looks like an ordinary recursion,
-it will only do enough work to find the first leaf before returning.
-The stream it returns can be accessed with {\lisp stream-car}, which
-will yield the (already computed) first leaf of the tree, or with
-{\lisp stream-cdr}, which will initiate computation of the next leaf.
-
-Such a computation would be cumbersome to write using \iter, or any of
-the other standard iteration constructs; in fact, it is not even
-technically speaking an iteration, if we confine that term to
-processes that take constant space and linear time. Streams, then,
-are definitely more powerful than standard iteration machinery.
-
-Unfortunately, streams are very expensive, since they must somehow
-save the state of the computation. Generators are typically cheaper,
-but are less powerful and still require at least a function call.
-So these powerful tools should be used only when necessary, and that
-is not very often; most of the time, ordinary iteration suffices.
-
-There is one aspect of generators that \iter\ can capture, and that is
-the ability to produce elements on demand. Say we wish to
-create an alist that pairs the non-null elements of a list with the
-positive integers. We saw above that it is easy to iterate over
-a list and a series of numbers simultaneously, but here we would like
-to do something a little different: we want to iterate over the list
-of elements, but only draw a number when we need one (namely, when a list
-element is non-null). The solution employs the \iter\ {\lisp generate}
-keyword in place of {\lisp for} and the special clause
-{\lisp next}:
-
-{\samepage
-\begin{verbatim}
-(iterate (for el in list)
- (generate i from 1)
- (if el
- (collect (cons el (next i)))))
-\end{verbatim}
-}
-
-Using {\lisp next} with any driver variable changes how that driver
-works. Instead of supplying its values one at a time on each iteration,
-the driver computes a value only when a {\lisp next} clause is
-executed. This ability to obtain values on demand greatly increases
-\iter's power. Here, {\lisp el} is set to the next element of the
-list on each iteration, as usual; but {\lisp i} is set only when
-{\lisp (next i)} is executed.
-
-\subsection{Series}
-
-Richard C. Waters has developed a very elegant notation called Series
-which allows iteration to be expressed as sequence-mapping somewhat in
-the style of APL, but which compiles to efficient looping code
-\cite{Series}.
-
-My reasons for not using Series are, again, matters of taste. Like many
-elegant notations, Series can be somewhat cryptic. Understanding what a
-Series expression does can require some effort until one has mastered
-the idiom. And if you wish to share your code with others, they will
-have to learn Series as well. \iter\ suffers from this problem to some
-extent, but since the iteration metaphor it proposes is much more
-familiar to most programmers than that of Series, it is considerably
-easier to learn and read.
-
-\subsection{{\lisp Prog} and {\lisp Go}}
-
-Oh, don't be silly.
-
-
-\subsection{\LooP}
-
-\looP\ is the iteration construct most similar to \iter\ in
-appearance. \looP\ is a macro written originally for MacLisp and in
-widespread use \cite{Loop}. It has been adopted as part of Common
-Lisp. \looP\ provides high-level iteration with abstractions for
-collecting, summing, maximizing and so on. Recall our first \iter\
-example:
-
-\pagebreak[2]
-\begin{verbatim}
-(iterate (for el in num-list)
- (when (> el 3)
- (collect el)))
-\end{verbatim}
-
-\pagebreak[2]
-Expressed with \looP, it would read
-n
-\begin{verbatim}
-(loop for el in list
- when (> el 3)
- collect el)
-\end{verbatim}
-
-The similarity between the two macros should immediately be apparent.
-Most of \iter's clauses were borrowed from \looP. But compared to
-\iter, \looP\ has a paucity of parens. Though touted as more readable
-than heavily-parenthesized code, \looP's Pascalish syntax creates
-several problems. First, many dyed-in-the-wool Lisp hackers simply
-find it ugly. Second, it requires learning the syntax of a whole new
-sublanguage. Third, the absence of parens makes it hard to parse,
-both by machine and, more importantly, by human. Fourth, one often
-has to consult the manual to recall lesser-used aspects of the strange
-syntax. Fifth, there is no good interface with the rest of Lisp, so
-\looP\ clauses cannot appear inside Lisp forms and macros cannot
-expand to pieces of \looP. And Sixth, pretty-printers and indenters
-that don't know about \looP\ will invariably display it wrongly. This
-is particularly a problem with program-editor indenters. A reasonably
-clever indenter, like that of Gnu Emacs, can indent nearly any normal
-Lisp form correctly, and can be easily customized for most new forms.
-But it can't at present handle \looP. The syntax of \iter\ was
-designed to keep parens to a minimum, but conform close enough to Lisp
-so as not to confuse code-display tools. Gnu Emacs indents \iter\
-reasonably with no modifications.
-
-Indenting is a mere annoyance; \looP's lack of extensibility is a more
-serious problem. The original \looP\ was completely extensible, but
-the Symbolics version only provides for the definition of new
-iteration-driving clauses, and the Common Lisp specification does not
-have any extension mechanism. But extensibility is a boon. Consider
-first the problem of adding the elements of a list together, which can
-be accomplished with \iter\ by
-
-\pagebreak[3]
-\begin{verbatim}
-(iterate (for el in list)
- (sum el))
-\end{verbatim}
-
-and in \looP\ with
-
-\begin{verbatim}
-(loop for el in list
- sum el)
-\end{verbatim}
-
-But now, say that you wished to compute the sum of the square roots of the
-elements. You could of course write, in either \looP\ or \iter,
-
-\begin{verbatim}
-(iterate (for el in list)
- (sum (sqrt el)))
-\end{verbatim}
-
-But perhaps you find yourself writing such loops often enough to make
-it worthwhile to create a new abstraction. There is nothing you can
-do in \looP, but in \iter\ you could simply write a macro:
-
-\begin{verbatim}
-(defmacro (sum-of-sqrts expr &optional into-var)
- `(sum (sqrt ,expr) into ,into-var))
-\end{verbatim}
-
-{\lisp sum-of-sqrts} is a perfectly ordinary Lisp macro. Since
-\iter\ expands all macros and processes the results, {\lisp
-(sum-of-sqrts el)} will behave exactly as if we'd written {\lisp
-(sum (sqrt el))}.
-
-There's also a way to define macros that use \iter's clause syntax.
-It's fully documented in \iman.
-
-%Just to beat a dead horse, I'd like to point out that there's no way
-%to define {\lisp for...maximizing} in
-%\looP.\footnote{In fact, it was in part the frustration of knowing
-%that \looP\ could generate code to maximize a value, but could not be
-%easily altered to supply the element associated with that maximum,
-%that prompted me to write \iter.}
-
-\section{Implementation}
-
-A Common Lisp implementation of \iter\ has existed for well over a year.
-It runs under Lucid for HP 300's, Sun 3's and SPARCstations, and on
-Symbolics Lisp machines. See \iman\ for details.
-
-\section{Conclusion}
-
-Iteration is a matter of taste. I find \iter\ more palatable than
-other iteration constructs: it's more readable, more efficient than
-most, provides nice abstractions, and can be extended.
-
-If you're new to Lisp iteration, start with \iter---look before you
-\looP. If you're already using \looP\ and like the power that it
-offers, but have had enough of its syntax and inflexibility, then my
-advice to you is, don't \looP---\iter.
-
-\pagebreak
-
-\begin{flushleft}
-\bf Acknowledgements
-\end{flushleft}
-
-Thanks to David Clemens for many helpful suggestions and for the
-egregious pun near the end. Conversations with Richard Waters prompted
-me to add many improvements to \iter. Alan Bawden, Sundar Narasimhan,
-and Jerry Roylance also provided useful comments. David Clemens and
-Oren Etzioni shared with me the joys of beta-testing.
-
-\begin{thebibliography}{9}
-
-\bibitem{SchemeBook} Abelson, Harold and Gerald Jay Sussman. {\em
-Structure and Interpretation of Computer Programs.} Cambridge, MA: The
-MIT Press, 1985.
-
-
-\bibitem{Loop} ``The loop Iteration Macro.'' In {\em Symbolics Common
-Lisp---Language Concepts}, manual 2A of the Symbolics documentation,
-pp. 541--567.
-
-\bibitem{CLM} Steele, Guy L. {\em Common Lisp: The Language}.
-Bedford, MA: Digital Press, 1984.
-
-\bibitem{Series} Waters, Richard C. {\em Optimization of Series
-Expressions: Part I: User's Manual for the Series Macro Package}. MIT
-AI Lab Memo No. 1082.
-
-\end{thebibliography}
-
-\end{document}
-
-
-
-% arch-tag: "c0ff23d7-313c-11d8-abb9-000c76244c24"
Binary files old-iterate/doc/iterate-manual.pdf and new-iterate/doc/iterate-manual.pdf differ
diff -rN -u old-iterate/doc/iterate-manual.tex new-iterate/doc/iterate-manual.tex
--- old-iterate/doc/iterate-manual.tex 2014-04-17 15:33:26.000000000 -0700
+++ new-iterate/doc/iterate-manual.tex 1969-12-31 16:00:00.000000000 -0800
@@ -1,2070 +0,0 @@
-% Fix ``.'' spacing in lists
-\documentstyle[12pt,aimemo]{article}
-
-\setlength{\textwidth}{6.0in}
-\setlength{\oddsidemargin}{0.25in}
-\setlength{\evensidemargin}{0.25in}
-\setlength{\topmargin}{0pt}
-\setlength{\headsep}{24pt}
-\setlength{\textheight}{8.5in}
-
-\let\origpar=\par
-
-% somehow, LaTex fucks with things so that the plain Tex \obeyspaces
-% doesn't work. This is the same, except we use an mbox containing
-% a space instead of just a space.
-
-\newcommand{\spc}{\mbox{ }}
-\newcommand{\tAb}{\mbox{ }}
-\def\obspaces{\catcode`\ =\active\catcode`\^^I=\active}
-{\obspaces \global\let =\spc\global\let^^I=\tAb}
-
-\newenvironment{program}{\medskip\samepage\tt\obeylines\obspaces}{\medskip}
-
-% use | for \tt
-\catcode`\|=13
-\newif\ifvbar
-\def|{\ifvbar
- \endgroup\vbarfalse
- \else
- \begingroup\tt\vbartrue
- \fi}
-
-
-
-\newcommand{\lisp}{\tt}
-\newcommand{\iter}{|iterate|}
-\newcommand{\iterpg}{|iterate-pg|}
-\newcommand{\setf}{|setf|}
-\newcommand{\nil}{|nil|}
-\newcommand{\nonnil}{non-\nil}
-\newcommand{\opt}{{\lisp \&optional}}
-\newcommand{\yields}{$\Rightarrow$}
-
-
-
-\newbox\Dots
-\setbox\Dots=\hbox{\small ...}
-\renewcommand{\dots}{\copy\Dots}
-
-% Here's a way to define an environment which will treat all
-% paragraphs inside it in the same manner. It's, as near as I can
-% figure, the way that Latex does things. Using \everypar won't work;
-% apparently Latex resets that a lot. What you have to do is: at the
-% top of the file do \let\origpar=\par. In the
-% begin part of the environment, do the parshape (or whatever), then say
-% \def\par{{\origpar}}. The extra braces are necessary. That's all
-% you have to do; at the end of the environment things will return to
-% normal automatically. Why does this all work? I have no idea.
-% Another important thing: there should be a blank line (i.e. a \par)
-% between the end of the last paragraph and the \end{environment}.
-
-\newlength{\clindent}
-\setlength{\clindent}{0.5in}
-\newlength{\clparindent}
-\setlength{\clparindent}{\parindent}
-
-\newenvironment{clauses}{\advance\linewidth -\parindent
- \hangindent\clindent\relax
- \hangafter=0
- \parindent=0pt
- \def\par{{\origpar}}}{}
-
-\newcommand{\cpar}{\hspace \clparindent}
-
-\newcommand{\startitem}{\bigskip\pagebreak[3]}
-\newcommand{\finishitem}{\smallskip}
-
-\newcommand{\clause}[1]{\startitem\Clause{#1}\finishitem}
-\newcommand{\Clause}[1]{\hbox{#1}}
-\newcommand{\clindex}[1]{\index{{\lisp #1}}}
-\newcommand{\clindexx}[2]{\index{{\lisp #1\dots #2}}}
-\newcommand{\clindexxx}[3]{\index{{\lisp #1\dots #2\dots #3}}}
-\newcommand{\clausex}[2]{\startitem\Clausex{#1}{#2}\finishitem}
-\newcommand{\Clausex}[2]{\Clause{|#1| #2}\clindex{#1}}
-
-\newcommand{\defvar}[1]{\startitem\deff{#1}{}{Variable}\finishitem}
-\newcommand{\defunexpvar}[1]{\startitem\deffnoindex{iterate::#1}{}{Variable}
- \lispindex{#1}\finishitem}
-\newcommand{\defun}[2]{\startitem\deff{#1}{#2}{Function}\finishitem}
-\newcommand{\defmacro}[2]{\startitem\deff{#1}{#2}{Macro}\finishitem}
-\newcommand{\defunx}[3]{\startitem\deffx{#1}{#2}{#3}{Function}\finishitem}
-\newcommand{\defmacrox}[3]{\startitem\deffx{#1}{#2}{#3}{Macro}\finishitem}
-\newcommand{\defunxx}[4]{\startitem\deffxx{#1}{#2}{#3}{#4}{Function}\finishitem}
-\newcommand{\defmacroxx}[4]{\startitem\deffxx{#1}{#2}{#3}{#4}{Macro}\finishitem}
-
-\newcommand{\deff}[3]{\deffnoindex{#1}{#2}{#3}\lispindex{#1}}
-\newcommand{\deffnoindex}[3]{\hbox to \hsize{{\tt #1} {\it #2}\hfill [{\it #3}]}}
-\newcommand{\deffx}[4]{\deff{#1}{#2}{#4}\moreargs{#1}{#3}}
-\newcommand{\deffxx}[5]{\deffx{#1}{#2}{#3}{#5}\moreargs{#1}{#4}}
-
-\newcommand{\moreargs}[2]{\hbox to \hsize{\phantom{\lisp #1} {\it #2}\hfill}}
-
-\newcommand{\lispindex}[1]{\index{{\lisp #1}}}
-
- \newenvironment{note}[1]{\pagebreak[2]\bigskip
- \hrule\smallskip\small
- {\setlength{\parindent}{0pt}
- \par{\bf #1:}}}{\smallskip\hrule\bigskip}
-
-
-
-\makeindex
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-%\thispagestyle{empty}
-
-%\vspace*{2in}
-
-%\title{The |Iterate| Manual}
-%\author{Jonathan Amsterdam}
-
-%\maketitle
-
-%\thispagestyle{empty}
-
-%\begin{center}
-%\Large *** DRAFT ***
-%\end{center}
-%This manual is in beta-test. It will become an AI Memo in a couple of
-%months. I would appreciate any comments or
-%corrections. You can reach me at email address |jba@ai.ai.mit.edu|.
-
-\begin{document}
-
-\def\writtenby{Jonathan Amsterdam}
-\def\contractno{This report describes research done at the Artificial
-Intelligence Laboratory of the Massachusetts Institute of Technology.
-Support for the laboratory's artificial intelligence research is
-provided in part by the Advanced Research Projects Agency of the
-Department of Defense under Office
-of Naval Research contract N00014-85-K-0124.}
-
-\AIMEMO{1236}{\Large The Iterate Manual \\[1in]}
-{This is the manual for version 1.4 of \iter, a powerful iteration
-macro for Common
-Lisp. \iter\ is similar to {\tt loop} but provides numerous additional
-features, is well integrated with Lisp, and is extensible.
-\vfill }
-
-
-% use ~ for \em
-\catcode`\~=13
-\newif\ifem
-\def~{\ifem
- \/\endgroup\emfalse
- \else
- \begingroup\em\emtrue
- \fi}
-
-
-
-%\pagebreak
-%\setcounter{page}{1}
-
-%\thispagestyle{empty}
-
-
-\tableofcontents
-
-\pagebreak
-\pagestyle{headings}
-
-\section{Introduction}
-
-\begin{sloppypar}
-This manual describes
-\iter, a powerful iteration facility for Common Lisp.
-\iter\ provides abstractions for many common iteration
-patterns and allows for the definition of additional patterns. \iter\ is
-a macro that expands into ordinary Lisp at
-compile-time, so it is more efficient than higher-order
-functions like |map| and |reduce.|
-While it is similar to |loop|, \iter\ offers a more Lisp-like syntax
-and enhanced extensibility.
-(For a more complete
-comparison of \iter\ with other iteration constructs, see MIT AI Lab Working
-Paper No. 324, ~Don't Loop, Iterate.~)
-\end{sloppypar}
-
-An \iter\ form consists of the symbol |iter|\footnote{You can also use
-|iterate|, but |iter| is preferred because it avoids potential conflicts with
-possible future additions to Common Lisp, and because it saves
-horizontal space when writing code.}
-followed by one or more
-forms, some of which may be \iter\
-~clauses.~ Here is a simple example of \iter\ which collects the
-numbers from 1 to 10 into a list, and returns the list. The return
-value is shown following the arrow.
-\begin{program}
-(iter (for i from 1 to 10)
- (collect i)) \yields (1 2 3 4 5 6 7 8 9 10)
-\end{program}
-This form contains two clauses: a |for| clause that steps the
-variable |i| over the integers from 1 to 10, and a |collect|
-clause that accumulates its argument into a list. With a few
-exceptions, all \iter\ clauses have the same format: alternating
-symbols (called ~keywords~) and expressions (called
-~arguments~). The syntax and terminology are those of Common
-Lisp's keyword lambda lists. One difference is that \iter's keywords
-do not have to begin with a colon---though they may, except for the
-first symbol of a clause. So you can also write |(for i :from
-1 :to 10)| if you prefer.
-
-Any Lisp form can appear in the body of an \iter, where it will have
-its usual meaning. \iter\ walks the entire body, expanding macros,
-and recognizing clauses at any level. This example collects all the
-odd numbers in a list:
-\begin{program}
-(iter (for el in list)
- (if (and (numberp el) (oddp el))
- (collect el)))
-\end{program}
-
-There are clauses for iterating over numbers, lists, arrays and other
-objects, and for
-collecting, summing, counting, maximizing and other useful operations.
-\iter\ also supports the creation of new variable bindings, stepping
-over multiple sequences at once, destructuring, and compiler
-declarations of variable types. The following example illustrates
-some of these features:
-\begin{program}
-(iter (for (key . item) in alist)
- (for i from 0)
- (declare (fixnum i))
- (collect (cons i key)))
-\end{program}
-
-This loop takes the keys of an alist and returns a new alist
-associating the keys with their positions in the original list. The
-compiler declaration for |i| will appear in the generated code
-in the appropriate place.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Clauses}
-
-Most of \iter's clauses will be familiar to |loop| programmers.
-(|loop| is an iteration macro that has been incorporated into Common
-Lisp. Seen Guy Steele's {\em Common Lisp, 2nd Edition}.)
-In
-nearly all cases they behave the same as their |loop| counterparts, so
-a |loop| user can switch to \iter\ with little pain (and much gain).
-
-All clauses with the standard keyword-argument syntax consist of two
-parts: a ~required~ part,
-containing keywords that must be present and in the right order; and
-an ~optional~ part, containing keywords that may be omitted and,
-if present, may occur in any order. In the descriptions below, the
-parts are separated by the Lisp lambda-list keyword \opt.
-
-
-\subsection{Drivers}
-
-An iteration-driving clause
-conceptually causes the iteration to go forward. Driver clauses in
-\iter\ allow iteration over numbers, lists, vectors, hashtables, packages,
-files and streams. Iteration-driving clauses must
-appear at the top level of an \iter\ form; they cannot be nested
-inside another clause. The driver variable is updated at the point
-where the driver clause occurs. Before the clause is executed for the
-first time, the value of the variable is undefined.
-
-%Also, regardless of where the driver clause
-%appears in the body, the driver variable is stepped at the top of the
-%loop; hence it is stylistically preferable, though
-%not required, to place driver clauses at the beginning of the \iter.
-
-Multiple drivers may appear in a single \iter\ form, in which case all
-of the driver variables are updated each time through the loop, in the
-order in which the clauses appear. The first driver to terminate will
-terminate the entire loop.
-
-In all cases, the value of the driver variable on exit from the loop,
-including within the epilogue code (see the |finally| clause), is
-undefined.
-
-All the parameters of a driver clause are evaluated once, before the
-loop begins. Hence it is not possible to change the bounds or other
-properties of an iteration by side-effect from within the loop.
-
-With one exception, driver clauses begin with the word |for| (or
-the synonym |as|) and mention an iteration variable, which is
-given a binding within the \iter\ form.
-The exception is |repeat|, which just executes a loop a
-specified number of times:
-
-\begin{clauses}
-
-\clausex{repeat}{~n~}
-Repeats the loop ~n~ times. For example:
-\begin{program}
-(iter (repeat 100)
- (print "I will not talk in class."))
-\end{program}
-\cpar If $n \leq 0$, the
-loop will never be executed. If ~n~ is not an integer, the
-actual number of executions will be $\lceil n \rceil$.
-
-\end{clauses}
-
-\pagebreak[3]
-
-\subsubsection{Numerical Iteration}
-
-\begin{clauses}
-\clausex{for}{~var~ |\&sequence|}
-The general form for iterating over a sequence of numbers requires a
-variable and, optionally, one or more keywords that provide the bounds
-and step size of the iteration. The |\&sequence|
-lambda-list keyword is a shorthand for these sequence keywords. They are:
-|from|, |upfrom|, |downfrom|, |to|, |downto|, |above|, |below| and |by|.
-|from| provides the starting value for ~var~
-and defaults to zero. |to| provides a final value and implies that the
-successive values of ~var~ will be increasing; |downto| implies that
-they will be decreasing. The loop terminates when ~var~ passes
-the final value (i.e. becomes smaller or larger than it, depending on
-the direction of iteration); in other words, the loop body
-will never be
-executed for values of ~var~ past the final value.
-|below| and |above| are similar to |to| and
-|downto|, except that the loop terminates when ~var~ equals or passes
-the final value.
-
-\cpar If no final value is specified, the variable will be stepped
-forever. Using |from| or |upfrom| will result in increasing
-values, while |downfrom| will give decreasing values.
-
-\cpar On each iteration,
-~var~ is incremented or decremented by the value of the sequence
-keyword |by|, which defaults to 1. It should always be a positive
-number, even for downward iterations.
-
-\cpar In the following examples, the sequence of numbers generated is shown
-next to the clause.
-
-\begin{program}
-(for i upfrom 0) \yields\ 0 1 2 \ldots
-(for i from 5) \yields\ 5 6 7 \ldots ; either from or upfrom is okay
-(for i downfrom 0) \yields\ 0 -1 -2 \ldots
-(for i from 1 to 3) \yields\ 1 2 3
-(for i from 1 below 3) \yields\ 1 2
-(for i from 1 to 3 by 2) \yields\ 1 3
-(for i from 1 below 3 by 2) \yields\ 1
-(for i from 5 downto 3) \yields\ 5 4 3
-\end{program}
-
-\end{clauses}
-
-\subsubsection{Sequence Iteration}
-
-There are a number of clauses for iterating over sequences. In all of
-them, the argument following |for| may be a list instead of a
-symbol, in which case destructuring is performed. See section
-\ref{destructuring}.
-
-\begin{clauses}
-
-\clause{|for| ~var~ |in| ~list~ \opt\ |by| ~step-function~}
-\clindexx{for}{in}
-~var~ is set to successive elements of list.
-~step-function,~ which
-defaults to |cdr|, is used to obtain the next sublist.
-
-\clause{|for| ~var~ |on| ~list~ \opt\ |by| ~step-function~}
-\clindexx{for}{on}
-~var~ is set to successive sublists of list.
-~step-function~ (default |cdr|) is used as in |for\dots in|.
-
-\end{clauses}
-
-\medskip
-
-These two clauses use |atom| to test for the end
-of a list. Hence, given a list whose final |cdr| is not \nil,
-they will silently ignore the last |cdr|. Other choices are
-|endp|, which would signal an error, and |null|, which
-would probably result in an error somewhere else. If you wish to use
-an end-test other than |atom|, set the variable
-|iterate::*list-end-test*|\lispindex{*list-end-test*} to the name of
-the desired function.
-
-\begin{clauses}
-\clause{|for| ~var~ |in-vector| ~vector~ |\&sequence|}
-\clindexx{for}{in-vector}
-~var~ takes on successive elements from ~vector.~ The vector's
-fill-pointer is observed. Here and in subsequent clauses, the |\&sequence|
-keywords include |with-index|, which takes a symbol as argument
-and uses it for the index variable instead of an internally generated
-symbol. The other |\&sequence| keywords behave as in numerical
-iteration, except that the default iteration bounds are the bounds of
-the vector. E.g. in |(for i in-vector v downto 3)|,
-|i| will start off being bound to the last element in |v|,
-and will
-be set to preceding elements down to and including the element with
-index 3.
-
-\clause{|for| ~var~ |in-sequence| ~seq~ |\&sequence|}
-\clindexx{for}{in-sequence}
-This uses Common Lisp's generalized sequence functions, |elt|
-and |length|, to obtain elements and determine the length of
-~seq.~ Hence it will work for any sequence, including lists, and will
-observe the fill-pointers of vectors.
-
-\clause{|for| ~var~ |in-string| ~string~ |\&sequence|}
-\clindexx{for}{in-string}
-~var~ is set to successive characters of ~string.~
-
-\startitem
-\Clause{|for| ~var~ |index-of-vector| ~vector~ |\&sequence|}
-\clindexx{for}{index-of-vector}
-\Clause{|for| ~var~ |index-of-sequence| ~sequence~ |\&sequence|}
-\clindexx{for}{index-of-sequence}
-\Clause{|for| ~var~ |index-of-string| ~string~ |\&sequence|}
-\clindexx{for}{index-of-string}
-\finishitem
-~var~ is set to successive indices of the sequence.
-These clauses avoid the overhead of accessing the sequence elements
-for those applications where they do not need to be examined, or are
-examined rarely. They admit all the optional keywords of the other
-sequence drivers except the (redundant) |with-index| keyword.
-
-\clause{|for| ~(key value)~ |in-hashtable| ~table~}
-\clindexx{for}{in-hashtable}
-
-~key~ and ~value,~ which must appear as shown in a list
-and may be destructuring templates, are set to the keys and values of
-~table~. If ~key~ is |nil|, then the hashtable's keys will be ignored;
-similarly for ~value~.
-The order in which
-elements of ~table~ will be retrieved is unpredictable.
-
-\clause{|for| ~var~ |in-package| ~package~ \opt\ |external-only| ~ext~}
-\clindexx{for}{in-package}
-Iterates over all the symbols in ~package,~ or over only the
-external symbols if ~ext~ is specified and non-|nil|. ~ext~ is not
-evaluated. The same symbol may appear more than once.
-
-\clause{|for| ~var~ |in-packages| ~packages~ \opt\ |having-access| ~symbol-types~}
-\clindexx{for}{in-packages}
-Iterates over all the symbols from the list of packages denoted by the
-descriptor ~packages~ and having accessibility (or visibility) given by
-~symbol-types~. This defaults to the list |(:external :internal :inherited)|
-and is not evaluated. ~var~ must be a list of up to three variables: in each
-iteration, these will be set to a symbol, its access-type and package (as per
-|with-package-iterator| in ANSI-CL). The same symbol may appear more than
-once.
-
-\end{clauses}
-
-\begin{clauses}
-
-\clause{|for| ~var~ |in-file| ~name~ \opt\ |using| ~reader~}
-\clindexx{for}{in-file}
-Opens the file ~name~ (which may be a string or pathname) for input,
-and iterates
-over its contents. ~reader~ defaults to |read|, so by default ~var~
-will be bound to the successive forms in the file. The \iter\ body is
-wrapped in an unwind-protect to ensure that the file is closed no
-matter how the \iter\ is exited.
-
-\clause{|for| ~var~ |in-stream| ~stream~ \opt\ |using| ~reader~}
-\clindexx{for}{in-stream}
-Like |for\dots in-file|, except that ~stream~ should be an existing
-stream object that supports input operations.
-
-\end{clauses}
-
-\subsubsection{Generalized Drivers}
-
-These are primarily useful for writing drivers that can also be used
-as generators (see section \ref{generators}, below).
-
-\begin{clauses}
-
-\clause{|for| ~var~ |next| ~expr~}
-\clindexx{for}{next}
-
-~var~ is set to ~expr~ each time through the loop. Destructuring is
-performed. When the clause is used as a generator, ~expr~ is the code
-that is executed when |(next ~var~)| is
-encountered (see section \ref{generators}, below).
-~expr~ should compute the first value for ~var~, as well
-as all subsequent values, and is responsible for terminating the loop.
-For compatibility with future versions of \iter, this termination
-should be done with |terminate|\clindex{terminate}, which can be
-considered a synonym for |finish| (see section \ref{control-flow}).
-
-\cpar As an example, the following clauses are equivalent to |(for
-i from 1 to 10)|:
-\begin{program}
-(initially (setq i 0))
-(for i next (if (> i 10) (terminate) (incf i)))
-\end{program}
-
-\clause{|for| ~var~ |do-next| ~form~}
-\clindexx{for}{do-next}
-~form~ is evaluated each time through the loop. Its value is ~not~
-set to ~var~; that is ~form's~ job. ~var~ is only present so that
-\iter\ knows it is a driver variable. \linebreak |(for ~var~ next
-~expr~)| is equivalent to |(for ~var~ do-next (dsetq ~var~ ~expr~))|.
-(See section \ref{destructuring} for an explanation of |dsetq|.)
-
-\end{clauses}
-
-\subsubsection{Generators}
-\label{generators}
-
-In all of the above clauses, the driver variable is updated on each
-iteration.
-Sometimes it is desirable to have greater control over updating.
-For instance, consider the problem of associating numbers, in
-increasing order and with no gaps, with the
-\nonnil\ elements of a list. One obvious first pass at writing this is:
-
-\begin{program}
-(iter (for el in list)
- (for i upfrom 1)
- (if el (collect (cons el i))))
-\end{program}
-But on the list |(a b nil c)| this produces |((a . 1) (b . 2) (c .
-4))| instead of the desired |((a . 1) (b . 2) (c . 3))|. The problem
-is that |i| is incremented each time through the loop, even when |el|
-is |nil|.
-
-The problem could be solved elegantly if we could step |i| only when
-we wished to. This
-can be accomplished for any \iter\ driver by writing |generate| (or
-its synonym |generating|)
-instead of |for|. Doing so produces a ~generator~---a driver whose
-values are yielded explicitly. To obtain the next value of a
-generator variable ~v~, write \linebreak |(next ~v~)|. The value of a |next|
-form is the next value of ~v~, as determined by its associated driver
-clause. |next| also has the side-effect of updating ~v~ to that
-value. If there is no next value, |next| will terminate the loop,
-just as with a normal driver.
-
-
-Using generators, we can now write our example like this:
-\begin{program}
-(iter (for el in list)
- (generate i upfrom 1)
- (if el (collect (cons el (next i)))))
-\end{program}
-Now |i| is updated only when |(next i)| is executed, and this occurs
-only when |el| is \nonnil.
-
-To better understand the relationship between ordinary drivers and
-generators, observe that we can rewrite an ordinary driver using its
-generator form immediately followed by |next|, as this example shows:
-\begin{program}
-(iter (generating i from 1 to 10)
- (next i)
- ...)
-\end{program}
-Provided that the loop body contains no |(next i)| forms, this will
-behave just as if we had written |(for i from 1 to 10)|.
-
-We can still refer to a driver variable ~v~ without using |next|; in
-this case, its value is that given to it by the last evaluation of
-|(next ~v~)|. Before |(next ~v~)| has been called the first time, the
-value of ~v~ is undefined.
-
-This semantics is more flexible than
-one in which ~v~ begins the loop bound to its first value and calls
-of |next| supply subsequent values, because it means the loop will not
-terminate too soon if the generator's sequence is empty. For
-instance, consider the following code, which tags \nonnil\ elements of
-a list using a list of tags, and also counts the null elements.
-(We assume there are at least as many tags as \nonnil\ elements.)
-\begin{program}
-(let* ((counter 0)
- (tagged-list (iter (for el in list)
- (generating tag in tag-list)
- (if (null el)
- (incf counter)
- (collect (cons el (next tag)))))))
- ...)
-\end{program}
-It may be that there are just as many tags as non-null elements of
-|list|. If all the elements of |list| are null, we still want the
-counting to proceed, even though |tag-list| is \nil. If |tag| had to be
-assigned its first value before the loop begins, we would have had to
-terminate the loop before the first iteration, since when |tag-list|
-is \nil, |tag|
-has no first value. With the existing semantics, however, |(next
-tag)| will never execute, so the iteration will cover all the elements of
-|list|.
-
-When the ``variable'' of a driver clause is actually a destructuring
-template containing several variables, all the variables are eligible
-for use with |next|. As before, |(next ~v~)| evaluates to ~v's~ next
-value; but the effect is to update all of the template's variables.
-For instance, the following code will return the list |(a 2 c)|.
-\begin{program}
-(iter (generating (key . item) in '((a . 1) (b . 2) (c . 3)))
- (collect (next key))
- (collect (next item)))
-\end{program}
-
-Only driver clauses with variables can be made into generators. This
-includes all clauses mentioned so far except for |repeat|. It does
-~not~ include |for\dots previous|, |for\dots =|,
-|for\dots initially\dots then| or |for\dots first\dots then| (see
-below).
-
-\subsubsection{Previous Values of Driver Variables}
-
-Often one would like to access the value of a variable on a previous
-iteration. \iter\ provides a special clause for accomplishing this.
-
-\begin{clauses}
-
-\clause{|for| ~pvar~ |previous| ~var~ \opt\ |initially| ~init~
-|back| ~n~}
-\clindexx{for}{previous}
-Sets ~pvar~ to the previous value of ~var,~ which should be a driver
-variable, a variable from another |for\dots previous| clause, or a
-variable established by a |for\dots =|,
-|for\dots initially\dots then| or |for\dots first\dots then| clause
-(see section \ref{setting}).
-Initially, ~pvar~ is given the value ~init~ (which defaults to \nil).
-The ~init~ expression will be moved outside the loop body, so it
-should not depend on anything computed within the loop.
-~pvar~ retains the value of ~init~ until ~var~ is set to its second
-value, at which point ~pvar~ is set to ~var's~ first value; and so on.
-
-\cpar The
-argument ~n~ to |back| must be a constant, positive integer, and
-defaults to 1. It determines how many iterations back ~pvar~ should
-track ~var~. For example, when ~n~ is 2, then ~pvar~ will be assigned
-~var's~ first value when ~var~ is set to its third value.
-
-\cpar A |for\dots previous| clause may occur after or before its
-associated driver clause. |for\dots previous| works with generators as
-well as ordinary drivers.
-
-\pagebreak[3]
-
-\cpar Example:
-\begin{program}
-(iter (for el in '(1 2 3 4))
- (for p-el previous el)
- (for pp-el previous p-el initially 0)
- (collect pp-el))
-\end{program}
-This evaluates to |(0 0 1 2)|. It could have been written more
-economically as
-\begin{program}
-(iter (for el in '(1 2 3 4))
- (for pp-el previous el back 2 initially 0)
- (collect pp-el))
-\end{program}
-
-
-\end{clauses}
-
-\subsection{Variable Binding and Setting}
-\label{setting}
-
-Several clauses exist for establishing new variable bindings or for
-setting variables in the loop. They all support destructuring.
-
-\begin{clauses}
-
-\clausex{with}{~var~ \opt\ |=| ~value~}
-Causes ~var~ to be bound to value before the loop body is entered.
-If ~value~ is not supplied, ~var~ assumes a default
-binding, which will be
-\nil\ in the absence of declarations. Also, if ~value~ is not
-supplied, no destructuring is performed; instead, ~var~ may be a list of
-symbols, all of which are given default
-bindings. If ~value~ is supplied, ~var~ is bound to it, with
-destructuring.
-
-\cpar Because |with|
-creates bindings whose scope includes the entire \iter\ form, it is
-good style to put all |with| clauses at the beginning.
-
-\cpar Successive occurrences of |with| result in sequential
-bindings (as with
-|let*|). There is no way to obtain parallel bindings; see
-section \ref{bindings} for a rationale.
-
-
-\clause{|for| ~var~ |=| ~expr~}
-\clindexx{for}{=}
-On each iteration, ~expr~ is evaluated and ~var~ is set
-to its value.
-
-\cpar This clause may appear to do the same thing as |for\dots next|.
-In fact, they are quite different. |for\dots =| provides only three
-services: it sets up a binding for ~var~, sets it to ~expr~ on each
-iteration, and makes it possible to use |for\dots previous| with
-~var~. |for\dots next| provides these services in addition to the
-ability to turn the driver into a generator.
-%Also, the code which sets ~var~ appears in the loop body in the same
-%place as the |for\dots =| clause; the code for |for\dots next| appears
-%at the top of the loop, as with other drivers (except when being used
-%as a generator).
-
-\clause{|for| ~var~ |initially| ~init-expr~ |then| ~then-expr~}
-\clindexxx{for}{initially}{then}
-Before the loop begins, ~var~ is set to ~init-expr;~ on all
-iterations after the first it is set to ~then-expr.~ This clause
-must occur at top-level. ~init-expr~ will be moved outside the loop
-body and ~then-expr~ will be moved to the end of the loop body, so
-they are subject to code motion problems (see section
-\ref{code-movement}).
-
-\cpar This clause may appear to be similar to |for\dots next|, but in
-fact they differ significantly. |for\dots initially\dots then| is
-typically used to give ~var~ its first value before the loop begins,
-and subsequent values on following iterations. This is incompatible
-with generators, whose first value and subsequent values must all be
-computed by |(next ~var~)|. Also, the update of ~var~ in
-|for\dots initially\dots then| does not occur at the location of the
-clause.
-Use |for\dots initially\dots then| for
-one-shot computations where its idiom is more convenient, but use
-|for\dots next| for extending \iter\ with new drivers (see section
-\ref{extend}).
-
-\clause{|for| ~var~ |first| ~first-expr~ |then| ~then-expr~}
-\clindexxx{for}{first}{then}
-The first time through the loop, ~var~ is set to ~first-expr;~ on
-subsequent iterations, it is set to ~then-expr.~ This differs from
-|for\dots initially| in that ~var~ is set to ~first-expr~
-inside the loop body,
-so ~first-expr~ may depend on the results of other clauses. For
-instance,
-\begin{program}
-(iter (for num in list)
- (for i first num then (1+ i))
- ...)
-\end{program}
-will set |i| to the first element of |list| on the first
-iteration, whereas
-\begin{program}
-(iter (for num in list)
- (for i initially num then (1+ i))
- ...)
-\end{program}
-is probably erroneous; |i| will be bound to |num|'s
-default binding (usually \nil) for the first iteration.
-
-\end{clauses}
-
-\begin{note}{Compatibility note}
-|loop|'s |for\dots =| works like \iter's, but |loop| used the syntax
-|for\dots =\dots then| to mean |for\dots initially\dots then|. It was
-felt that these two operations were sufficiently different to warrant
-different keywords.
-
-Also, the |for| in the above three clauses is misleading,
-since none is true driver (e.g. none has a corresponding |generate|
-form). |setting| would have been a better choice, but |for| was used
-to retain some compatibility with |loop|.
-\end{note}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Gathering Clauses}
-Many of \iter's clauses accumulate values into a variable, or set a
-variable under certain conditions. At the end of the loop, this
-variable contains the desired result. All these clauses have an
-optional |into| keyword, whose argument should be a symbol. If the
-|into| keyword is not supplied, the accumulation variable will be
-internally generated and its value will be returned at the end of the
-loop; if a variable is specified, that variable is used for the
-accumulation, and is not returned as a result---it is up to the user
-to return it explicitly, in the loop's epilogue code (see |finally|).
-It is safe to examine the accumulation variable during the loop, but
-it should not be modified.
-
-These clauses all begin with a verb. When the verb does
-not conflict with an existing Common Lisp function, then it may be
-used in either its infinitival or present-participle form (e.g. |sum|,
-|summing|). However, when there is a conflict with Common Lisp, only
-the present-participle form may be used (e.g. |unioning|). This is to
-prevent \iter\ clauses from clashing with Common Lisp
-functions.
-
-%although these clauses are described as ``producing a value,'' it is a
-%mistake to think of the lisp list representing the clause as a
-%value-producing form in the usual way. clauses may legally be written
-%where a value is expected, e.g. |(setq x (sum i))|, but the
-%lisp value of a clause in such a context is undefined.
-
-\subsubsection{Reductions}
-
-~Reduction~ is an extremely common iteration pattern in which
-the results of successive applications of a
-binary operation are accumulated.
-For example, a loop that computes the sum of the
-elements of a list is performing a reduction with the addition
-operation. This could be written in Common Lisp as |(reduce \#'+
-list)| or with \iter\ as
-\begin{program}
-(iter (for el in list)
- (sum el))
-\end{program}
-
-\begin{clauses}
-
-\clausex{sum}{~expr~ \opt\ |into| ~var~}
-Each time through the loop, ~expr~ is evaluated and added to a
-variable, which is bound initially to zero. If ~expr~ has a type,
-it is ~not~ used as the type of the sum variable, which is always
-|number|. To get the result variable to be of a more specific
-type, use an explicit variable, as in
-\begin{program}
-(iter (for el in number-list)
- (sum el into x)
- (declare (fixnum x))
- (finally (return x)))
-\end{program}
-
-\clausex{multiply}{~expr~ \opt\ |into| ~var~}
-Like |sum|, but the initial value of the result variable is $1$,
-and the variable is updated by multiplying ~expr~ into it.
-
-\clausex{counting}{~expr~ \opt\ |into| ~var~}
-~expr~ is evaluated on each iteration. If it is \nonnil, the
-accumulation variable, initially zero, is incremented.
-
-\startitem
-\Clausex{maximize}{~expr~ \opt\ |into| ~var~}
-\Clausex{minimize}{~expr~ \opt\ |into| ~var~}
-\finishitem
-~expr~ is evaluated on each iteration and its extremum (maximum or
-minimum) is stored in the accumulation variable. If ~expr~ is never
-evaluated, then the result is \nil\ (if the accumulation variable is
-untyped) or $0$ (if it has a numeric type).
-
-\clausex{reducing}{~expr~ |by| ~func~ \opt\ |initial-value| ~init-val~ |into| ~var~}
-This is a general way to perform reductions. ~func~ should be a
-function of two arguments, the first of which will be the value
-computed so far and
-the second of which will be the value of ~expr~. It should return the
-new value.
-|reducing| is roughly equivalent to the
-Common Lisp |(reduce ~func~ ~sequence~ :key ~expr-function~)|, where
-~expr-function~ is used to derive values from the successive elements
-of ~sequence~.
-
-\cpar If the |reducing| clause is never executed, the result is
-undefined.
-
-\cpar It is not necessary to provide an
-initial value, but better code can be generated if one is supplied.
-Regardless of its location in the \iter\ body, ~init-val~ will be
-evaluated before the loop is entered, so it should not depend on any
-value computed inside the \iter\ form.
-
-%\cpar if a ~var~ is not specified, you can get \iter\ to declare the
-%type of the internal variable by putting a |the| expression around
-%~func.~ see section \ref{types}.
-
-\end{clauses}
-
-%\begin{note}{implementation note}
-%in principle, |maximize| and |minimize| can be thought of
-%as reductions where the initial value is the smallest (or largest)
-%value that the accumulation variable can assume. because lisp's
-%bignums can represent arbitrary integers, these clauses cannot be
-%implemented as reductions in general. if, however, the type of
-%~expr~ or ~var~ can be determined to be a fixnum
-%or a float, \iter\ will implement the clause as a true reduction,
-%using one of the constants |most-negative-fixnum|, |%most-positive-fixnum|,
-%|most-negative-short-float|, etc. as appropriate.
-%\end{note}
-
-\subsubsection{Accumulations}
-
-All the predefined accumulation clauses add values to a sequence. If
-the sequence is a list, they all
-have the property that the partial list is kept in the correct order
-and available for inspection at any point in the loop.
-
-\begin{clauses}
-
-\clausex{collect}{~expr~ \opt\ |into| ~var~ |at| ~place~ |result-type| ~type~}
-Produces a sequence of the values of ~expr~ on each iteration. ~place~
-indicates where the next value of ~expr~ is added to the list and may
-be one of the symbols |start|, |beginning| (a synonym for |start|) or
-|end|. The symbol may be quoted, but need not be. The default is
-|end|. For example,
-\begin{program}
-(iter (for i from 1 to 5)
- (collect i))
-\end{program}
-produces |(1 2 3 4 5)|, whereas
-\begin{program}
-(iter (for i from 1 to 5)
- (collect i at beginning))
-\end{program}
-produces |(5 4 3 2 1)| (and is likely to be faster in most Common Lisp
-implementations).
-
-\cpar If ~type~ is provided, it should be a subtype of |sequence|.
-The default is |list|. Specifying a type other than |list| will
-result in |collect| returning a sequence of that type. ~However,~ the
-type of the sequence being constructed when inside the loop body is
-undefined when a non-|list| type is specified. (As with ~place~,
-quoting ~type~ is optional.)
-
-\clausex{adjoining}{~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~ |result-type| ~type~}
-Like |collect|, but only adds the value of ~expr~ if it is not
-already present. ~test,~ which defaults to |\#'eql|, is
-the test to be used with |member|.
-
-\startitem
-\Clausex{appending}{~expr~ \opt\ |into| ~var~ |at| ~place~}
-\Clausex{nconcing}{\ ~expr~ \opt\ |into| ~var~ |at| ~place~}
-\Clausex{unioning}{\ ~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~}
-\Clausex{nunioning}{~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~}
-\finishitem
-These are like |collect|, but behave like the Common Lisp functions
-|append|, |nconc|, |union| or |nunion|.
-As in Common Lisp, they work only on lists. Also as in Common Lisp,
-|unioning| and |nunioning| assume that the value of ~expr~ contains no
-duplicates.
-
-\clausex{accumulate}{~expr~ |by| ~func~ \opt\ |initial-value| ~init-val~ |into| ~var~}
-This is a general-purpose accumulation clause. ~func~ should be a
-function of two arguments, the value of ~expr~ and the value
-accumulated so far in the iteration, and it should return the updated
-value. If no initial value is supplied, \nil\ is used.
-
-%\cpar If a ~var~ is not specified, you can get \iter\ to declare the
-%type of the internal variable by putting a |the| expression around
-%~func.~ see section \ref{types}.
-
-\cpar The differences between |accumulate| and |reducing| are slight.
-One difference is that the functions take their arguments in a
-different order. Another is that in the absence of ~init-val~,
-|accumulate| will use \nil, whereas |reducing| will generate different
-code that avoids any dependence on the initial value.
-The reason for having both clauses is that one usually
-thinks of reductions (like |sum|) and accumulations (like |collect|)
-as different beasts.
-
-\end{clauses}
-
-
-\subsubsection{Finders}
-
-A ~finder~ is a clause whose value is an expression that meets some
-condition.
-
-\begin{clauses}
-
-\clause{|finding| ~expr~ |such-that| ~test~ \opt\ |into| ~var~ |on-failure| ~failure-value~}
-\clindexx{finding}{such-that}
-If ~test~ (which is an expression) ever evaluates to \nonnil, the loop
-is terminated, the
-epilogue code is run and the value of ~expr~ is returned. Otherwise,
-\nil\ (or ~failure-value,~ if provided) is returned. If ~var~ is
-provided, it will have either the \nonnil\ value of ~expr~ or
-~failure-value~ when the epilogue code is run.
-
-\cpar As a special case, if the ~test~ expression is a sharp-quoted
-function, then it is applied to ~expr~ instead of being simply
-evaluated. E.g. |(finding x such-that \#'evenp)| is equivalent to
-|(finding x such-that (evenp x))|.
-
-%\cpar although ~test~ need have nothing to do with ~%expr~ as in
-%|(finding j such-that (> i 3))|, it usually
-%will: |(finding (length el) such-that (oddp (length el)))|. to
-%avoid performing the |length| computation twice, you could write
-%|(finding (length el) such-that \#'oddp)| or |(finding (length
-%el) such-that 'oddp)|; for these cases, \iter\ generates code that
-%executes ~expr~ only once. the code for |\#'oddp|
-%is slightly different from that for {\lisp 'oddp}; see the discussion
-%under {\lisp for\dots in} and {\lisp for\dots on}.
-
-\cpar |On-failure| is a misnomer. Because it is always evaluated, it behaves
-more like the default third argument to the |gethash| function. As a result,
-|on-failure (error "Not found")| makes no sense. Instead, the clauses |leave|
-or |thereis| can be used in conjunction with |finally| as follows:
-\begin{program}
-(iter (for x in '(1 2 3))
- (if (evenp x) (leave x))
- (finally (error "not found")))
-\end{program}
-
-\cpar This clause may appear multiple times when all defaults are
-identical. It can also be used together with either |always|/|never| or
-|thereis| if their defaults match. More specifically, |on-failure nil| is
-compatible with |thereis|, while |on-failure t| is compatible with |always|
-and |never| clauses.
-\begin{program}
-(iter (for i in '(7 -4 2 -3))
- (if (plusp i)
- (finding i such-that (evenp i))
- (finding (- i) such-that (oddp i))))
-\end{program}
-
-\startitem
-\Clause{|finding| ~expr~ |maximizing| ~m-expr~ \opt\ |into| ~var~}
-\clindexx{finding}{maximizing}
-\Clause{|finding| ~expr~ |minimizing| ~m-expr~ \opt\ |into| ~var~}
-\clindexx{finding}{minimizing}
-\finishitem
-Computes the extremum (maximum or minimum) value of ~m-expr~ over all
-iterations, and returns the value of ~expr~ corresponding to the
-extremum. ~expr~ is evaluated inside the loop at the time the new
-extremum is established. If ~m-expr~ is never evaluated (due to, for
-example, being embedded in a conditional clause), then the returned
-value depends on the type, if any, of ~expr~ (or ~var,~ if
-one is supplied). If there is no type, the returned
-value will be \nil; if the type is numeric, the returned value will be
-zero.
-
-\cpar For these two clauses, ~var~ may be a list of two
-symbols; in that case, the first is used to record ~expr~ and
-the second, ~m-expr.~
-
-\cpar As with |finding\dots such-that|, if ~m-expr~ is a sharp-quoted
-function, then it is called on ~expr~ instead of being evaluated.
-
-\end{clauses}
-
-\subsubsection{Boolean Tests}
-
-\begin{clauses}
-
-\clausex{first-iteration-p}{}
-Returns |t| in the first cycle of the loop, otherwise \nil.
-
-\clausex{first-time-p}{}
-Returns |t| the first time the expression is evaluated, and then \nil\ forever.
-This clause comes handy when printing (optional) elements separated
-by a comma:
-
-\begin{program}
-(iter (for el in '(nil 1 2 nil 3))
- (when el
- (unless (first-time-p)
- (princ ", "))
- (princ el)))
-\end{program}
-produces |"1, 2, 3"|.
-
-\end{clauses}
-
-\subsubsection{Aggregated Boolean Tests}
-
-\begin{clauses}
-
-\clausex{always}{~expr~}
-If ~expr~ ever evaluates to
-\nil, then \nil\ is immediately returned; the epilogue code is not
-executed. If ~expr~ never evaluates to \nil, the epilogue code
-is executed and the last value of ~expr~ (or |t| if ~expr~ was never
-evaluated) is returned (whereas |loop| would constantly return |t|).
-
-% mention last evaluated clause when multiple always clauses?
-
-\clausex{never}{~expr~}
-Like |(always (not ~expr~))|, except it does not influence the last
-value returned by a possible other |always| clause. That is,
-\begin{program}
-(iter (repeat 2)
- (always 2)
- (never nil)) \yields 2 ; not t
-\end{program}
-
-\clausex{thereis}{~expr~}
-If ~expr~ is ever \nonnil,
-its value is immediately returned without running epilogue code.
-Otherwise, the epilogue code is performed and \nil\ is returned.
-
-This clause cannot be used together with |always| or |never|, because their
-defaults are opposed (similarly, |(loop always 3 thereis nil)| refuses to
-compile in some implementations of |loop|).
-
-\end{clauses}
-
-
-\subsection{Control Flow}
-\label{control-flow}
-Several clauses can be used to alter the usual flow of control in a loop.
-
-Note: the clauses of this and subsequent sections don't adhere to \iter's
-usual syntax, but instead use standard Common Lisp syntax. Hence the
-format for describing syntax subsequently is
-like the standard format used in the Common Lisp manual, not like the
-descriptions of clauses above.
-
-\begin{clauses}
-
-\clausex{finish}{}
-Stops the loop and runs the epilogue code.
-
-%for example:
-%
-%\begin{program}
-%(iter (with answer = nil)
-% (initially (make-a-mess))
-% (for i from 1 to 10)
-% (when (correct? i)
-% (setq answer i)
-% (finish))
-% (finally (cleanup)))
-%\end{program}
-%
-%this code will execute |cleanup| whether or not the test |(correct?
-%i)| ever succeeds.
-%the (more elegant) formulation,
-%\begin{program}
-%(iter (initially (make-a-mess))
-% (for i from 1 to 10)
-% (finding i such-that (correct? i))
-% (finally (cleanup)))
-%\end{program}
-%would not execute |cleanup| if |(correct? i)| succeeded; it
-%would do an immediate return.
-
-\clausex{leave}{\opt\ ~value~}
-Immediately returns ~value~ (default \nil) from the current \iter\
-form, skipping the epilogue code. Equivalent to using |return-from|.
-
-\clausex{next-iteration}{}
-Skips the remainder of the loop body and begins the next iteration of
-the loop.
-
-\clausex{while}{~expr~}
-If ~expr~ ever evaluates to \nil, the loop is terminated and the
-epilogue code executed. Equivalent to |(if (not ~expr~) (finish))|.
-
-\clausex{until}{~expr~}
-Equivalent to |(if ~expr~ (finish))|.
-
-\clausex{if-first-time}{~then~ \opt\ ~else~}
-If this clause is being executed for the first time in this invocation
-of the \iter\ form, then the ~then~ code is evaluated; otherwise the
-~else~ code is evaluated.
-
-\cpar |(for ~var~ first ~expr1~ then ~expr2~)| is almost equivalent to
-\begin{program}
-(if-first-time (dsetq ~var~ ~expr1~)
- (dsetq ~var~ ~expr2~))
-\end{program}
-The only difference is that the |for| version makes ~var~ available
-for use with |for\dots previous|.
-
-\end{clauses}
-
-\subsection{Code Placement}
-When fine control is desired over where code appears in a loop
-generated by \iter, the following special clauses may be useful.
-They are all subject to code-motion problems (see section
-\ref{code-movement}).
-
-\begin{clauses}
-
-\clausex{initially}{|\&rest| ~forms~}
-The lisp ~forms~ are placed in the prologue section of the loop, where
-they are executed once, before the loop body is entered.
-
-\clausex{after-each}{|\&rest| ~forms~}
-The ~forms~ are placed at the end of the loop body, where they
-are executed after each iteration. Unlike the other clauses in this
-section, ~forms~ may contain \iter\ clauses.
-
-\clausex{else}{|\&rest| ~forms~}
-The lisp ~forms~ are placed in the epilogue section of the loop, where they
-are executed if this |else| clause is never met during execution of the
-loop and the loop terminates normally.
-
-\clausex{finally}{|\&rest| ~forms~}
-The lisp ~forms~ are placed in the epilogue section of the loop, where
-they are executed after the loop has terminated normally.
-
-\clausex{finally-protected}{|\&rest| ~forms~}
-The lisp ~forms~ are placed in the second form of an unwind-protect
-outside the loop. They are always executed after the loop has
-terminated, regardless of how the termination occurred.
-
-\end{clauses}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Other Features}
-
-\subsection{Multiple Accumulations}
-\label{multiple}
-
-\begin{sloppypar}
-It is permitted to have more than one clause accumulate into the same
-variable, as in the following:
-\begin{program}
-(iter (for i from 1 to 10)
- (collect i into nums)
- (collect (sqrt i) into nums)
- (finally (return nums)))
-\end{program}
-Clauses can only accumulate into the same variable if they are
-compatible. |collect|, |adjoining|, |appending|, |nconcing|,
-|unioning| and |nunioning| are compatible with each other; |sum|,
-|multiply| and |counting| are compatible; |always| and |never| are compatible;
-|finding| \dots |such-that| is compatible with either |thereis| or |always|
-and |never| when their defaults match; and |maximize| and |minimize| clauses
-are compatible only with other |maximize| and |minimize| clauses,
-respectively.
-
-%note that the same variable ~cannot~ be both an accumulation
-%variable and an ordinary variable; there can be only one variable with
-%a given name within an \iter\ form.
-\end{sloppypar}
-
-\subsection{Named Blocks}
-
-Like Common Lisp |block|s, \iter\ forms can be given names. The
-name should be a single symbol, and it must be the first form in the
-\iter. The generated code behaves exactly like a named block; in
-particular, |(return-from ~name~)| can be used to exit it:
-\begin{program}
-(iter fred
- (for i from 1 to 10)
- (iter barney
- (for j from i to 10)
- (if (> (* i j) 17)
- (return-from fred j))))
-\end{program}
-An \iter\ form that is not given a name is implicitly named \nil.
-
-Sometimes one would like to write an expression in an inner \iter\ form,
-but have it processed by an outer \iter\ form. This is possible with
-the |in| clause.
-
-\begin{clauses}
-
-\clausex{in}{~name~ |\&rest| ~forms~}
-Evaluates ~forms~ as if they were part of the \iter\ form named
-~name~. In other words, \iter\ clauses are processed by the \iter\
-form named ~name,~ and not by any \iter\ forms that occur inside ~name.~
-
-\cpar As an example, consider the problem of collecting a list of the
-elements in a two-dimensional array. The naive solution,
-\begin{program}
-(iter (for i below (array-dimension ar 0))
- (iter (for j below (array-dimension ar 1))
- (collect (aref ar i j))))
-\end{program}
-\noindent is wrong because the list created by the inner \iter\ is simply
-ignored by the outer one. But using |in| we can write:
-\begin{program}
-(iter outer (for i below (array-dimension ar 0))
- (iter (for j below (array-dimension ar 1))
- (in outer (collect (aref ar i j)))))
-\end{program}
-\noindent which has the desired result.
-
-\end{clauses}
-
-\subsection{Destructuring}
-\label{destructuring}
-
-In many places within \iter\ clauses where a variable is expected, a
-list can be written instead. In these cases, the value to be assigned
-is ~destructured~ according to the pattern
-described by the list. As a simple example, the clause
-\begin{program}
-(for (key . item) in alist)
-\end{program}
-\noindent will result in |key| being set to the |car| of
-each element in |alist|, and |item| being set to the |cdr|. The
-pattern list may be nested to arbitrary depth, and (as the example
-shows) need not be terminated with \nil; the only requirement is that
-each leaf be a bindable symbol (or \nil, in which case no binding is
-generated for that piece of the structure).
-
-Sometimes, you might like to do the equivalent of a
-|multiple-value-setq| in a clause. This
-``multiple-value destructuring'' can be expressed by writing
-\linebreak |(values $pat_1$ $pat_2 \ldots$)| for a destructuring
-pattern, as in
-\begin{program}
-(for (values (a . b) c d) = (three-valued-function ...))
-\end{program}
-\begin{sloppypar}
-Note that the $pat_i$ can themselves be destructuring patterns (though
-not multiple-value destructuring patterns). You can't do multiple-value
-destructuring in a |with| clause; instead wrap the whole \iter\
-form in a |multiple-value-bind|.
-\end{sloppypar}
-
-\begin{note}{Rationale}
-There are subtle interactions between variable declarations and
-evaluation order that make the correct implementation of
-multiple-value destructuring in a |with| somewhat tricky.
-\end{note}
-
-The destructuring feature of \iter\ is available as a separate
-mechanism, using the |dsetq| macro:
-
-\begin{clauses}
-\defmacro{dsetq}{template expr}
-Performs destructuring of ~expr~ using ~template~. May be used
-outside of an \iter\ form. Yields the primary value of ~expr~.
-
-\end{clauses}
-
-\subsection{On-line Help}
-
-\begin{sloppypar}
-There is a limited facility for on-line help, in the form of the
-|display-iterate-clauses| function.
-\end{sloppypar}
-
-\begin{clauses}
-
-\defun{display-iterate-clauses}{\opt\ clause-spec}
-Displays a list of \iter\ clauses. If ~clause-spec~ is not
-provided, all clauses are shown; if it is a symbol, all clauses
-beginning with that symbol are shown; and if it is a list of symbols,
-all clauses for which ~clause-spec~ is a prefix are shown.
-
-\end{clauses}
-
-\subsection{Parallel Binding and Stepping}
-\label{bindings}
-
-The parallel binding and stepping of variables is a feature that
-\iter\ does ~not~ have. This section attempts to provide a rationale.
-
-We say that two variables are bound ~in parallel~ if neither
-binding shadows the other. This is the usual semantics of |let|
-(as opposed to |let*|). Similarly, we can say that iteration
-variables are stepped in parallel if neither variable is updated
-before the other, conceptually speaking; in other words, if the code
-to update each variable can reference the old values of both variables.
-
-|loop| allows parallel binding of variables and parallel stepping of
-driver variables. My view is that if you are depending on the
-serial/parallel distinction, you are doing something obscure. If you
-need to bind
-variables in parallel using |with|, then you must be using a
-variable name that shadows a name in the existing lexical environment.
-Don't do that. The most common use for parallel stepping is to track
-the values of variables on the previous iteration, but in fact this
-does not require parallel stepping at all; the following will work:
-\begin{program}
-(iter (for current in list)
- (for prev previous current)
- ...)
-\end{program}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Types and Declarations}
-\label{types}
-
-\subsection{Discussion}
-
-Sometimes efficiency dictates that the types of variables be declared.
-This type information needs to be communicated to \iter\ so it can
-bind variables to appropriate values. Furthermore, \iter\ must often
-generate internal variables invisible to the user; there needs to be a
-way for these to be declared.
-
-As an example, consider this code, which will return the number of
-odd elements in |number-list|:
-\begin{program}
-(iter (for el in number-list)
- (count (oddp el)))
-\end{program}
-In processing this form,
-\iter\ will create an internal variable, let us call it |list17|, to
-hold the successive |cdr|s of |number-list|, and
-will bind the variable to |number-list|. It will also generate a
-default binding for |el|; only inside the body of the loop will |el|
-be set to the |car| of |list17|. Finally, \iter\ will generate a
-variable, call it |result|, to hold the result of the count, and will
-bind it to zero.
-
-When dealing with type declarations, \iter\ observes one simple rule:
-~it will never generate a declaration unless requested to do so.~ The
-reason is that such declarations might mask errors in compiled code by
-avoiding error-checks; the resulting problems would be doubly hard to
-track down because the declarations would be hidden from the
-programmer. Of course, a compiler might omit error-checks even in the
-absence of declarations, though this behavior can usually be avoided,
-e.g. by saying |(declaim (optimize (safety 3)))|.
-
-So, the above \iter\ form will generate code with no declarations.
-But say we wish to declare the types of |el| and the internal
-variables |list17| and |result|. How is this done?
-
-Declaring the type of |el| is easy, since the programmer knows
-the variable's name:
-\begin{program}
-(iter (for el in number-list)
- (declare (fixnum el))
- (counting (oddp el)))
-\end{program}
-\iter\ can read variable type declarations like this one. Before
-processing any clauses, it scans the entire top-level form for type
-declarations
-and records the types, so that variable bindings can be performed
-correctly. In this case, |el| will be bound to zero
-instead of \nil. Also, \iter\ collects all the top-level declarations
-and puts them at the begining of the generated code, so it is not
-necessary to place all declarations at the beginning of an \iter\
-form; instead, they can be written near the variables whose types they
-declare.
-
-Since \iter\ is not part of the compiler, it will not know
-about declarations that occur outside an \iter\ form; these
-declarations must be repeated inside the form.
-
-Here is another way we could have declared the type of |el|:
-\begin{program}
-(iter (for (the fixnum el) in number-list)
- (counting (oddp el)))
-\end{program}
-\iter\ extends the Common Lisp |the|\lispindex{the}
-form to apply to variables as well as value-producing forms; anywhere
-a variable is allowed---in a |with| clause, as the iteration
-variable in a driver clause, as the |into| argument of an
-accumulation clause, even inside a destructuring template---you can
-write |(the ~type~ ~symbol~)| instead.
-
-There is one crucial difference between using a |the| form and
-actually declaring the variable: explicit declarations are always
-placed in the generated code, but type information from a |the|
-form is not turned into an actual declaration unless you tell \iter\
-to do so using |iterate:declare-variables|. See below.
-
-\begin{sloppypar}
-Declaring the types of internal variables is harder than declaring the
-types of explicitly mentioned variables, since their names
-are unknown. You do it by declaring |iterate:declare-variables|
-somewhere inside the top level of the \iter\ form. (This will also
-generate declarations for variables declared using |the|.)
-\iter\ does not provide much selectivity here: it's all or none.
-And unfortunately, since \iter\ is not privy to compiler information
-but instead reads declarations itself, it will not hear if you
-|(declaim (iterate:declare-variables))|. Instead, set the variable
-|iterate::*always-declare-variables*| to |t| at
-compile-time, using |eval-when|.
-\end{sloppypar}
-
-To determine the appropriate types for internal variables, \iter\ uses
-three sources of information:
-
-\begin{itemize}
-
-\item Often, the particular clause dictates a certain type for a
-variable; \iter\ will use this information when available. In the
-current example, the variable |list17| will be given the type
-|list|, since that is the only type that makes sense; and the
-variable |result| will be given the type |fixnum|, on the
-assumption that you will not be counting high enough to need bignums.
-You can override this assumption only by using and explicitly declaring a
-variable:
-\begin{verbatim}
-(iter (declare (iterate:declare-variables))
- (for el in number-list)
- (count (oddp el) into my-result)
- (declare (integer my-result))
- (finally (return my-result)))
-\end{verbatim}
-
-\begin{sloppypar}
-Other examples of the type assumptions that \iter\ makes are: type
-|list| for |into| variables of collection clauses; type |list| for
-expressions that are to be destructured; type |vector| for the
-variable holding the vector in a |for\dots in-vector| clause, and
-similarly for |string| and the |for\dots in-string| clause;
-and the implementation-dependent type
-|(type-of array-dimension-limit)| for the index and limit
-variables generated by sequence iteration drivers like |for\dots
-in-vector| and |for\dots in-string| (but not |for\dots in-sequence|,
-because it may be used to iterate over a list).
-\end{sloppypar}
-
-\item Sometimes, \iter\ will examine expressions and try to determine
-their types in a simple-minded way. If the expression is
-self-evaluating (like a number, for instance), \iter\ knows that the
-expression's type is the same as the type of the value it denotes, so
-it can use that type. If the expression is of the form |(the ~type~
-~expr~)|, \iter\ is smart enough to extract ~type~ and use it.
-However, the current version of \iter\ does not
-examine declarations of function result types or do any type
-inference. It will not determine, for
-example, that the type of |(+ 3 4)| is |fixnum|, or even
-|number|.
-
-\item In some cases, the type of an internal variable should match the
-type of some other variable. For instance, \iter\ generates an
-internal variable for |(f x)| in the
-clause |(for i from 1 to (f x))|, and in the absence of other
-information will give it the same type as |i|. If, however, the
-expression had been written |(the fixnum (f x))|, then \iter\
-would have given the internal variable the type |fixnum|
-regardless of |i|'s type. The type incompatibility errors that
-could arise in this situation are not checked for.
-
-\end{itemize}
-
-Note that if you do declare |iterate:declare-variables|, then
-\iter\ may declare user variables as well as internal ones if they do
-not already have declarations, though only for variables that it
-binds. For instance, in this code:
-
-\begin{program}
-(iter (declare (iterate:declare-variables))
- (for i from 1 to 10)
- (collect i into var))
-\end{program}
-the variable |var| will be declared to be of type |list|.
-
-
-\subsection{Summary}
-
-\iter\ understands standard Common Lisp variable type declarations
-that occur within an \iter\ form and
-will pass them through to the generated code. If the declaration
-|(iterate:declare-variables)|\lispindex{declare-variables}
-appears at the top level of an
-\iter\ form, or if
-|iterate::*always-declare-variables*|\lispindex{*always-declare-variables*}
-is \nonnil, then \iter\ will use the type information gleaned from user
-declarations, self-evaluating expressions and |the| expressions,
-combined with reasonable assumptions, to determine variable
-types and declare them.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Problems with Code Movement}
-\label{code-movement}
-
-Some \iter\ clauses, or parts of clauses, result in code being
-moved from the location of the clause to other parts of the loop.
-Drivers behave this way, as do code-placement clauses like |initially|
-and |finally|. When using these clauses, there is a danger of writing
-an expression that makes sense in its apparent location but will be
-invalid or have a different meaning in another location. For example:
-\begin{program}
-(iter (for i from 1 to 10)
- (let ((x 3))
- (initially (setq x 4))))
-\end{program}
-While it may appear that the |x| of |(initially (setq x 4))| is the
-same as the |x| of |(let ((x 3)) \dots|, in fact they are not:
-|initially| moves its code outside the loop body, so |x| would refer
-to a global variable. Here is another example of the same problem:
-\begin{program}
-(iter (for i from 1 to 10)
- (let ((x 3))
- (collect i into x)))
-\end{program}
-If this code were executed, |collect| would create a binding for its
-|x| at the top level of the \iter\ form that the |let| will shadow.
-
-Happily, \iter\ is smart enough to catch these errors; it
-walks all problematical code to ensure that free variables are not
-bound inside the loop body, and checks all variables it binds for the
-same problem.
-
-However, some errors cannot be caught:
-
-\begin{program}
-(iter (with x = 3)
- (for el in list)
- (setq x 1)
- (reducing el by \#'+ initial-value x))
-\end{program}
-|reducing| moves its |initial-value| argument to the initialization
-part of the loop in order to produce more efficient code. Since
-\iter\ does not perform data-flow analysis, it cannot determine that
-|x| is changed inside the loop; all it can establish is that |x| is
-not bound internally. Hence this code will not signal an
-error and will use $3$ as the initial value of the reduction.
-
-The following list summarizes all cases that are subject to these code
-motion and variable-shadowing problems.
-\begin{itemize}
-\item Any variable for which \iter\ creates a binding, including those
-used in |with| and the |into| keyword of many clauses.
-
-\begin{sloppypar}
-\item The special clauses which place code: |initially|, |after-each|, |else|,
-|finally| and |finally-protected|.
-\end{sloppypar}
-
-\item The variables of a |next| or |do-next| form.
-
-\item The |initially| arguments of |for\dots initially\dots then| and
-|for\dots previous|.
-
-\item The |then| argument of |for\dots initially\dots then|.
-
-\item The |initial-value| arguments of |reducing| and |accumulate|.
-
-\item The |on-failure| argument of |finding\dots such-that|.
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Differences Between {\tt Iterate} and {\tt Loop}}
-|loop| contains a great deal of complexity which \iter\ tries to
-avoid. Hence many esoteric features of |loop| don't exist in \iter.
-Other features have been carried over, but in a cleaned-up form.
-And of course, many new features have been added; they are not
-mentioned in this list.
-
-\begin{itemize}
-
-\item \iter's syntax is more Lisp-like than |loop|'s, having a higher
-density of parens.
-
-\item The current implementation of \iter, unlike the current version
-of |loop| (as documented in {\em Common Lisp, 2nd Ed.\/}), is
-extensible (see section \ref{extend}).
-
-\item |loop| puts the updates of all driver variables at the top of
-the loop; \iter\ leaves them where the driver clauses appear.
-
-\item While for the most part \iter\ clauses that resemble |loop| clauses
-behave similarly, there are some differences. For instance, there is
-no |for\dots =\dots then| in \iter; instead use
-|for\dots initially\dots then|.
-
-\item |loop| binds the variable |it| at certain times
-to allow pseudo-English expressions like |when ~expr~ return it|.
-In \iter, you must bind ~expr~ to a variable yourself. Note that
-|when ~expr~ return it| is like |thereis ~expr~| except that the latter is an
-accumulation clause and therefore competes with other accumulations
-(remember section \ref{multiple} above).
-
-% repeat different behaviour of |always| clause here?
-
-\item |loop| has a special |return| clause, illustrated in the
-previous item. \iter\ doesn't need one, since an ordinary Lisp
-|return| has the same effect.
-
-\item |loop| allows for parallel binding and stepping of iteration
-variables. \iter\ does not. (See section \ref{bindings}.)
-
-\item |loop| and \iter\ handle variable type declarations very
-differently. |loop| provides a special syntax for declaring variable
-types, and does not examine declarations. Moreover, the standard
-implementation of |loop| will
-generate declarations when none are requested.
-\iter\ parses standard Common Lisp type declarations, and will never
-declare a variable itself unless declarations are
-specifically requested.
-
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Rolling Your Own}
-\label{extend}
-
-\subsection{Introduction}
-
-\iter\ is extensible---you can write new clauses that embody new
-iteration patterns. You might want to write a new driver clause for a
-data structure of your own, or you might want to write a clause that
-collects or manipulates elements in a way not provided by \iter.
-
-This section describes how to write clauses for \iter. Writing a
-clause is like writing a macro. In fact, writing a clause ~is~
-writing a macro: since \iter\ code-walks its body and macroexpands,
-you can add new abstractions to \iter\ with good old |defmacro|.
-
-Actually, there are two extensions you can make to \iter\ that are
-even easier than writing a macro. They are adding a synonym for an
-existing clause and defining a driver clause for an indexable
-sequence. These can be done with |defsynonym| and
-|defclause-sequence|, respectively. See section \ref{aids}, below.
-
-The rest of this section explains how to write macros that expand into
-\iter\ clauses.
-Here's how you could add a simplified version of \iter's |multiply|
-clause, if \iter\ didn't already have one:
-\begin{program}
-(defmacro multiply (expr)
- `(reducing ,expr by \#'* initial-value 1))
-\end{program}
-
-If you found yourself summing the square of an expression often, you
-might want to write a macro for that. A first cut might be
-\begin{program}
-(defmacro sum-of-squares (expr)
- `(sum (* ,expr ,expr)))
-\end{program}
-but if you are an experienced macro writer, you will realize that this
-code will evaluate ~expr~ twice, which is probably a bad idea. A
-better version would use a temporary:
-\begin{program}
-(defmacro sum-of-squares (expr)
- (let ((temp (gensym)))
- `(let ((,temp ,expr))
- (sum (* ,temp ,temp)))))
-\end{program}
-Although this may seem complex, it is just the sort of thing you'd
-have to go through to write any macro, which illustrates the point of
-this section: if you can write macros, you can extend \iter.
-
-Our macros don't use \iter's keyword-argument
-syntax. We could just use keywords with |defmacro|, but we would
-still not be using \iter's clause indexing mechanism. Unlike Lisp,
-which uses just the first symbol of a form to determine what function
-to call, \iter\ individuates clauses by the list of required keywords.
-For instance, |for\dots in| and |for\dots in-vector| are different clauses
-implemented by distinct Lisp functions.
-
-To buy into this indexing scheme, as well as the keyword-argument
-syntax, use |defmacro-clause|:
-
-\begin{clauses}
-
-\defmacro{defmacro-clause}{arglist |\&body| body}
-Defines a new \iter\ clause. ~arglist~ is a list of symbols which are
-alternating keywords and arguments. \opt\ may be used, and the list
-may be terminated by |\&sequence|. ~body~ is an ordinary macro body,
-as with |defmacro|. If the first form of ~body~ is a string, it is
-considered a documentation string and will be shown by
-|display-iterate-clauses|. |defmacro-clause| will signal an error if
-defining the clause would result in an ambiguity. E.g. you cannot
-define the clause |for\dots from| because there would be no way to
-distinguish it from a use of the |for| clause with optional keyword |from|.
-
-\end{clauses}
-
-\medskip
-
-Here is |multiply| using |defmacro-clause|. The keywords are capitalized
-for readability.
-\begin{program}
-(defmacro-clause (MULTIPLY expr \opt\ INTO var)
- `(reducing ,expr by \#'* into ,var initial-value 1))
-\end{program}
-You don't have to worry about the case when |var| is not supplied; for
-any clause with an |into| keyword, saying |into nil| is equivalent to
-omitting the |into| entirely.
-
-As another, more extended example, consider the fairly common
-iteration pattern that
-involves finding the sequence element that maximizes (or minimizes) some
-function. \iter\ provides this as |finding\dots maximizing|, but it's
-instructive to see how to write it.
-Here, in pseudocode, is how you might write such a loop for
-maximizing a function F:
-
-\begin{quote}
-\begin{tabbing}
-set variable MAX-VAL to NIL; \\
-set variable WINNER to NIL; \\
-for\=\ each element EL in the sequence \\
-\> if\=\ MAX-VAL\=\ is NIL or F(EL) $>$ MAX-VAL then \\
-\>\> set MAX-VAL to F(EL); \\
-\>\> set WINNER to EL; \\
-\> end if; \\
-end for; \\
-return WINNER.
-\end{tabbing}
-\end{quote}
-
-Here is the macro:
-\begin{program}
-(defmacro-clause (FINDING expr MAXIMIZING func \opt\ INTO var)
- (let ((max-val (gensym))
- (temp1 (gensym))
- (temp2 (gensym))
- (winner (or var iterate::*result-var*)))
- `(progn
- (with ,max-val = nil)
- (with ,winner = nil)
- (cond
- ((null ,max-val)
- (setq ,winner ,expr)
- (setq ,max-val (funcall ,func ,winner))
- (t
- (let* ((,temp1 ,expr)
- (,temp2 (funcall ,func ,temp1)))
- (when (> ,temp2 ,max-val)
- (setq ,max-val ,temp2)
- (setq ,winner ,temp1))))))
- (finally (leave ,winner)))))
-\end{program}
-Note that if no |into| variable is supplied, we use
-|iterate::*result-var*|, which contains the internal variable into
-which all clauses place their results. If this variable is bound by
-some clause, then \iter\ will return its value automatically;
-otherwise, \nil\ will be returned.
-
-\subsection{Writing Drivers}
-
-In principle, drivers can be implemented just as easily as other
-\iter\ clauses. In practice, they are a little harder to get right.
-As an example, consider writing a driver that
-iterates over all the
-elements of a vector, ignoring its fill-pointer. |for\dots in-vector|
-won't work for this, because it observes the fill-pointer. It's necessary to
-use |array-dimension| instead of |length| to obtain the size of the
-vector. Here is one approach:
-
-\begin{program}
-(defmacro-clause (FOR var IN-WHOLE-VECTOR v)
- "All the elements of a vector (disregards fill-pointer)"
- (let ((vect (gensym))
- (index (gensym)))
- `(progn
- (with ,vect = ,v)
- (for ,index from 0 below (array-dimension ,vect 0))
- (for ,var = (aref ,vect ,index)))))
-\end{program}
-Note that we immediately put |v| in a variable, in case it is an
-expression. Again, this is just good Lisp macrology. It also has a
-subtle effect on the semantics of the driver: |v| is evaluated only
-once, at the beginning of the loop, so changes to |v| in the loop have
-no effect on the driver. Similarly, the bounds for numerical iteration
-e.g. the above |array-dimension| are also evaluated once only. This is how
-all of \iter's drivers work.
-
-
-There is an important point concerning the |progn| in this code. We
-need the |progn|, of course, because we are returning several forms,
-one of which is a driver. But \iter\ drivers must occur at top-level.
-Is this code in error? No, because ~top-level~ is defined in \iter\
-to include forms inside a |progn|. This is just the definition of
-top-level that Common Lisp uses, and for the same reason: to allow
-macros to return multiple forms at top-level.
-
-While our |for\dots in-whole-vector| clause will work, it is not
-ideal. In particular, it does not support generating. Do do so, we
-need to use |for\dots next| or |for\dots do-next|. The job is
-simplified by the |defmacro-driver| macro.
-
-\begin{clauses}
-
-\defmacro{defmacro-driver}{arglist |\&body| body}
-Defines a driver clause in
-both the |for| and |generate| forms, and provides a parameter
-|generate| which ~body~ can examine to determine how it was invoked.
-~arglist~ is as in |defmacro-clause|, and should begin with the symbol
-|for|.
-
-\end{clauses}
-
-With |defmacro-driver|, our driver looks like this:
-\begin{program}
-(defmacro-driver (FOR var IN-WHOLE-VECTOR v)
- "All the elements of a vector (disregards fill-pointer)"
- (let ((vect (gensym))
- (end (gensym))
- (index (gensym))
- (kwd (if generate 'generate 'for)))
- `(progn
- (with ,vect = ,v)
- (with ,end = (array-dimension ,vect 0))
- (with ,index = -1)
- (,kwd ,var next (progn (incf ,index)
- (if (>= ,index ,end) (terminate))
- (aref ,vect ,index))))))
-\end{program}
-
-
-We are still missing one thing: the |\&sequence| keywords.
-We can get them easily enough, by writing
-\begin{program}
-(defmacro-driver (FOR var IN-WHOLE-VECTOR v \&sequence)
- ...)
-\end{program}
-We can now refer to parameters |from|, |to|, |by|, etc. which contain
-either the values for the corresponding keyword, or \nil\ if the
-keyword was not supplied. Implementing the right code for these
-keywords is cumbersome but not difficult; it is left as an exercise.
-But before you begin, see |defclause-sequence| below for an easier way.
-
-\subsection{Extensibility Aids}
-\label{aids}
-
-This section documents assorted features that may be of use in
-extending \iter.
-
-\begin{clauses}
-
-\defunexpvar{*result-var*}
-Holds the variable that is used to return a value as a result of the
-\iter\ form. You may examine this and use it in a |with| clause, but
-you should not change it.
-
-\defmacro{defsynonym}{syn word}
- Makes ~syn~ a synonym for the existing \iter\ keyword ~word.~ Only
-the first word in each clause can have synonyms.
-
-\defmacroxx{defclause-sequence}{element-name index-name}{|\&key|
-access-fn size-fn sequence-type}{element-type
-element-doc-string index-doc-string}
-Provides
-a simple way to define sequence clauses. Generates two
-clauses, one for iterating over the sequence's elements, the other
-for iterating over its indices. The first symbol of both
-clauses will have print-name |for|.
-~element-name~ and ~index-name~ should be symbols.
-~element-name~ is the second keyword of the element iterator (typically of
-the form
-|in-~sequence-type~|), and ~index-name~ is the second keyword
-of the index-iterator (typically of the form
-|index-of-~sequence-type~|). Either name may be
-\nil, in which case the corresponding clause is not defined. If both
-symbols are supplied, they should be in the same package. The |for|
-that begins the clauses will be in this package.
-
-\cpar ~access-fn~ is the function to be used to
-access elements of the sequence in the element iterator. The function
-should take two
-arguments, a sequence and an index, and return the appropriate element.
-~size-fn~ should denote a function of one argument, a sequence, that
-returns its size. Both ~access-fn~ and ~size-fn~ are required for the
-element iterator, but only ~size-fn~ is needed for the index iterator.
-
-\cpar The ~sequence-type~ and ~element-type~ keywords are used to
-suggest types for the variables
-used to hold the sequence and the
-sequence elements, respectively. The usual rules about \iter's
-treatment of variable type declarations apply (see section \ref{types}).
-
-\cpar ~element-doc-string~ and ~index-doc-string~ are
-the documentation strings, for use with |display-iterate-clauses|.
-
-\cpar The generated element-iterator performs destructuring on the
-element variable.
-
-\cpar As an example, the above |for\dots in-whole-vector| example
-could have been written:
-\begin{program}
-(defclause-sequence IN-WHOLE-VECTOR INDEX-OF-WHOLE-VECTOR
- :access-fn 'aref
- :size-fn \#'(lambda (v) (array-dimension v 0))
- :sequence-type 'vector
- :element-type t
- :element-doc-string
- "Elements of a vector, disregarding fill-pointer"
- :index-doc-string
- "Indices of vector, disregarding fill-pointer")
-\end{program}
-
-\end{clauses}
-
-\subsection{Subtleties}
-
-There are some subtleties to be aware of when writing \iter\ clauses.
-First, the code returned by your macros may be |nconc|'ed into a list,
-so you should always returned freshly consed lists, rather than
-constants. Second, \iter\ matches clauses by using |eq| on the first
-symbol and |string=| on the subsequent ones, so the package of the
-first symbol of a clause is relevant. All of the clauses in this manual
-have their first word in the \iter\ package.
-You can use the package system in the usual way to shadow
-\iter\ clauses without replacing them.
-
-%%% say more here, about the badness that only the first word of a
-%%% clause is packagey.
-
-\section{Non-portable Extensions to Iterate (Contribs)}
-\label{contribs}
-
-Currently, there is only one non-portable extension to iterate in the
-distribution: iterate-pg. If you have made an extension that depends
-on non-portable features, feel free to send them to |asf@boinkor.net|
-for inclusion in the iterate distribution.
-
-\subsection{An SQL query driver for iterate}
-
-The pg package by Eric Marsden (see |http://cliki.net/pg|) provides an
-interface to the PostgreSQL database. Using the \iterpg\ extension, it
-is possible to handle the results of SQL queries using \iter.
-
-This usage example should give you an idea of how to use it:
-
-\begin{program}
-(pg:with-pg-connection (c "somedb" "someuser")
- (iter (for (impl version date) in-relation "select * from version"
- on-connection *dbconn*)
- (collect version)))
-\end{program}
-
-To use the extension via |ASDF|, simply make your system depend on the
-|iterate-pg| system instead of the |iterate| system. To load it
-manually, use:
-
-\begin{program}
- (asdf:oos 'asdf:load-op :iterate-pg)
-\end{program}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Obtaining {\tt Iterate}}
-
-\begin{sloppypar}
-The information in this chapter is obsolete but included for
-completeness's sake; Currently, the most up-to-date information on
-\iter\ can be found at |http://boinkor.net/iterate.html|.
-\end{sloppypar}
-
-\begin{sloppypar}
-\iter\ currently runs on Lisp Machines, and on
-HP's, Sun3's and Sparcstations under Lucid.
-\iter\ source and binaries are available at the MIT AI Lab in the
-subdirectories of |/src/local/lisplib/|. The source file,
-|iterate.lisp|, is also available for anonymous FTP in the directory
-|/com/fpt/pub/| on the machine |TRIX.AI.MIT.EDU| (Internet number
-128.52.32.6). If you are unable to obtain |iterate| in one of these
-ways, send mail to |jba@ai.mit.edu| and I will send you the source
-file.
-\end{sloppypar}
-
-\begin{sloppypar}
-\iter\ resides in the |iterate| package (nickname |iter|). Just say
-\linebreak |(use-package :iterate)| to make all the necessary symbols
-available.
-If a symbol is not exported, it appears in this manual with an
-``|iterate::|'' prefix.
-\end{sloppypar}
-
-Send bug reports to |bug-iterate@ai.mit.edu|. The |info-iterate|
-mailing list will have notices of changes and problems; to have
-yourself added, send mail to |info-iterate-request@ai.mit.edu|.
-
-
-\medskip
-
-\begin{flushleft}
- \bf Acknowledgements
-\end{flushleft}
-\smallskip
-
-Richard Waters provided invaluable criticism which spurred me to improve
-\iter\ greatly. As early users, David Clemens, Oren Etzioni and Jeff
-Siskind helped ferret out many bugs.
-
-%\begin{theindex}
-% The index files must be generated with the genindex program
-% or from makeindex iterate-manual.idx which creates iterate-manual.ind.
-
-%\baselineskip\normalbaselineskip
-%\advance\baselineskip by -2pt
-
-\input{iterate-manual.ind}
-
-%\underline{Clauses}
-%\input{iterate-manual.clindex}
-%
-%\indexspace
-%\underline{Lisp}
-%\input{iterate-manual.lispindex}
-
-%\end{theindex}
-
-
-\end{document}
-
-
-% arch-tag: "c0f871a6-313c-11d8-abb9-000c76244c24"
diff -rN -u old-iterate/doc/iterate.texinfo new-iterate/doc/iterate.texinfo
--- old-iterate/doc/iterate.texinfo 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/iterate.texinfo 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,2657 @@
+\input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*-
+@c %**start of header
+@setfilename iterate.info
+@settitle The Iterate Manual
+@exampleindent 2
+
+@c @documentencoding utf-8
+
+@macro iter {}
+@code{iterate}
+@end macro
+
+@macro mathx {tex, non-tex}
+@iftex
+@math{\tex\}
+@end iftex
+@ifnottex
+@emph{\non-tex\}
+@end ifnottex
+@end macro
+
+@macro impnote {text}
+@quotation
+@strong{Implementor's note:} @emph{\text\}
+@end quotation
+@end macro
+
+@c Set ROMANCOMMENTS to get comments in roman font.
+@ifset ROMANCOMMENTS
+@alias lispcmt = r
+@end ifset
+@ifclear ROMANCOMMENTS
+@alias lispcmt = asis
+@end ifclear
+
+@c Index for iterate clauses.
+@defindex it
+
+@macro clauseu {name1}
+@itindex \name1\
+@c
+@end macro
+
+@macro claused {name1, name2}
+@itindex \name1\@dots{}\name2\
+@c
+@end macro
+
+@macro clauset {name1, name2, name3}
+@itindex \name1\@dots{}\name2\@dots{}\name3\
+@c
+@end macro
+
+@macro k {what}
+@code{\what\}
+@end macro
+
+@iftex
+@alias v = asis
+@alias cl = code
+@end iftex
+
+@ifnottex
+@alias v = var
+@alias cl = strong
+@end ifnottex
+
+@c Show variables, clauses, and concepts in the same index.
+@syncodeindex it cp
+@syncodeindex vr cp
+
+@copying
+Copyright @copyright{} 1989 Jonathan Amsterdam <jba at ai.mit.edu> @*
+@c Copyright @copyright{} 2006 Lu@'{@dotless{i}}s Oliveira
+@c <loliveira at common-lisp.net> @*
+
+@quotation
+The present manual is an adaptation of Jonathan Amsterdam's ``The
+Iterate Manual'', @acronym{MIT} @acronym{AI} Memo No. 1236. Said memo
+mentioned the following contract information:
+
+@emph{This report describes research done at the Artificial
+Intelligence Laboratory of the Massachusetts Institute of Technology.
+Support for the laboratory's artificial intelligence research is
+provided in part by the Advanced Research Projects Agency of the
+Department of Defense under Office of Naval Research contract
+N00014-85-K-0124.}
+@end quotation
+@end copying
+@c %**end of header
+
+@titlepage
+@title The Iterate Manual
+@c @subtitle Version X.X
+@c @author Jonathan Amsterdam
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top iterate
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Clauses::
+* Other Features::
+* Types and Declarations::
+* Problems with Code Movement::
+* Differences Between Iterate and Loop::
+* Rolling Your Own::
+* Non-portable Extensions to Iterate (Contribs)::
+* Obtaining Iterate::
+* Acknowledgements::
+* Don't Loop Iterate::
+* Comprehensive Index::
+@end menu
+
+@c ===================================================================
+@node Introduction
+@chapter Introduction
+
+This manual describes @iter{}, a powerful iteration facility for
+Common Lisp. @iter{} provides abstractions for many common iteration
+patterns and allows for the definition of additional patterns.
+@iter{} is a macro that expands into ordinary Lisp at compile-time, so
+it is more efficient than higher-order functions like @code{map} and
+@code{reduce}. While it is similar to @code{loop}, @iter{} offers a
+more Lisp-like syntax and enhanced extensibility. (For a more
+complete comparison of @iter{} with other iteration constructs, see
+@acronym{MIT} @acronym{AI} Lab Working Paper No. 324, @emph{Don't
+Loop, Iterate.} also included in this manual in @ref{Don't Loop
+Iterate}.)
+
+An @iter{} form consists of the symbol @code{iter}@footnote{You can
+also use @code{iterate}, but @code{iter} is preferred because it
+avoids potential conflicts with possible future additions to Common
+Lisp, and because it saves horizontal space when writing code.}
+followed by one or more forms, some of which may be @iter{}
+@emph{clauses}. Here is a simple example of @iter{} which collects
+the numbers from 1 to 10 into a list, and returns the list. The
+return value is shown following the arrow.
+
+@lisp
+(iter (for i from 1 to 10)
+ (collect i)) @result{} (1 2 3 4 5 6 7 8 9 10)
+@end lisp
+
+This form contains two clauses: a @code{for} clause that steps the
+variable @code{i} over the integers from 1 to 10, and a @code{collect}
+clause that accumulates its argument into a list. With a few
+exceptions, all @iter{} clauses have the same format: alternating
+symbols (called @emph{keywords}) and expressions (called
+@emph{arguments}). The syntax and terminology are those of Common
+Lisp's keyword lambda lists. One difference is that @iter{}'s keywords
+do not have to begin with a colon---though they may, except for the
+first symbol of a clause. So you can also write @code{(for i :from 1
+:to 10)} if you prefer.
+
+Any Lisp form can appear in the body of an @iter{}, where it will have
+its usual meaning. @iter{} walks the entire body, expanding macros,
+and recognizing clauses at any level. This example collects all the
+odd numbers in a list:
+
+@lisp
+(iter (for el in list)
+ (if (and (numberp el) (oddp el))
+ (collect el)))
+@end lisp
+
+There are clauses for iterating over numbers, lists, arrays and other
+objects, and for collecting, summing, counting, maximizing and other
+useful operations. @iter{} also supports the creation of new variable
+bindings, stepping over multiple sequences at once, destructuring, and
+compiler declarations of variable types. The following example
+illustrates some of these features:
+
+@lisp
+(iter (for (key . item) in alist)
+ (for i from 0)
+ (declare (fixnum i))
+ (collect (cons i key)))
+@end lisp
+
+This loop takes the keys of an alist and returns a new alist
+associating the keys with their positions in the original list. The
+compiler declaration for @code{i} will appear in the generated code in
+the appropriate place.
+
+@c ===================================================================
+@node Clauses
+@chapter Clauses
+
+Most of @iter{}'s clauses will be familiar to @code{loop} programmers.
+(@code{loop} is an iteration macro that has been incorporated into
+Common Lisp. See Guy Steele's @emph{Common Lisp, 2nd Edition}.) In
+nearly all cases they behave the same as their @code{loop}
+counterparts, so a @code{loop} user can switch to @iter{} with little
+pain (and much gain).
+
+All clauses with the standard keyword-argument syntax consist of two
+parts: a @emph{required} part, containing keywords that must be present and
+in the right order; and an @emph{optional} part, containing keywords that
+may be omitted and, if present, may occur in any order. In the
+descriptions below, the parts are separated by the Lisp lambda-list
+keyword @code{&optional}.
+
+@menu
+* Drivers::
+* Variable Binding and Setting::
+* Gathering Clauses::
+* Control Flow::
+* Code Placement::
+@end menu
+
+@c ===================================================================
+@node Drivers
+@section Drivers
+
+An iteration-driving clause conceptually causes the iteration to go
+forward. Driver clauses in @iter{} allow iteration over numbers,
+lists, vectors, hashtables, packages, files and streams.
+Iteration-driving clauses must appear at the top level of an @iter{}
+form; they cannot be nested inside another clause. The driver
+variable is updated at the point where the driver clause occurs.
+Before the clause is executed for the first time, the value of the
+variable is undefined.
+
+@c Also, regardless of where the driver clause appears in the body,
+@c the driver variable is stepped at the top of the loop; hence it is
+@c stylistically preferable, though not required, to place driver
+@c clauses at the beginning of the @iter{}.
+
+Multiple drivers may appear in a single @iter{} form, in which case all
+of the driver variables are updated each time through the loop, in the
+order in which the clauses appear. The first driver to terminate will
+terminate the entire loop.
+
+In all cases, the value of the driver variable on exit from the loop,
+including within the epilogue code (see the @code{finally} clause), is
+undefined.
+
+All the parameters of a driver clause are evaluated once, before the
+loop begins. Hence it is not possible to change the bounds or other
+properties of an iteration by side-effect from within the loop.
+
+With one exception, driver clauses begin with the word @code{for} (or
+the synonym @code{as}) and mention an iteration variable, which is
+given a binding within the @iter{} form. The exception is
+@code{repeat}, which just executes a loop a specified number of times:
+
+@clauseu{repeat}
+@deffn Clause repeat @v{n}
+
+Repeat the loop @var{n} times. For example:
+
+@lisp
+(iter (repeat 100)
+ (print "I will not talk in class."))
+@end lisp
+
+If @mathx{n \leq 0, n <= 0}, then loop will never be executed. If @var{n} is
+not an integer, the actual number of executions will be @mathx{\lceil n
+\rceil, ceil(n)}.
+@end deffn
+
+@menu
+* Numerical Iteration::
+* Sequence Iteration::
+* Generalized Drivers::
+* Generators::
+* Previous Values of Driver Variables::
+@end menu
+
+@c ===================================================================
+@node Numerical Iteration
+@subsection Numerical Iteration
+
+@clauseu{for}
+@deffn Clause for @v{var} @k{&sequence}
+
+The general form for iterating over a sequence of numbers requires a
+variable and, optionally, one or more keywords that provide the bounds
+and step size of the iteration. The @code{&sequence} lambda-list
+keyword is a shorthand for these sequence keywords. They are:
+@code{from}, @code{upfrom}, @code{downfrom}, @code{to}, @code{downto},
+@code{above}, @code{below} and @code{by}. @code{from} provides the
+starting value for @var{var} and defaults to zero. @code{to} provides
+a final value and implies that the successive values of @var{var} will
+be increasing; @code{downto} implies that they will be decreasing.
+The loop terminates when @var{var} passes the final value
+(i.e. becomes smaller or larger than it, depending on the direction of
+iteration); in other words, the loop body will never be executed for
+values of @var{var} past the final value. @code{below} and
+@code{above} are similar to @code{to} and @code{downto}, except that
+the loop terminates when @var{var} equals or passes the final value.
+
+If no final value is specified, the variable will be stepped forever.
+Using @code{from} or @code{upfrom} will result in increasing values,
+while @code{downfrom} will give decreasing values.
+
+On each iteration, @var{var} is incremented or decremented by the
+value of the sequence keyword @code{by}, which defaults to 1. It
+should always be a positive number, even for downward iterations.
+
+In the following examples, the sequence of numbers generated is shown
+next to the clause.
+
+@lisp
+(for i upfrom 0) @result{} 0 1 2 @dots{}
+(for i from 5) @result{} 5 6 7 @dots{} ; either from or upfrom is okay
+(for i downfrom 0) @result{} 0 -1 -2 @dots{}
+(for i from 1 to 3) @result{} 1 2 3
+(for i from 1 below 3) @result{} 1 2
+(for i from 1 to 3 by 2) @result{} 1 3
+(for i from 1 below 3 by 2) @result{} 1
+(for i from 5 downto 3) @result{} 5 4 3
+@end lisp
+@end deffn
+
+@c ===================================================================
+@node Sequence Iteration
+@subsection Sequence Iteration
+
+There are a number of clauses for iterating over sequences. In all of
+them, the argument following @code{for} may be a list instead of a
+symbol, in which case destructuring is performed. See
+@ref{Destructuring}.
+
+@claused{for, in}
+@deffn Clause for @v{var} @cl{in} @v{list} @k{&optional} @k{by} @v{step-function}
+
+@var{var} is set to successive elements of list. @var{step-function},
+which defaults to @code{cdr}, is used to obtain the next sublist.
+@end deffn
+
+@claused{for, on}
+@deffn Clause for @v{var} @cl{on} @v{list} @k{&optional} @k{by} @v{step-function}
+
+@var{var} is set to successive sublists of list. @var{step-function}
+(default @code{cdr}) is used as in @code{for@dots{} in}.
+@end deffn
+
+@vindex *list-end-test*
+These two clauses use @code{atom} to test for the end of a list.
+Hence, given a list whose final @code{cdr} is not @code{nil}, they
+will silently ignore the last @code{cdr}. Other choices are
+@code{endp}, which would signal an error, and @code{null}, which would
+probably result in an error somewhere else. If you wish to use an
+end-test other than @code{atom}, set the variable
+@code{iterate::*list-end-test*} to the name of the desired function.
+
+@claused{for, in-vector}
+@deffn Clause for @v{var} @cl{in-vector} @v{vector} @k{&sequence}
+
+@var{var} takes on successive elements from @var{vector}. The vector's
+fill-pointer is observed. Here and in subsequent clauses, the
+@code{&sequence} keywords include @code{with-index}, which takes a
+symbol as argument and uses it for the index variable instead of an
+internally generated symbol. The other @code{&sequence} keywords
+behave as in numerical iteration, except that the default iteration
+bounds are the bounds of the vector. E.g. in @code{(for i in-vector v
+downto 3)}, @code{i} will start off being bound to the last element in
+@code{v}, and will be set to preceding elements down to and including
+the element with index 3.
+@end deffn
+
+@claused{for, in-sequence}
+@deffn Clause for @v{var} @cl{in-sequence} @v{seq} @k{&sequence}
+
+This uses Common Lisp's generalized sequence functions, @code{elt} and
+@code{length}, to obtain elements and determine the length of
+@var{seq}. Hence it will work for any sequence, including lists, and
+will observe the fill-pointers of vectors.
+@end deffn
+
+@claused{for, in-string}
+@deffn Clause for @v{var} @cl{in-string} @v{string} @k{&sequence}
+
+@var{var} is set to successive characters of @var{string}.
+@end deffn
+
+@claused{for, index-of-vector}
+@claused{for, index-of-sequence}
+@claused{for, index-of-string}
+@deffn Clause for @v{var} @cl{index-of-vector} @v{vector} @k{&sequence}
+@deffnx Clause for @v{var} @cl{index-of-sequence} @v{sequence} @k{&sequence}
+@deffnx Clause for @v{var} @cl{index-of-string} @v{string} @k{&sequence}
+
+@var{var} is set to successive indices of the sequence. These clauses
+avoid the overhead of accessing the sequence elements for those
+applications where they do not need to be examined, or are examined
+rarely. They admit all the optional keywords of the other sequence
+drivers except the (redundant) @code{with-index} keyword.
+@end deffn
+
+@claused{for, in-hashtable}
+@deffn Clause for (@v{key} @v{value}) @cl{in-hashtable} @v{table}
+
+@var{key} and @var{value}, which must appear as shown in a list and
+may be destructuring templates, are set to the keys and values of
+@var{table}. If @var{key} is @code{nil}, then the hashtable's keys
+will be ignored; similarly for @var{value}. The order in which
+elements of @var{table} will be retrieved is unpredictable.
+@end deffn
+
+@claused{for, in-package}
+@deffn Clause for @v{var} @cl{in-package} @v{package} @
+ @k{&optional} @k{external-only} @v{ext}
+
+Iterates over all the symbols in @var{package}, or over only the
+external symbols if @var{ext} is specified and non-@code{nil}.
+@var{ext} is not evaluated. The same symbol may appear more than
+once.
+@end deffn
+
+@claused{for, in-packages}
+@deffn Clause for @v{var} @cl{in-packages} @
+ @k{&optional} @k{having-access} @v{symbol-types}
+
+Iterates over all the symbols from the list of packages denoted by the
+descriptor @var{packages} and having accessibility (or visibility)
+given by @var{symbol-types}. This defaults to the list
+@code{(:external :internal :inherited)} and is not evaluated.
+@var{var} must be a list of up to three variables: in each iteration,
+these will be set to a symbol, its access-type and package (as per
+@code{with-package-iterator} in ANSI CL). The same symbol may appear
+more than once.
+@end deffn
+
+@claused{for, in-file}
+@deffn Clause for @v{var} @cl{in-file} @v{name} @
+ @k{&optional} @k{using} @v{reader}
+
+Opens the file @var{name} (which may be a string or pathname) for
+input, and iterates over its contents. @var{reader} defaults to
+@code{read}, so by default @emph{var} will be bound to the successive
+forms in the file. The @iter{} body is wrapped in an
+@code{unwind-protect} to ensure that the file is closed no matter how
+the @iter{} is exited.
+@end deffn
+
+@claused{for, in-stream}
+@deffn Clause for @v{var} @cl{in-stream} @v{stream} @k{&optional} @k{using} @
+ @v{reader}
+
+Like @code{for@dots{} in-file}, except that @var{stream} should be an
+existing stream object that supports input operations.
+@end deffn
+
+@c ===================================================================
+@node Generalized Drivers
+@subsection Generalized Drivers
+
+These are primarily useful for writing drivers that can also be used
+as generators (see @ref{Generators}).
+
+@clauseu{terminate}
+@claused{for, next}
+@deffn Clause for @v{var} @cl{next} @v{expr}
+
+@var{var} is set to @var{expr} each time through the loop.
+Destructuring is performed. When the clause is used as a generator,
+@var{expr} is the code that is executed when @code{(next @emph{var})}
+is encountered (see @ref{Generators}). @var{expr} should compute the
+first value for @var{var}, as well as all subsequent values, and is
+responsible for terminating the loop. For compatibility with future
+versions of @iter{}, this termination should be done with
+@code{terminate}, which can be considered a synonym for @code{finish}
+(see @ref{Control Flow}).
+
+As an example, the following clauses are equivalent to @code{(for i
+from 1 to 10)}:
+
+@lisp
+(initially (setq i 0))
+(for i next (if (> i 10) (terminate) (incf i)))
+@end lisp
+@end deffn
+
+@claused{for, do-next}
+@deffn Clause for @v{var} @k{do-next} @v{form}
+
+@var{form} is evaluated each time through the loop. Its value is
+@var{not} set to @var{var}; that is @var{form}'s job. @var{var} is
+only present so that @iter{} knows it is a driver variable. @*
+@code{(for @var{var} next @var{expr})} is equivalent to @code{(for
+@var{var} do-next (dsetq @var{var} @var{expr}))}. (See
+@ref{Destructuring} for an explanation of @code{dsetq}.)
+@end deffn
+
+@c ===================================================================
+@node Generators
+@subsection Generators
+
+In all of the above clauses, the driver variable is updated on each
+iteration. Sometimes it is desirable to have greater control over
+updating. For instance, consider the problem of associating numbers,
+in increasing order and with no gaps, with the non-@code{nil} elements
+of a list. One obvious first pass at writing this is:
+
+@lisp
+(iter (for el in list)
+ (for i upfrom 1)
+ (if el (collect (cons el i))))
+@end lisp
+
+But on the list @code{(a b nil c)} this produces @code{((a . 1) (b
+. 2) (c . 4))} instead of the desired @code{((a . 1) (b . 2) (c
+. 3))}. The problem is that @code{i} is incremented each time through
+the loop, even when @code{el} is @code{nil}.
+
+The problem could be solved elegantly if we could step @code{i} only
+when we wished to. This can be accomplished for any @iter{} driver by
+writing @code{generate} (or its synonym @code{generating}) instead of
+@code{for}. Doing so produces a @emph{generator}---a driver whose
+values are yielded explicitly. To obtain the next value of a
+generator variable @var{v}, write @code{(next @var{v})}. The value of
+a @code{next} form is the next value of @emph{v}, as determined by its
+associated driver clause. @code{next} also has the side-effect of
+updating @var{v} to that value. If there is no next value,
+@code{next} will terminate the loop, just as with a normal driver.
+
+Using generators, we can now write our example like this:
+
+@lisp
+(iter (for el in list)
+ (generate i upfrom 1)
+ (if el (collect (cons el (next i)))))
+@end lisp
+
+Now @code{i} is updated only when @code{(next i)} is executed, and
+this occurs only when @code{el} is non-@code{nil}.
+
+To better understand the relationship between ordinary drivers and
+generators, observe that we can rewrite an ordinary driver using its
+generator form immediately followed by @code{next}, as this example
+shows:
+
+@lisp
+(iter (generating i from 1 to 10)
+ (next i)
+ @dots{})
+@end lisp
+
+Provided that the loop body contains no @code{(next i)} forms, this
+will behave just as if we had written @code{(for i from 1 to 10)}.
+
+We can still refer to a driver variable @var{v} without using
+@code{next}; in this case, its value is that given to it by the last
+evaluation of @code{(next @var{v})}. Before @code{(next @var{v})} has
+been called the first time, the value of @var{v} is undefined.
+
+This semantics is more flexible than one in which @var{v} begins the
+loop bound to its first value and calls of @code{next} supply
+subsequent values, because it means the loop will not terminate too
+soon if the generator's sequence is empty. For instance, consider the
+following code, which tags non-@code{nil} elements of a list using a
+list of tags, and also counts the null elements. (We assume there are
+at least as many tags as non-@code{nil} elements.)
+
+@lisp
+(let* ((counter 0)
+ (tagged-list (iter (for el in list)
+ (generating tag in tag-list)
+ (if (null el)
+ (incf counter)
+ (collect (cons el (next tag)))))))
+ @dots{})
+@end lisp
+
+It may be that there are just as many tags as non-null elements of
+@code{list}. If all the elements of @code{list} are null, we still
+want the counting to proceed, even though @code{tag-list} is
+@code{nil}. If @code{tag} had to be assigned its first value before
+the loop begins, we would have had to terminate the loop before the
+first iteration, since when @code{tag-list} is @code{nil}, @code{tag}
+has no first value. With the existing semantics, however, @code{(next
+tag)} will never execute, so the iteration will cover all the elements
+of @code{list}.
+
+When the ``variable'' of a driver clause is actually a destructuring
+template containing several variables, all the variables are eligible
+for use with @code{next}. As before, @code{(next @var{v})} evaluates
+to @var{v}'s next value; but the effect is to update all of the
+template's variables. For instance, the following code will return
+the list @code{(a 2 c)}.
+
+@lisp
+(iter (generating (key . item) in '((a . 1) (b . 2) (c . 3)))
+ (collect (next key))
+ (collect (next item)))
+@end lisp
+
+Only driver clauses with variables can be made into generators. This
+includes all clauses mentioned so far except for @code{repeat}. It
+does @emph{not} include @code{for@dots{} previous}, @code{for@dots{}
+=}, @code{for@dots{} initially@dots{} then} or @code{for@dots{}
+first@dots{} then} (see below).
+
+@c ===================================================================
+@node Previous Values of Driver Variables
+@subsection Previous Values of Driver Variables
+
+Often one would like to access the value of a variable on a previous
+iteration. @iter{} provides a special clause for accomplishing this.
+
+@claused{for, previous}
+@deffn Clause for @v{pvar} @cl{previous} @v{var} @
+ @k{&optional} @k{initially} @v{init} @k{back} @v{n}
+
+Sets @var{pvar} to the previous value of @var{var}, which should be a
+driver variable, a variable from another @code{for@dots{} previous}
+clause, or a variable established by a @code{for@dots{} =},
+@code{for@dots{} initially@dots{} then} or @code{for@dots{}
+first@dots{} then} clause (see @ref{Variable Binding and Setting}).
+Initially, @var{pvar} is given the value @var{init} (which defaults to
+@code{nil}). The @var{init} expression will be moved outside the loop
+body, so it should not depend on anything computed within the loop.
+@var{pvar} retains the value of @var{init} until @var{var} is set to
+its second value, at which point @var{pvar} is set to @var{var}'s
+first value; and so on.
+
+The argument @var{n} to @code{back} must be a constant, positive
+integer, and defaults to 1. It determines how many iterations back
+@var{pvar} should track @var{var}. For example, when @var{n} is 2,
+then @var{pvar} will be assigned @var{var}'s first value when
+@var{var} is set to its third value.
+
+A @code{for@dots{} previous} clause may occur after or before its
+associated driver clause. @code{for@dots{} previous} works with
+generators as well as ordinary drivers.
+
+Example:
+
+@lisp
+(iter (for el in '(1 2 3 4))
+ (for p-el previous el)
+ (for pp-el previous p-el initially 0)
+ (collect pp-el))
+@end lisp
+
+This evaluates to @code{(0 0 1 2)}. It could have been written more
+economically as
+
+@lisp
+(iter (for el in '(1 2 3 4))
+ (for pp-el previous el back 2 initially 0)
+ (collect pp-el))
+@end lisp
+@end deffn
+
+@c ===================================================================
+@node Variable Binding and Setting
+@section Variable Binding and Setting
+
+Several clauses exist for establishing new variable bindings or for
+setting variables in the loop. They all support destructuring.
+
+@clauseu{with}
+@deffn Clause with @v{var} @k{&optional} @k{=} @v{value}
+
+Causes @var{var} to be bound to value before the loop body is entered.
+If @var{value} is not supplied, @var{var} assumes a default binding,
+which will be @code{nil} in the absence of declarations. Also, if
+@var{value} is not supplied, no destructuring is performed; instead,
+@var{var} may be a list of symbols, all of which are given default
+bindings. If @var{value} is supplied, @var{var} is bound to it, with
+destructuring.
+
+Because @code{with} creates bindings whose scope includes the entire
+@iter{} form, it is good style to put all @code{with} clauses at the
+beginning.
+
+Successive occurrences of @code{with} result in sequential bindings
+(as with @code{let*}). There is no way to obtain parallel bindings;
+see @ref{Parallel Binding and Stepping} for a rationale.
+@end deffn
+
+@claused{for, =}
+@deffn Clause for @v{var} @cl{=} @v{expr}
+
+On each iteration, @var{expr} is evaluated and @var{var} is set to its
+value.
+
+This clause may appear to do the same thing as @code{for@dots{} next}.
+In fact, they are quite different. @code{for@dots{} =} provides only
+three services: it sets up a binding for @var{var}, sets it to
+@var{expr} on each iteration, and makes it possible to use
+@code{for@dots{} previous} with @var{var}. @code{for@dots{} next}
+provides these services in addition to the ability to turn the driver
+into a generator.
+
+@c Also, the code which sets @var{var} appears in the loop body in the
+@c same place as the @code{for@dots{} =} clause; the code for
+@c @code{for@dots{} next} appears at the top of the loop, as with
+@c other drivers (except when being used as a generator).
+@end deffn
+
+@clauset{for, initially, then}
+@deffn Clause for @v{var} @cl{initially} @v{init-expr} @cl{then} @v{then-expr}
+
+Before the loop begins, @var{var} is set to @var{init-expr;} on all
+iterations after the first it is set to @var{then-expr.} This clause
+must occur at top-level. @var{init-expr} will be moved outside the
+loop body and @var{then-expr} will be moved to the end of the loop
+body, so they are subject to code motion problems (see @ref{Problems
+with Code Movement}).
+
+This clause may appear to be similar to @code{for@dots{} next}, but in
+fact they differ significantly. @code{for@dots{} initially@dots{}
+then} is typically used to give @var{var} its first value before the
+loop begins, and subsequent values on following iterations. This is
+incompatible with generators, whose first value and subsequent values
+must all be computed by @code{(next @var{var})}. Also, the update of
+@var{var} in @code{for@dots{} initially@dots{} then} does not occur at
+the location of the clause.
+
+Use @code{for@dots{} initially@dots{} then} for one-shot computations
+where its idiom is more convenient, but use @code{for@dots{} next} for
+extending @iter{} with new drivers (see @ref{Rolling Your Own}).
+@end deffn
+
+@clauset{for, first, then}
+@deffn Clause for @v{var} @cl{first} @v{first-expr} @cl{then} @v{then-expr}
+
+The first time through the loop, @var{var} is set to @var{first-expr};
+on subsequent iterations, it is set to @var{then-expr}. This differs
+from @code{for@dots{} initially} in that @var{var} is set to
+@var{first-expr} inside the loop body, so @var{first-expr} may depend
+on the results of other clauses. For instance,
+
+@lisp
+(iter (for num in list)
+ (for i first num then (1+ i))
+ ...)
+@end lisp
+
+will set @code{i} to the first element of @code{list} on the first
+iteration, whereas
+
+@lisp
+(iter (for num in list)
+ (for i initially num then (1+ i))
+ ...)
+@end lisp
+
+is probably erroneous; @code{i} will be bound to @code{num}'s default
+binding (usually @code{nil}) for the first iteration.
+@end deffn
+
+@quotation Compatibility Note
+@code{loop}'s @code{for@dots{} =} works like @iter{}'s, but
+@code{loop} used the syntax @code{for@dots{} =@dots{} then} to mean
+@code{for@dots{} initially@dots{} then}. It was felt that these two
+operations were sufficiently different to warrant different keywords.
+
+Also, the @code{for} in the above three clauses is misleading, since
+none is true driver (e.g. none has a corresponding @code{generate}
+form). @code{setting} would have been a better choice, but @code{for}
+was used to retain some compatibility with @code{loop}.
+@end quotation
+
+@c ===================================================================
+@node Gathering Clauses
+@section Gathering Clauses
+
+Many of @iter{}'s clauses accumulate values into a variable, or set a
+variable under certain conditions. At the end of the loop, this
+variable contains the desired result. All these clauses have an
+optional @code{into} keyword, whose argument should be a symbol. If
+the @code{into} keyword is not supplied, the accumulation variable
+will be internally generated and its value will be returned at the end
+of the loop; if a variable is specified, that variable is used for the
+accumulation, and is not returned as a result---it is up to the user
+to return it explicitly, in the loop's epilogue code (see
+@code{finally}). It is safe to examine the accumulation variable
+during the loop, but it should not be modified.
+
+These clauses all begin with a verb. When the verb does not conflict
+with an existing Common Lisp function, then it may be used in either
+its infinitival or present-participle form (e.g. @code{sum},
+@code{summing}). However, when there is a conflict with Common Lisp,
+only the present-participle form may be used (e.g. @code{unioning}).
+This is to prevent @iter{} clauses from clashing with Common Lisp
+functions.
+
+@c although these clauses are described as ``producing a value,'' it
+@c is a mistake to think of the lisp list representing the clause as a
+@c value-producing form in the usual way. clauses may legally be
+@c written where a value is expected, e.g. @code{(setq x (sum i))},
+@c but the lisp value of a clause in such a context is undefined.
+
+@menu
+* Reductions::
+* Accumulations::
+* Finders::
+* Boolean Tests::
+* Aggregated Boolean Tests::
+@end menu
+
+@c ===================================================================
+@node Reductions
+@subsection Reductions
+
+@emph{Reduction} is an extremely common iteration pattern in which the
+results of successive applications of a binary operation are
+accumulated. For example, a loop that computes the sum of the
+elements of a list is performing a reduction with the addition
+operation. This could be written in Common Lisp as @code{(reduce #'+
+list)} or with @iter{} as
+
+@lisp
+(iter (for el in list)
+ (sum el))
+@end lisp
+
+@clauseu{sum}
+@deffn Clause sum @v{expr} @k{&optional} @k{into} @v{var}
+
+Each time through the loop, @var{expr} is evaluated and added to a
+variable, which is bound initially to zero. If @var{expr} has a type,
+it is @emph{not} used as the type of the sum variable, which is always
+@code{number}. To get the result variable to be of a more specific
+type, use an explicit variable, as in
+
+@lisp
+(iter (for el in number-list)
+ (sum el into x)
+ (declare (fixnum x))
+ (finally (return x)))
+@end lisp
+@end deffn
+
+@clauseu{multiply}
+@deffn Clause multiply @v{expr} @k{&optional} @k{into} @v{var}
+
+Like @code{sum}, but the initial value of the result variable is
+@math{1}, and the variable is updated by multiplying @var{expr} into
+it.
+@end deffn
+
+@clauseu{counting}
+@deffn Clause counting @v{expr} @k{&optional} @k{into} @v{var}
+
+@var{expr} is evaluated on each iteration. If it is non-@code{nil},
+the accumulation variable, initially zero, is incremented.
+@end deffn
+
+@clauseu{maximize}
+@clauseu{minimize}
+@deffn Clause maximize @v{expr} @k{&optional} @k{into} @v{var}
+@deffnx Clause minimize @v{expr} @k{&optional} @k{into} @v{var}
+
+@var{expr} is evaluated on each iteration and its extremum (maximum or
+minimum) is stored in the accumulation variable. If @var{expr} is
+never evaluated, then the result is @code{nil} (if the accumulation
+variable is untyped) or @math{0} (if it has a numeric type).
+@end deffn
+
+@clauseu{reducing}
+@deffn Clause reducing @v{expr} @k{by} @v{func} @k{&optional}
+ @k{initial-value} @v{init-val} @k{into} @v{var}
+
+This is a general way to perform reductions. @var{func} should be a
+function of two arguments, the first of which will be the value
+computed so far and the second of which will be the value of
+@var{expr}. It should return the new value. @code{reducing} is
+roughly equivalent to the Common Lisp @code{(reduce @var{func}
+@var{sequence} :key @var{expr-function})}, where @var{expr-function}
+is used to derive values from the successive elements of
+@var{sequence}.
+
+If the @code{reducing} clause is never executed, the result is
+undefined.
+
+It is not necessary to provide an initial value, but better code can
+be generated if one is supplied. Regardless of its location in the
+@iter{} body, @var{init-val} will be evaluated before the loop is
+entered, so it should not depend on any value computed inside the
+@iter{} form.
+
+@c if a @var{var} is not specified, you can get @iter{} to declare the
+@c type of the internal variable by putting a @code{the} expression
+@c around @var{func}. see @ref{Types}.
+@end deffn
+
+@c @impnote{in principle, |maximize| and |minimize| can be thought of
+@c as reductions where the initial value is the smallest (or largest)
+@c value that the accumulation variable can assume. because lisp's
+@c bignums can represent arbitrary integers, these clauses cannot be
+@c implemented as reductions in general. if, however, the type of
+@c ~expr~ or ~var~ can be determined to be a fixnum or a float,
+@c @iter{} will implement the clause as a true reduction, using one of
+@c the constants |most-negative-fixnum|, |@c most-positive-fixnum|,
+@c |most-negative-short-float|, etc. as appropriate.}
+
+@c ===================================================================
+@node Accumulations
+@subsection Accumulations
+
+All the predefined accumulation clauses add values to a sequence. If
+the sequence is a list, they all have the property that the partial
+list is kept in the correct order and available for inspection at any
+point in the loop.
+
+@clauseu{collect}
+@deffn Clause collect @v{exptr} @k{&optional}
+ @k{into} @v{var} @k{at} @v{place} @k{result-type} @v{type}
+
+Produces a sequence of the values of @var{exptr} on each
+iteration. @var{place} indicates where the next value of @var{exptr}
+is added to the list and may be one of the symbols @code{start},
+@code{beginning} (a synonym for @code{start}) or @code{end}. The
+symbol may be quoted, but need not be. The default is @code{end}.
+For example,
+
+@lisp
+(iter (for i from 1 to 5)
+ (collect i))
+@end lisp
+
+produces @code{(1 2 3 4 5)}, whereas
+
+@lisp
+(iter (for i from 1 to 5)
+ (collect i at beginning))
+@end lisp
+
+produces @code{(5 4 3 2 1)} (and is likely to be faster in most Common
+Lisp implementations).
+
+If @var{type} is provided, it should be a subtype of @code{sequence}.
+The default is @code{list}. Specifying a type other than @code{list}
+will result in @code{collect} returning a sequence of that type.
+@emph{However}, the type of the sequence being constructed when inside
+the loop body is undefined when a non-@code{list} type is specified.
+(As with @var{place}, quoting @var{type} is optional.)
+@end deffn
+
+@clauseu{adjoining}
+@deffn Clause adjoining @v{exptr} @k{&optional} @k{into} @v{var} @
+ @k{test} @v{test} @k{at} @v{place} @
+ @k{result-type} @v{type}
+
+Like @code{collect}, but only adds the value of @var{exptr} if it is
+not already present. @var{test}, which defaults to @code{#'eql}, is
+the test to be used with @code{member}.
+@end deffn
+
+@clauseu{appending}
+@clauseu{nconcing}
+@clauseu{unioning}
+@clauseu{nunioning}
+@deffn Clause appending @v{expr} @k{&optional} @k{into} @v{var} @k{at} @v{place}
+@deffnx Clause nconcing @v{expr} @k{&optional} @k{into} @v{var} @k{at} @v{place}
+@deffnx Clause unioning @v{expr} @k{&optional} @k{into} @v{var} @
+ @k{test} @v{test} @k{at} @v{place}
+@deffnx Clause nunioning @v{expr} @k{&optional} @k{into} @v{var} @
+ @k{test} @v{test} @k{at} @v{place}
+
+These are like @code{collect}, but behave like the Common Lisp
+functions @code{append}, @code{nconc}, @code{union} or @code{nunion}.
+As in Common Lisp, they work only on lists. Also as in Common Lisp,
+@code{unioning} and @code{nunioning} assume that the value of
+@var{expr} contains no duplicates.
+@end deffn
+
+@clauseu{accumulate}
+@deffn Clause accumulate @v{expr} @k{by} @v{func} @k{&optional} @
+ @k{initial-value} @v{init-val} @k{into} @v{var}
+
+This is a general-purpose accumulation clause. @var{func} should be a
+function of two arguments, the value of @var{expr} and the value
+accumulated so far in the iteration, and it should return the updated
+value. If no initial value is supplied, @code{nil} is used.
+
+@c If a @var{var} is not specified, you can get @iter{} to declare the
+@c type of the internal variable by putting a @code{the} expression
+@c around @var{func}. see section \ref{types}.
+
+The differences between @code{accumulate} and @code{reducing} are
+slight. One difference is that the functions take their arguments in
+a different order. Another is that in the absence of @var{init-val},
+@code{accumulate} will use @code{nil}, whereas @code{reducing} will
+generate different code that avoids any dependence on the initial
+value. The reason for having both clauses is that one usually thinks
+of reductions (like @code{sum}) and accumulations (like
+@code{collect}) as different beasts.
+@end deffn
+
+@c ===================================================================
+@node Finders
+@subsection Finders
+
+A @emph{finder} is a clause whose value is an expression that meets
+some condition.
+
+@claused{finding, such-that}
+@deffn Clause finding @var{expr} @cl{such-that} @v{test} @k{&optionally} @
+ @k{into} @v{var} @k{on-failure} @v{failure-value}
+
+If @var{test} (which is an expression) ever evaluates to
+non-@code{nil}, the loop is terminated, the epilogue code is run and
+the value of @var{expr} is returned. Otherwise, @code{nil} (or
+@var{failure-value}, if provided) is returned. If @var{var} is
+provided, it will have either the non-@code{nil} value of @var{expr}
+or @var{failure-value} when the epilogue code is run.
+
+As a special case, if the @var{test} expression is a sharp-quoted
+function, then it is applied to @var{expr} instead of being simply
+evaluated. E.g. @code{(finding x such-that #'evenp)} is equivalent to
+@code{(finding x such-that (evenp x))}.
+
+@c \cpar although @var{test} need have nothing to do with ~@c expr~ as in
+@c |(finding j such-that (> i 3))|, it usually
+@c will: |(finding (length el) such-that (oddp (length el)))|. to
+@c avoid performing the |length| computation twice, you could write
+@c |(finding (length el) such-that \#'oddp)| or |(finding (length
+@c el) such-that 'oddp)|; for these cases, @iter{} generates code that
+@c executes @var{expr} only once. the code for |\#'oddp|
+@c is slightly different from that for {\lisp 'oddp}; see the discussion
+@c under {\lisp for\dots in} and {\lisp for\dots on}.
+
+@code{On-failure} is a misnomer. Because it is always evaluated, it
+behaves more like the default third argument to the @code{gethash}
+function. As a result, @code{on-failure (error "Not found")} makes no
+sense. Instead, the clauses @code{leave} or @code{thereis} can be used
+in conjunction with @code{finally} as follows:
+
+@lisp
+(iter (for x in '(1 2 3))
+ (if (evenp x) (leave x))
+ (finally (error "not found")))
+@end lisp
+
+This clause may appear multiple times when all defaults are
+identical. It can also be used together with either
+@code{always}/@code{never} or @code{thereis} if their defaults
+match. More specifically, @code{on-failure nil} is compatible with
+@code{thereis}, while @code{on-failure t} is compatible with
+@code{always} and @code{never} clauses.
+
+@lisp
+(iter (for i in '(7 -4 2 -3))
+ (if (plusp i)
+ (finding i such-that (evenp i))
+ (finding (- i) such-that (oddp i))))
+@end lisp
+@end deffn
+
+@claused{finding, maximizing}
+@claused{finding, minimizing}
+@deffn Clause finding @v{expr} @cl{maximizing} @v{m-expr} @
+ @k{&optional} @k{into} @v{var}
+@deffnx Clause finding @v{expr} @cl{minimizing} @v{m-expr} @
+ @k{&optional} @k{into} @v{var}
+
+Computes the extremum (maximum or minimum) value of @var{m-expr} over
+all iterations, and returns the value of @var{expr} corresponding to
+the extremum. @var{expr} is evaluated inside the loop at the time the
+new extremum is established. If @var{m-expr} is never evaluated (due
+to, for example, being embedded in a conditional clause), then the
+returned value depends on the type, if any, of @var{expr} (or
+@var{var}, if one is supplied). If there is no type, the returned
+value will be \nil; if the type is numeric, the returned value will be
+zero.
+
+For these two clauses, @var{var} may be a list of two symbols; in that
+case, the first is used to record @var{expr} and the second,
+@var{m-expr}.
+
+As with @code{finding@dots{} such-that}, if @var{m-expr} is a
+sharp-quoted function, then it is called on @var{expr} instead of
+being evaluated.
+@end deffn
+
+@c ===================================================================
+@node Boolean Tests
+@subsection Boolean Tests
+
+@clauseu{first-iteration-p}
+@deffn Clause first-iteration-p
+
+Returns @code{t} in the first cycle of the loop, otherwise @code{nil}.
+@end deffn
+
+@clauseu{first-time-p}
+@deffn Clause first-time-p
+
+Returns @code{t} the first time the expression is evaluated, and then
+@code{nil} forever. This clause comes handy when printing (optional)
+elements separated by a comma:
+
+@lisp
+(iter (for el in '(nil 1 2 nil 3))
+ (when el
+ (unless (first-time-p)
+ (princ ", "))
+ (princ el)))
+@end lisp
+produces @code{"1, 2, 3"}.
+@end deffn
+
+@c ===================================================================
+@node Aggregated Boolean Tests
+@subsection Aggregated Boolean Tests
+
+@clauseu{always}
+@deffn Clause always @v{expr}
+
+If @var{expr} ever evaluates to @code{nil}, then @code{nil} is
+immediately returned; the epilogue code is not executed. If
+@var{expr} never evaluates to @code{nil}, the epilogue code is
+executed and the last value of @var{expr} (or @code{t} if @var{expr}
+was never evaluated) is returned (whereas @code{loop} would constantly
+return @code{t}).
+
+@c mention last evaluated clause when multiple always clauses?
+@end deffn
+
+@clauseu{never}
+@deffn Clause never @v{expr}
+
+Like @code{(always (not @var{expr}))}, except it does not influence
+the last value returned by a possible other @code{always} clause. That
+is,
+
+@lisp
+(iter (repeat 2)
+ (always 2)
+ (never nil)) @result{} 2 ; not t
+@end lisp
+@end deffn
+
+@clauseu{thereis}
+@deffn Clause thereis @v{expr}
+
+If @var{expr} is ever non-@code{nil}, its value is immediately
+returned without running epilogue code. Otherwise, the epilogue code
+is performed and @code{nil} is returned.
+
+This clause cannot be used together with @code{always} or
+@code{never}, because their defaults are opposed (similarly,
+@code{(loop always 3 thereis nil)} refuses to compile in some
+implementations of @code{loop}).
+@end deffn
+
+@c ===================================================================
+@node Control Flow
+@section Control Flow
+
+Several clauses can be used to alter the usual flow of control in a
+loop.
+
+Note: the clauses of this and subsequent sections don't adhere to
+@iter{}'s usual syntax, but instead use standard Common Lisp syntax.
+Hence the format for describing syntax subsequently is like the
+standard format used in the Common Lisp manual, not like the
+descriptions of clauses above.
+
+@clauseu{finish}
+@deffn Clause finish
+
+Stops the loop and runs the epilogue code.
+@end deffn
+
+@c for example:
+@c
+@c @lisp
+@c (iter (with answer = nil)
+@c (initially (make-a-mess))
+@c (for i from 1 to 10)
+@c (when (correct? i)
+@c (setq answer i)
+@c (finish))
+@c (finally (cleanup)))
+@c @end lisp
+@c
+@c this code will execute |cleanup| whether or not the test |(correct?
+@c i)| ever succeeds.
+@c the (more elegant) formulation,
+@c @lisp
+@c (iter (initially (make-a-mess))
+@c (for i from 1 to 10)
+@c (finding i such-that (correct? i))
+@c (finally (cleanup)))
+@c @end lisp
+@c would not execute |cleanup| if |(correct? i)| succeeded; it
+@c would do an immediate return.
+
+@clauseu{leave}
+@deffn Clause leave @k{&optional} @v{value}
+
+Immediately returns @var{value} (default @code{nil}) from the current
+@iter{} form, skipping the epilogue code. Equivalent to using
+@code{return-from}.
+@end deffn
+
+@clauseu{next-iteration}
+@deffn Clause next-iteration
+
+Skips the remainder of the loop body and begins the next iteration of
+the loop.
+@end deffn
+
+@clauseu{while}
+@deffn Clause while @v{expr}
+
+If @var{expr} ever evaluates to @code{nil}, the loop is terminated and
+the epilogue code executed. Equivalent to @code{(if (not @var{expr})
+(finish))}.
+@end deffn
+
+@clauseu{until}
+@deffn Clause until @v{~expr~}
+
+Equivalent to @code{(if @var{expr} (finish))}.
+@end deffn
+
+@clauseu{if-first-time}
+@deffn Clause if-first-time @v{then} @k{&optional} @v{else}
+
+If this clause is being executed for the first time in this invocation
+of the @iter{} form, then the @var{then} code is evaluated; otherwise
+the @var{else} code is evaluated.
+
+@code{(for @var{var} first @var{expr1} then @var{expr2})} is almost
+equivalent to
+
+@lisp
+(if-first-time (dsetq @var{var} @var{expr1})
+ (dsetq @var{var} @var{expr2}))
+@end lisp
+
+The only difference is that the @code{for} version makes @var{var}
+available for use with @code{for@dots{} previous}.
+@end deffn
+
+@c ===================================================================
+@node Code Placement
+@section Code Placement
+
+When fine control is desired over where code appears in a loop
+generated by @iter{}, the following special clauses may be useful.
+They are all subject to code-motion problems (see @ref{Problems with
+Code Movement}).
+
+@clauseu{initially}
+@deffn Clause initially @k{&rest} @var{forms}
+
+The lisp @var{forms} are placed in the prologue section of the loop,
+where they are executed once, before the loop body is entered.
+@end deffn
+
+@clauseu{after-each}
+@deffn Clause after-each @k{&rest} @v{forms}
+
+The @var{forms} are placed at the end of the loop body, where they
+are executed after each iteration. Unlike the other clauses in this
+section, @var{forms} may contain @iter{} clauses.
+@end deffn
+
+@clauseu{else}
+@deffn Clause else @k{&rest} @v{forms}
+
+The lisp @var{forms} are placed in the epilogue section of the loop,
+where they are executed if this @code{else} clause is never met during
+execution of the loop and the loop terminates normally.
+@end deffn
+
+@clauseu{finally}
+@deffn Clause finally @k{&rest} @v{forms}
+
+The lisp @var{forms} are placed in the epilogue section of the loop,
+where they are executed after the loop has terminated normally.
+@end deffn
+
+@clauseu{finally-protected}
+@deffn finally-protected @k{&rest} @v{forms}
+
+The lisp @var{forms} are placed in the second form of an
+@code{unwind-protect} outside the loop. They are always executed
+after the loop has terminated, regardless of how the termination
+occurred.
+@end deffn
+
+@c ===================================================================
+@node Other Features
+@chapter Other Features
+
+@section Multiple Accumulations
+
+It is permitted to have more than one clause accumulate into the same
+variable, as in the following:
+
+@lisp
+(iter (for i from 1 to 10)
+ (collect i into nums)
+ (collect (sqrt i) into nums)
+ (finally (return nums)))
+@end lisp
+
+Clauses can only accumulate into the same variable if they are
+compatible. @code{collect}, @code{adjoining}, @code{appending},
+@code{nconcing}, @code{unioning} and @code{nunioning} are compatible
+with each other; @code{sum}, @code{multiply} and @code{counting} are
+compatible; @code{always} and @code{never} are compatible;
+@code{finding}@dots{} @code{such-that} is compatible with either
+@code{thereis} or @code{always} and @code{never} when their defaults
+match; and @code{maximize} and @code{minimize} clauses are compatible
+only with other @code{maximize} and @code{minimize} clauses,
+respectively.
+
+@c note that the same variable ~cannot~ be both an accumulation
+@c variable and an ordinary variable; there can be only one variable
+@c with a given name within an @iter{} form.
+
+@menu
+* Named Blocks::
+* Destructuring::
+* On-line Help::
+* Parallel Binding and Stepping::
+@end menu
+
+@c ===================================================================
+@node Named Blocks
+@section Named Blocks
+
+Like Common Lisp @code{block}s, @iter{} forms can be given names. The
+name should be a single symbol, and it must be the first form in the
+@iter{}. The generated code behaves exactly like a named block; in
+particular, @code{(return-from @var{name})} can be used to exit it:
+
+@lisp
+(iter fred
+ (for i from 1 to 10)
+ (iter barney
+ (for j from i to 10)
+ (if (> (* i j) 17)
+ (return-from fred j))))
+@end lisp
+
+An @iter{} form that is not given a name is implicitly named
+@code{nil}.
+
+Sometimes one would like to write an expression in an inner @iter{}
+form, but have it processed by an outer @iter{} form. This is
+possible with the @code{in} clause.
+
+@clauseu{in}
+@deffn Clause in @v{name} @k{&rest} @v{forms}
+
+Evaluates @var{forms} as if they were part of the @iter{} form named
+@var{name}. In other words, @iter{} clauses are processed by the
+@iter{} form named @var{name}, and not by any @iter{} forms that occur
+inside @var{name}.
+
+As an example, consider the problem of collecting a list of the
+elements in a two-dimensional array. The naive solution,
+@lisp
+(iter (for i below (array-dimension ar 0))
+ (iter (for j below (array-dimension ar 1))
+ (collect (aref ar i j))))
+@end lisp
+is wrong because the list created by the inner @iter{} is simply
+ignored by the outer one. But using @code{in} we can write:
+@lisp
+(iter outer (for i below (array-dimension ar 0))
+ (iter (for j below (array-dimension ar 1))
+ (in outer (collect (aref ar i j)))))
+@end lisp
+which has the desired result.
+@end deffn
+
+@c ===================================================================
+@node Destructuring
+@section Destructuring
+
+In many places within @iter{} clauses where a variable is expected, a
+list can be written instead. In these cases, the value to be assigned
+is @emph{destructured} according to the pattern described by the list.
+As a simple example, the clause
+@lisp
+(for (key . item) in alist)
+@end lisp
+will result in @code{key} being set to the @code{car} of each element
+in @code{alist}, and @code{item} being set to the @code{cdr}. The
+pattern list may be nested to arbitrary depth, and (as the example
+shows) need not be terminated with @code{nil}; the only requirement is
+that each leaf be a bindable symbol (or @code{nil}, in which case no
+binding is generated for that piece of the structure).
+
+Sometimes, you might like to do the equivalent of a
+@code{multiple-value-setq} in a clause. This ``multiple-value
+destructuring'' can be expressed by writing @code{(values @var{pat1}
+@var{pat2} @dots{})} for a destructuring pattern, as in
+
+@lisp
+(for (values (a . b) c d) = (three-valued-function ...))
+@end lisp
+
+Note that the @var{pati} can themselves be destructuring patterns
+(though not multiple-value destructuring patterns). You can't do
+multiple-value destructuring in a @code{with} clause; instead wrap the
+whole @iter{} form in a @code{multiple-value-bind}.
+
+@quotation Rationale
+There are subtle interactions between variable declarations and
+evaluation order that make the correct implementation of
+multiple-value destructuring in a @code{with} somewhat tricky.
+@end quotation
+
+The destructuring feature of @iter{} is available as a separate
+mechanism, using the @code{dsetq} macro:
+
+@itindex dsetq
+@defmac dsetq @v{template} @v{expr}
+
+Performs destructuring of @var{expr} using @var{template}. May be
+used outside of an @iter{} form. Yields the primary value of
+@var{expr}.
+@end defmac
+
+@c ===================================================================
+@node On-line Help
+@section On-line Help
+
+There is a limited facility for on-line help, in the form of the
+@code{display-iterate-clauses} function.
+
+@itindex display-iterate-clauses
+@defun display-iterate-clauses @k{&optional} @v{clause-spec}
+
+Displays a list of @iter{} clauses. If @var{clause-spec} is not
+provided, all clauses are shown; if it is a symbol, all clauses
+beginning with that symbol are shown; and if it is a list of symbols,
+all clauses for which @var{clause-spec} is a prefix are shown.
+@end defun
+
+@c ===================================================================
+@node Parallel Binding and Stepping
+@section Parallel Binding and Stepping
+
+The parallel binding and stepping of variables is a feature that
+@iter{} does @emph{not} have. This section attempts to provide a
+rationale.
+
+We say that two variables are bound @emph{in parallel} if neither
+binding shadows the other. This is the usual semantics of @code{let}
+(as opposed to @code{let*}). Similarly, we can say that iteration
+variables are stepped in parallel if neither variable is updated
+before the other, conceptually speaking; in other words, if the code
+to update each variable can reference the old values of both
+variables.
+
+@code{loop} allows parallel binding of variables and parallel stepping
+of driver variables. My view is that if you are depending on the
+serial/parallel distinction, you are doing something obscure. If you
+need to bind variables in parallel using @code{with}, then you must be
+using a variable name that shadows a name in the existing lexical
+environment. Don't do that. The most common use for parallel
+stepping is to track the values of variables on the previous
+iteration, but in fact this does not require parallel stepping at all;
+the following will work:
+
+@lisp
+(iter (for current in list)
+ (for prev previous current)
+ @dots{})
+@end lisp
+
+@c ===================================================================
+@node Types and Declarations
+@chapter Types and Declarations
+
+@section Discussion
+
+Sometimes efficiency dictates that the types of variables be declared.
+This type information needs to be communicated to @iter{} so it can
+bind variables to appropriate values. Furthermore, @iter{} must often
+generate internal variables invisible to the user; there needs to be a
+way for these to be declared.
+
+As an example, consider this code, which will return the number of
+odd elements in @code{number-list}:
+
+@lisp
+(iter (for el in number-list)
+ (count (oddp el)))
+@end lisp
+
+In processing this form, @iter{} will create an internal variable, let
+us call it @code{list17}, to hold the successive @code{cdr}s of
+@code{number-list}, and will bind the variable to @code{number-list}.
+It will also generate a default binding for @code{el}; only inside the
+body of the loop will @code{el} be set to the @code{car} of
+@code{list17}. Finally, @iter{} will generate a variable, call it
+@code{result}, to hold the result of the count, and will bind it to
+zero.
+
+When dealing with type declarations, @iter{} observes one simple rule:
+@emph{it will never generate a declaration unless requested to do so}.
+The reason is that such declarations might mask errors in compiled
+code by avoiding error-checks; the resulting problems would be doubly
+hard to track down because the declarations would be hidden from the
+programmer. Of course, a compiler might omit error-checks even in the
+absence of declarations, though this behavior can usually be avoided,
+e.g. by saying @code{(declaim (optimize (safety 3)))}.
+
+So, the above @iter{} form will generate code with no declarations.
+But say we wish to declare the types of @code{el} and the internal
+variables @code{list17} and @code{result}. How is this done?
+
+Declaring the type of @code{el} is easy, since the programmer knows
+the variable's name:
+
+@lisp
+(iter (for el in number-list)
+ (declare (fixnum el))
+ (counting (oddp el)))
+@end lisp
+
+@iter{} can read variable type declarations like this one. Before
+processing any clauses, it scans the entire top-level form for type
+declarations and records the types, so that variable bindings can be
+performed correctly. In this case, @code{el} will be bound to zero
+instead of @code{nil}. Also, @iter{} collects all the top-level
+declarations and puts them at the begining of the generated code, so
+it is not necessary to place all declarations at the beginning of an
+@iter{} form; instead, they can be written near the variables whose
+types they declare.
+
+Since @iter{} is not part of the compiler, it will not know
+about declarations that occur outside an @iter{} form; these
+declarations must be repeated inside the form.
+
+Here is another way we could have declared the type of @code{el}:
+
+@lisp
+(iter (for (the fixnum el) in number-list)
+ (counting (oddp el)))
+@end lisp
+
+@itindex the
+@iter{} extends the Common Lisp @code{the} form to apply to variables
+as well as value-producing forms; anywhere a variable is allowed---in
+a @code{with} clause, as the iteration variable in a driver clause, as
+the @code{into} argument of an accumulation clause, even inside a
+destructuring template---you can write @code{(the @var{type}
+@var{symbol})} instead.
+
+There is one crucial difference between using a @code{the} form and
+actually declaring the variable: explicit declarations are always
+placed in the generated code, but type information from a @code{the}
+form is not turned into an actual declaration unless you tell @iter{}
+to do so using @code{iterate:declare-variables}. See below.
+
+Declaring the types of internal variables is harder than declaring the
+types of explicitly mentioned variables, since their names are
+unknown. You do it by declaring @code{iterate:declare-variables}
+somewhere inside the top level of the @iter{} form. (This will also
+generate declarations for variables declared using @code{the}.)
+@iter{} does not provide much selectivity here: it's all or none. And
+unfortunately, since @iter{} is not privy to compiler information but
+instead reads declarations itself, it will not hear if you
+@code{(declaim (iterate:declare-variables))}. Instead, set the
+variable @code{iterate::*always-declare-variables*} to @code{t} at
+compile-time, using @code{eval-when}.
+
+To determine the appropriate types for internal variables, @iter{}
+uses three sources of information:
+
+@itemize
+@item
+Often, the particular clause dictates a certain type for a
+variable; @iter{} will use this information when available. In the
+current example, the variable @code{list17} will be given the type
+@code{list}, since that is the only type that makes sense; and the
+variable @code{result} will be given the type @code{fixnum}, on the
+assumption that you will not be counting high enough to need bignums.
+You can override this assumption only by using and explicitly declaring a
+variable:
+
+@lisp
+(iter (declare (iterate:declare-variables))
+ (for el in number-list)
+ (count (oddp el) into my-result)
+ (declare (integer my-result))
+ (finally (return my-result)))
+@end lisp
+
+Other examples of the type assumptions that @iter{} makes are: type
+@code{list} for @code{into} variables of collection clauses; type
+@code{list} for expressions that are to be destructured; type
+@code{vector} for the variable holding the vector in a
+@code{for@dots{} in-vector} clause, and similarly for @code{string}
+and the @code{for@dots{} in-string} clause; and the
+implementation-dependent type @code{(type-of array-dimension-limit)}
+for the index and limit variables generated by sequence iteration
+drivers like @code{for@dots{} in-vector} and @code{for@dots{}
+in-string} (but not @code{for@dots{} in-sequence}, because it may be
+used to iterate over a list).
+
+@item
+Sometimes, @iter{} will examine expressions and try to determine their
+types in a simple-minded way. If the expression is self-evaluating
+(like a number, for instance), @iter{} knows that the expression's
+type is the same as the type of the value it denotes, so it can use
+that type. If the expression is of the form @code{(the @var{type}
+@var{expr})}, @iter{} is smart enough to extract @var{type} and use
+it. However, the current version of @iter{} does not examine
+declarations of function result types or do any type inference. It
+will not determine, for example, that the type of @code{(+ 3 4)} is
+@code{fixnum}, or even @code{number}.
+
+@item
+In some cases, the type of an internal variable should match the type
+of some other variable. For instance, @iter{} generates an internal
+variable for @code{(f x)} in the clause @code{(for i from 1 to (f
+x))}, and in the absence of other information will give it the same
+type as @code{i}. If, however, the expression had been written
+@code{(the fixnum (f x))}, then @iter{} would have given the internal
+variable the type @code{fixnum} regardless of @code{i}'s type. The
+type incompatibility errors that could arise in this situation are not
+checked for.
+@end itemize
+
+Note that if you do declare @code{iterate:declare-variables}, then
+@iter{} may declare user variables as well as internal ones if they do
+not already have declarations, though only for variables that it
+binds. For instance, in this code:
+
+@lisp
+(iter (declare (iterate:declare-variables))
+ (for i from 1 to 10)
+ (collect i into var))
+@end lisp
+
+the variable @code{var} will be declared to be of type @code{list}.
+
+@section Summary
+
+@itindex declare-variables
+@itindex *always-declare-variables*
+@iter{} understands standard Common Lisp variable type declarations
+that occur within an @iter{} form and will pass them through to the
+generated code. If the declaration @code{(iterate:declare-variables)}
+appears at the top level of an @iter{} form, or if
+@code{iterate::*always-declare-variables*} is non-@code{nil}, then
+@iter{} will use the type information gleaned from user declarations,
+self-evaluating expressions and @code{the} expressions, combined with
+reasonable assumptions, to determine variable types and declare them.
+
+@c ===================================================================
+@node Problems with Code Movement
+@chapter Problems with Code Movement
+
+Some @iter{} clauses, or parts of clauses, result in code being moved
+from the location of the clause to other parts of the loop. Drivers
+behave this way, as do code-placement clauses like @code{initially}
+and @code{finally}. When using these clauses, there is a danger of
+writing an expression that makes sense in its apparent location but
+will be invalid or have a different meaning in another location. For
+example:
+
+@lisp
+(iter (for i from 1 to 10)
+ (let ((x 3))
+ (initially (setq x 4))))
+@end lisp
+
+While it may appear that the @code{x} of @code{(initially (setq x 4))}
+is the same as the @code{x} of @code{(let ((x 3)) @dots{}}, in fact
+they are not: @code{initially} moves its code outside the loop body,
+so @code{x} would refer to a global variable. Here is another example
+of the same problem:
+
+@lisp
+(iter (for i from 1 to 10)
+ (let ((x 3))
+ (collect i into x)))
+@end lisp
+
+If this code were executed, @code{collect} would create a binding for
+its @code{x} at the top level of the @iter{} form that the @code{let}
+will shadow.
+
+Happily, @iter{} is smart enough to catch these errors; it walks all
+problematical code to ensure that free variables are not bound inside
+the loop body, and checks all variables it binds for the same problem.
+
+However, some errors cannot be caught:
+
+@lisp
+(iter (with x = 3)
+ (for el in list)
+ (setq x 1)
+ (reducing el by #'+ initial-value x))
+@end lisp
+
+@code{reducing} moves its @code{initial-value} argument to the
+initialization part of the loop in order to produce more efficient
+code. Since @iter{} does not perform data-flow analysis, it cannot
+determine that @code{x} is changed inside the loop; all it can
+establish is that @code{x} is not bound internally. Hence this code
+will not signal an error and will use @math{3} as the initial value of
+the reduction.
+
+The following list summarizes all cases that are subject to these code
+motion and variable-shadowing problems.
+
+@itemize
+@item
+Any variable for which @iter{} creates a binding, including those used
+in @code{with} and the @code{into} keyword of many clauses.
+
+@item
+The special clauses which place code: @code{initially},
+@code{after-each}, @code{else}, @code{finally} and
+@code{finally-protected}.
+
+@item
+The variables of a @code{next} or @code{do-next} form.
+
+@item
+The @code{initially} arguments of @code{for@dots{} initially@dots{}
+then} and @code{for@dots{} previous}.
+
+@item
+The @code{then} argument of @code{for@dots{} initially@dots{} then}.
+
+@item
+The @code{initial-value} arguments of @code{reducing} and
+@code{accumulate}.
+
+@item
+The @code{on-failure} argument of @code{finding@dots{} such-that}.
+@end itemize
+
+@c ===================================================================
+@node Differences Between Iterate and Loop
+@chapter Differences Between @code{Iterate} and @code{Loop}
+
+@code{loop} contains a great deal of complexity which @iter{} tries to
+avoid. Hence many esoteric features of @code{loop} don't exist in
+@iter{}. Other features have been carried over, but in a cleaned-up
+form. And of course, many new features have been added; they are not
+mentioned in this list.
+
+@itemize
+@item
+@iter{}'s syntax is more Lisp-like than @code{loop}'s, having a higher
+density of parens.
+
+@item
+The current implementation of @iter{}, unlike the current version of
+@code{loop} (as documented in @emph{Common Lisp, 2nd Ed.}), is
+extensible (see @ref{Rolling Your Own}).
+
+@item
+@code{loop} puts the updates of all driver variables at the top of the
+loop; @iter{} leaves them where the driver clauses appear.
+
+@item
+While for the most part @iter{} clauses that resemble @code{loop}
+clauses behave similarly, there are some differences. For instance,
+there is no @code{for@dots{} =@dots{} then} in @iter{}; instead use
+@code{for@dots{} initially@dots{} then}.
+
+@item
+@code{loop} binds the variable @code{it} at certain times to allow
+pseudo-English expressions like @code{when @var{expr} return it}. In
+@iter{}, you must bind @var{expr} to a variable yourself. Note that
+@code{when @var{expr} return it} is like @code{thereis @var{expr}}
+except that the latter is an accumulation clause and therefore
+competes with other accumulations (remember ``Multiple Accumulations''
+in @ref{Other Features}).
+
+@c repeat different behaviour of |always| clause here?
+
+@item
+@code{loop} has a special @code{return} clause, illustrated in the
+previous item. @iter{} doesn't need one, since an ordinary Lisp
+@code{return} has the same effect.
+
+@item
+@code{loop} allows for parallel binding and stepping of iteration
+variables. @iter{} does not. (See @ref{Parallel Binding and
+Stepping}.)
+
+@item
+@code{loop} and @iter{} handle variable type declarations very
+differently. @code{loop} provides a special syntax for declaring
+variable types, and does not examine declarations. Moreover, the
+standard implementation of @code{loop} will generate declarations when
+none are requested. @iter{} parses standard Common Lisp type
+declarations, and will never declare a variable itself unless
+declarations are specifically requested.
+@end itemize
+
+@c ===================================================================
+@node Rolling Your Own
+@chapter Rolling Your Own
+
+@section Introduction
+
+@iter{} is extensible---you can write new clauses that embody new
+iteration patterns. You might want to write a new driver clause for a
+data structure of your own, or you might want to write a clause that
+collects or manipulates elements in a way not provided by @iter{}.
+
+This section describes how to write clauses for @iter{}. Writing a
+clause is like writing a macro. In fact, writing a clause @emph{is}
+writing a macro: since @iter{} code-walks its body and macroexpands,
+you can add new abstractions to @iter{} with good old @code{defmacro}.
+
+Actually, there are two extensions you can make to @iter{} that are
+even easier than writing a macro. They are adding a synonym for an
+existing clause and defining a driver clause for an indexable
+sequence. These can be done with @code{defsynonym} and
+@code{defclause-sequence}, respectively. See @ref{Extensibility
+Aids}.
+
+The rest of this section explains how to write macros that expand into
+@iter{} clauses. Here's how you could add a simplified version of
+@iter{}'s @code{multiply} clause, if @iter{} didn't already have one:
+
+@lisp
+(defmacro multiply (expr)
+ `(reducing ,expr by #'* initial-value 1))
+@end lisp
+
+If you found yourself summing the square of an expression often, you
+might want to write a macro for that. A first cut might be
+
+@lisp
+(defmacro sum-of-squares (expr)
+ `(sum (* ,expr ,expr)))
+@end lisp
+
+but if you are an experienced macro writer, you will realize that this
+code will evaluate @var{expr} twice, which is probably a bad idea. A
+better version would use a temporary:
+
+@lisp
+(defmacro sum-of-squares (expr)
+ (let ((temp (gensym)))
+ `(let ((,temp ,expr))
+ (sum (* ,temp ,temp)))))
+@end lisp
+
+Although this may seem complex, it is just the sort of thing you'd
+have to go through to write any macro, which illustrates the point of
+this section: if you can write macros, you can extend @iter{}.
+
+Our macros don't use @iter{}'s keyword-argument syntax. We could just
+use keywords with @code{defmacro}, but we would still not be using
+@iter{}'s clause indexing mechanism. Unlike Lisp, which uses just the
+first symbol of a form to determine what function to call, @iter{}
+individuates clauses by the list of required keywords. For instance,
+@code{for@dots{} in} and @code{for@dots{} in-vector} are different
+clauses implemented by distinct Lisp functions.
+
+To buy into this indexing scheme, as well as the keyword-argument
+syntax, use @code{defmacro-clause}:
+
+@itindex defmacro-clause
+@defmac defmacro-clause @v{arglist} @k{&body} @v{body}
+
+Defines a new @iter{} clause. @var{arglist} is a list of symbols
+which are alternating keywords and arguments. @code{&optional} may be
+used, and the list may be terminated by @code{&sequence}. @var{body}
+is an ordinary macro body, as with @code{defmacro}. If the first form
+of @var{body} is a string, it is considered a documentation string and
+will be shown by
+@code{display-iterate-clauses}. @code{defmacro-clause} will signal an
+error if defining the clause would result in an ambiguity. E.g. you
+cannot define the clause @code{for@dots{} from} because there would be
+no way to distinguish it from a use of the @code{for} clause with
+optional keyword @code{from}.
+@end defmac
+
+Here is @code{multiply} using @code{defmacro-clause}. The keywords
+are capitalized for readability.
+
+@lisp
+(defmacro-clause (MULTIPLY expr &optional INTO var)
+ `(reducing ,expr by #'* into ,var initial-value 1))
+@end lisp
+
+You don't have to worry about the case when @code{var} is not
+supplied; for any clause with an @code{into} keyword, saying
+@code{into nil} is equivalent to omitting the @code{into} entirely.
+
+As another, more extended example, consider the fairly common
+iteration pattern that involves finding the sequence element that
+maximizes (or minimizes) some function. @iter{} provides this as
+@code{finding@dots{} maximizing}, but it's instructive to see how to
+write it. Here, in pseudocode, is how you might write such a loop for
+maximizing a function F:
+
+@example
+@r{set variable MAX-VAL to NIL;}
+@r{set variable WINNER to NIL;}
+@r{for each element EL in the sequence}
+ @r{if MAX-VAL is NIL or F(EL) > MAX-VAL then}
+ @r{set MAX-VAL to F(EL);}
+ @r{set WINNER to EL;}
+ @r{end if;}
+@r{end for;}
+@r{return WINNER.}
+@end example
+
+Here is the macro:
+
+@lisp
+(defmacro-clause (FINDING expr MAXIMIZING func &optional INTO var)
+ (let ((max-val (gensym))
+ (temp1 (gensym))
+ (temp2 (gensym))
+ (winner (or var iterate::*result-var*)))
+ `(progn
+ (with ,max-val = nil)
+ (with ,winner = nil)
+ (cond
+ ((null ,max-val)
+ (setq ,winner ,expr)
+ (setq ,max-val (funcall ,func ,winner))
+ (t
+ (let* ((,temp1 ,expr)
+ (,temp2 (funcall ,func ,temp1)))
+ (when (> ,temp2 ,max-val)
+ (setq ,max-val ,temp2)
+ (setq ,winner ,temp1))))))
+ (finally (leave ,winner)))))
+@end lisp
+
+Note that if no @code{into} variable is supplied, we use
+@code{iterate::*result-var*}, which contains the internal variable
+into which all clauses place their results. If this variable is bound
+by some clause, then @iter{} will return its value automatically;
+otherwise, @code{nil} will be returned.
+
+@menu
+* Writing Drivers::
+* Extensibility Aids::
+* Subtleties::
+@end menu
+
+@c ===================================================================
+@node Writing Drivers
+@section Writing Drivers
+
+In principle, drivers can be implemented just as easily as other
+@iter{} clauses. In practice, they are a little harder to get right.
+As an example, consider writing a driver that iterates over all the
+elements of a vector, ignoring its fill-pointer. @code{for@dots{}
+in-vector} won't work for this, because it observes the fill-pointer.
+It's necessary to use @code{array-dimension} instead of @code{length}
+to obtain the size of the vector. Here is one approach:
+
+@lisp
+(defmacro-clause (FOR var IN-WHOLE-VECTOR v)
+ "All the elements of a vector (disregards fill-pointer)"
+ (let ((vect (gensym))
+ (index (gensym)))
+ `(progn
+ (with ,vect = ,v)
+ (for ,index from 0 below (array-dimension ,vect 0))
+ (for ,var = (aref ,vect ,index)))))
+@end lisp
+
+Note that we immediately put @code{v} in a variable, in case it is an
+expression. Again, this is just good Lisp macrology. It also has a
+subtle effect on the semantics of the driver: @code{v} is evaluated
+only once, at the beginning of the loop, so changes to @code{v} in the
+loop have no effect on the driver. Similarly, the bounds for
+numerical iteration e.g. the above @code{array-dimension} are also
+evaluated once only. This is how all of @iter{}'s drivers work.
+
+There is an important point concerning the @code{progn} in this code.
+We need the @code{progn}, of course, because we are returning several
+forms, one of which is a driver. But @iter{} drivers must occur at
+top-level. Is this code in error? No, because @emph{top-level} is
+defined in @iter{} to include forms inside a @code{progn}. This is
+just the definition of top-level that Common Lisp uses, and for the
+same reason: to allow macros to return multiple forms at top-level.
+
+While our @code{for@dots{} in-whole-vector} clause will work, it is
+not ideal. In particular, it does not support generating. Do do so,
+we need to use @code{for@dots{} next} or @code{for@dots{} do-next}.
+The job is simplified by the @code{defmacro-driver} macro.
+
+@itindex defmacro-driver
+@defmac defmacro-driver @v{arglist} @k{&body} @v{body}
+
+Defines a driver clause in both the @code{for} and @code{generate}
+forms, and provides a parameter @code{generate} which @var{body} can
+examine to determine how it was invoked. @var{arglist} is as in
+@code{defmacro-clause}, and should begin with the symbol @code{for}.
+@end defmac
+
+With @code{defmacro-driver}, our driver looks like this:
+
+@lisp
+(defmacro-driver (FOR var IN-WHOLE-VECTOR v)
+ "All the elements of a vector (disregards fill-pointer)"
+ (let ((vect (gensym))
+ (end (gensym))
+ (index (gensym))
+ (kwd (if generate 'generate 'for)))
+ `(progn
+ (with ,vect = ,v)
+ (with ,end = (array-dimension ,vect 0))
+ (with ,index = -1)
+ (,kwd ,var next (progn (incf ,index)
+ (if (>= ,index ,end) (terminate))
+ (aref ,vect ,index))))))
+@end lisp
+
+We are still missing one thing: the @code{&sequence} keywords.
+We can get them easily enough, by writing
+
+@lisp
+(defmacro-driver (FOR var IN-WHOLE-VECTOR v &sequence)
+ @dots{})
+@end lisp
+
+We can now refer to parameters @code{from}, @code{to}, @code{by},
+etc. which contain either the values for the corresponding keyword, or
+@code{nil} if the keyword was not supplied. Implementing the right
+code for these keywords is cumbersome but not difficult; it is left as
+an exercise. But before you begin, see @code{defclause-sequence}
+below for an easier way.
+
+@c ===================================================================
+@node Extensibility Aids
+@section Extensibility Aids
+
+This section documents assorted features that may be of use in
+extending @iter{}.
+
+@itindex *result-var*
+@defvr {Unexported Variable} *result-var*
+
+Holds the variable that is used to return a value as a result of the
+@iter{} form. You may examine this and use it in a @code{with}
+clause, but you should not change it.
+@end defvr
+
+@itindex defsynonym
+@defmac defsynonym @v{syn} @v{word}
+
+Makes @var{syn} a synonym for the existing @iter{} keyword @var{word}.
+Only the first word in each clause can have synonyms.
+@end defmac
+
+@itindex defclause-sequence
+@defmac defclause-sequence @v{element-name} @v{index-name} @k{&key} @
+ @v{access-fn} @v{size-fn} @v{sequence-type} @
+ @v{element-type} @v{element-doc-string} @
+ @v{index-doc-string}
+
+Provides a simple way to define sequence clauses. Generates two
+clauses, one for iterating over the sequence's elements, the other for
+iterating over its indices. The first symbol of both clauses will
+have print-name @code{for}. @var{element-name} and @var{index-name}
+should be symbols. @var{element-name} is the second keyword of the
+element iterator (typically of the form
+@code{in-@var{sequence-type}}), and @var{index-name} is the second
+keyword of the index-iterator (typically of the form
+@code{index-of-@var{sequence-type}}). Either name may be @code{nil},
+in which case the corresponding clause is not defined. If both
+symbols are supplied, they should be in the same package. The
+@code{for} that begins the clauses will be in this package.
+
+@var{access-fn} is the function to be used to access elements of the
+sequence in the element iterator. The function should take two
+arguments, a sequence and an index, and return the appropriate
+element. @var{size-fn} should denote a function of one argument, a
+sequence, that returns its size. Both @var{access-fn} and
+@var{size-fn} are required for the element iterator, but only
+@var{size-fn} is needed for the index iterator.
+
+The @var{sequence-type} and @var{element-type} keywords are used to
+suggest types for the variables used to hold the sequence and the
+sequence elements, respectively. The usual rules about @iter{}'s
+treatment of variable type declarations apply (see @ref{Types and
+Declarations}).
+
+@var{element-doc-string} and @var{index-doc-string} are the
+documentation strings, for use with @code{display-iterate-clauses}.
+
+The generated element-iterator performs destructuring on the element
+variable.
+
+As an example, the above @code{for@dots{} in-whole-vector} example
+could have been written:
+
+@lisp
+(defclause-sequence IN-WHOLE-VECTOR INDEX-OF-WHOLE-VECTOR
+ :access-fn 'aref
+ :size-fn (lambda (v) (array-dimension v 0))
+ :sequence-type 'vector
+ :element-type t
+ :element-doc-string "Elements of a vector, disregarding fill-pointer"
+ :index-doc-string "Indices of vector, disregarding fill-pointer")
+@end lisp
+@end defmac
+
+@c ===================================================================
+@node Subtleties
+@section Subtleties
+
+There are some subtleties to be aware of when writing @iter{} clauses.
+First, the code returned by your macros may be @code{nconc}'ed into a
+list, so you should always returned freshly consed lists, rather than
+constants. Second, @iter{} matches clauses by using @code{eq} on the
+first symbol and @code{string=} on the subsequent ones, so the package
+of the first symbol of a clause is relevant. All of the clauses in
+this manual have their first word in the @iter{} package. You can use
+the package system in the usual way to shadow @iter{} clauses without
+replacing them.
+
+@c say more here, about the badness that only the first word of a
+@c clause is packagey.
+
+@c ===================================================================
+@node Non-portable Extensions to Iterate (Contribs)
+@chapter Non-portable Extensions to Iterate (Contribs)
+
+Currently, there is only one non-portable extension to iterate in the
+distribution: iterate-pg. If you have made an extension that depends
+on non-portable features, feel free to send them to
+@code{asf@@boinkor.net} for inclusion in the iterate distribution.
+
+@section An SQL query driver for iterate
+
+The pg package by Eric Marsden (see @url{http://cliki.net/pg})
+provides an interface to the PostgreSQL database. Using the
+@code{iterpg} extension, it is possible to handle the results of SQL
+queries using @code{iter}.
+
+This usage example should give you an idea of how to use it:
+
+@lisp
+(pg:with-pg-connection (c "somedb" "someuser")
+ (iter (for (impl version date) in-relation "select * from version"
+ on-connection *dbconn*)
+ (collect version)))
+@end lisp
+
+To use the extension via @acronym{ASDF}, simply make your system
+depend on the @code{iterate-pg} system instead of the @code{iterate} system. To
+load it manually, use:
+
+@lisp
+(asdf:oos 'asdf:load-op :iterate-pg)
+@end lisp
+
+@c ===================================================================
+@node Obtaining Iterate
+@chapter Obtaining @code{Iterate}
+
+@impnote{This chapter is very, very obsolete.}
+
+The information in this chapter is obsolete but included for
+completeness's sake; Currently, the most up-to-date information on
+@iter{} can be found at @url{http://boinkor.net/iterate.html}.
+
+@iter{} currently runs on Lisp Machines, and on HP's, Sun3's and
+Sparcstations under Lucid. @iter{} source and binaries are available
+at the MIT AI Lab in the subdirectories of @code{/src/local/lisplib/}.
+The source file, @code{iterate.lisp}, is also available for anonymous
+FTP in the directory @code{/com/fpt/pub/} on the machine
+@code{TRIX.AI.MIT.EDU} (Internet number 128.52.32.6). If you are
+unable to obtain @code{iterate} in one of these ways, send mail to
+@code{jba@@ai.mit.edu} and I will send you the source file.
+
+@iter{} resides in the @code{iterate} package (nickname @code{iter}).
+Just say @code{(use-package :iterate)} to make all the necessary
+symbols available. If a symbol is not exported, it appears in this
+manual with an ``@code{iterate::}'' prefix.
+
+Send bug reports to @code{bug-iterate@@ai.mit.edu}. The
+@code{info-iterate} mailing list will have notices of changes and
+problems; to have yourself added, send mail to
+@code{info-iterate-request@@ai.mit.edu}.
+
+@c ===================================================================
+@node Acknowledgements
+@chapter Acknowledgements
+
+Richard Waters provided invaluable criticism which spurred me to
+improve @iter{} greatly. As early users, David Clemens, Oren Etzioni
+and Jeff Siskind helped ferret out many bugs.
+
+@c ===================================================================
+@node Don't Loop Iterate
+@appendix Don't Loop, Iterate
+
+@quotation Note
+This appendix is a Texinfo conversion of Jonathan Amsterdam's Working
+Paper 324, MIT AI Lab entitled ``Don't Loop, Iterate.''
+@end quotation
+
+@section Introduction
+
+Above all the wonders of Lisp's pantheon stand its metalinguistic
+tools; by their grace have Lisp's acolytes been liberated from the
+rigid asceticism of lesser faiths. Thanks to Macro and kin, the
+jolly, complacent Lisp hacker can gaze through a fragrant cloud of
+setfs and defstructs at the emaciated unfortunates below, scraping out
+their meager code in inflexible notation, and sneer superciliously.
+It's a good feeling.
+
+But all's not joy in Consville. For---I beg your pardon, but---there
+really is no good way to @emph{iterate} in Lisp. Now, some are happy
+to map their way about, whether for real with @code{mapcar} and
+friends, or with the make-believe of Series; others are so satisfied
+with @code{do} it's a wonder they're not C hackers.@footnote{Hey,
+don't get mad---I'll be much more polite later, when the real paper
+starts.} Still others have gotten by with @code{loop}, but are
+getting tired of looking up the syntax in the manual over and over
+again. And in the elegant schemes of some, only tail recursion and
+lambdas figure. But that still leaves a sizeable majority of
+folk---well, me, at least---who would simply like to @emph{iterate},
+thank you, but in a way that provides nice abstractions, is
+extensible, and looks like honest-to-God Lisp.
+
+In what follows I describe a macro package, called @iter{}, that
+provides the power and convenient abstractions of @code{loop} but in a
+more syntactically palatable way. @code{iter} also has many features
+that @code{loop} lacks, like generators and better support for nested
+loops. @iter{} generates inline code, so it's more efficient than
+using the higher-order function approach. And @iter{} is also
+extensible---it's easy to add new clauses to its vocabulary in order
+to express new patterns of iteration in a convenient way.
+
+@c \iter\ is fully documented in AI Lab Memo No. 1236, \iman.
+
+@section More about @iter{}
+
+A Common Lisp programmer who wonders what's lacking with present-day
+iteration features would do well to consider @code{setf}. Of course,
+@code{setf} doesn't iterate, but it has some other nice properties.
+It's easy to use, for one thing. It's extensible---you can define new
+@code{setf} methods very easily, so that @code{setf} will work with
+new forms. @code{setf} is also efficient, turning into code that's as
+good as anyone could write by hand. Arguably, @code{setf} provides a
+nice abstraction: it allows you to view value-returning forms, like
+@code{(car @dots{})} or @code{(get @dots{})} as locations that can be
+stored into. Finally and most obviously, @code{setf} @emph{looks}
+like Lisp; it's got a syntax right out of @code{setq}.
+
+@iter{} attempts to provide all of these properties. Here is a simple
+use of @iter{} that returns all the elements of @code{num-list} that
+are greater than three:
+
+@lisp
+(iterate (for el in num-list)
+ (when (> el 3)
+ (collect el)))
+@end lisp
+
+An @iter{} form consists of the symbol @iter{} followed by some Lisp
+forms. Any legal Lisp form is allowed, as well as certain forms that
+@iter{} treats specially, called @emph{clauses}. @code{for@dots{}in}
+and @code{collect} are the two clauses in the above example. An
+@iter{} clause can appear anywhere a Lisp form can appear; @iter{}
+walks its body, looking inside every form, processing @iter{} clauses
+when it finds them. It even expands macros, so you can write macros
+that contain @iter{} clauses. Almost all clauses use the syntax of
+function keyword-argument lists: alternating keywords and arguments.
+@iter{} keywords don't require a preceding colon, but you can use one
+if you like.
+
+@iter{} provides many convenient iteration abstractions, most of them
+familiar to @code{loop} users. Iteration-driving clauses (those
+beginning with @code{for}) can iterate over numbers, lists, arrays,
+hashtables, packages and files. There are clauses for collecting
+values into a list, summing and counting, maximizing, finding maximal
+elements, and various other things. Here are a few examples, for
+extra flavor.
+
+To sum a list of numbers:
+
+@lisp
+(iterate (for i in list)
+ (sum i))
+@end lisp
+
+To find the length of the shortest element in a list:
+
+@lisp
+(iterate (for el in list)
+ (minimize (length el)))
+@end lisp
+
+To find the shortest element in a list:
+
+@lisp
+(iterate (for el in list)
+ (finding el minimizing (length el)))
+@end lisp
+
+To return @code{t} only if every other element of a list is odd:
+
+@lisp
+(iterate (for els on list by #'cddr)
+ (always (oddp (car els))))
+@end lisp
+
+To split an association list into two separate lists (this example
+uses @iter{}'s ability to do destructuring):
+
+@lisp
+(iterate (for (key . item) in alist)
+ (collect key into keys)
+ (collect item into items)
+ (finally (return (values keys items))))
+@end lisp
+
+@section Comparisons With Other Iteration Methods
+
+As with any aspect of coding, how to iterate is a matter of taste. I
+do not wish to dictate taste or even to suggest that @iter{} is a
+``better'' way to iterate than other methods. I would, however, like
+to examine the options, and explain why I prefer @iter{} to its
+competitors.
+
+@subsection @code{do}, @code{dotimes} and @code{dolist}
+
+The @code{do} form has long been a Lisp iteration staple. It provides
+for binding of iteration variables, an end-test, and a body of
+arbitrary code. It can be a bit cumbersome for simple applications,
+but the most common special cases---iterating over the integers from
+zero and over the members of a list---appear more conveniently as
+@code{dotimes} and @code{dolist}.
+
+@code{do}'s major problem is that it provides no abstraction. For
+example, collection is typically handled by binding a variable to
+@code{nil}, pushing elements onto the variable, and @code{nreverse}ing
+the result before returning it. Such a common iteration pattern
+should be easier to write. (It is, using @code{mapcar}---but see
+below.)
+
+Another problem with @code{do}, for me at least, is that it's hard to
+read. The crucial end-test is buried between the bindings and the
+body, marked off only by an extra set of parens (and some
+indentation). It is also unclear, until after a moment of
+recollection, whether the end-test has the sense of a ``while'' or an
+``until.''
+
+Despite its flaws, @code{do} is superior to the iteration facilities
+of every other major programming language except CLU. Perhaps that is
+the reason many Lisp programmers don't mind using it.
+
+@subsection Tail Recursion
+@c FIXME: removed citation due to laziness
+
+Tail-recursive implementations of loops, like those found in Scheme
+code [SchemeBook], are parsimonious and illuminating. They have the
+advantage of looking like recursion, hence unifying the notation for
+two different types of processes. For example, if only tail-recursion
+is used, a loop that operates on list elements from front to back
+looks very much like a recursion that operates on them from back to
+front.
+
+However, using tail-recursion exclusively can lead to cumbersome code
+and a proliferation of functions, especially when one would like to
+embed a loop inside a function. Tail-recursion also provides no
+abstraction for iteration; in Scheme, that is typically done with
+higher-order functions.
+
+@subsection High-order Dunctions
+
+Lisp's age-old mapping functions, recently revamped for Common Lisp
+[CLM], are another favorite for iteration. They provide a pleasing
+abstraction, and it's easy to write new higher-order functions to
+express common iteration patterns. Common Lisp already comes with
+many such useful functions, for removing, searching, and performing
+reductions on lists. Another Common Lisp advantage is that these
+functions work on any sequence---vectors as well as lists.
+
+One problem with higher-order functions is that they are inefficient,
+requiring multiple calls on their argument function. While the the
+built-ins, like @code{map} and @code{mapcar}, can be open-coded, that
+cannot be so easily done for user-written functions. Also, using
+higher-order functions often results in the creation of intermediate
+sequences that could be avoided if the iteration were written out
+explicitly.
+
+The second problem with higher-order functions is very much a matter
+of personal taste. While higher-order functions are theoretically
+elegant, they are often cumbersome to read and write. The unpleasant
+sharp-quote required by Common Lisp is particularly annoying here, and
+even in Scheme, I find the presence of a lambda with its argument list
+visually distracting.
+
+Another problem is that it's difficult to express iteration of
+sequences of integers without creating such sequences explicitly as
+lists or arrays. One could resort to tail-recursion or
+@code{dotimes}---but then it becomes very messy to express double
+iterations where one driver is over integers. Multiple iteration is
+easy in @iter{}, as illustrated by the following example, which creates
+an alist of list elements and their positions:
+
+@lisp
+(iterate (for el in list)
+ (for i from 0)
+ (collect (cons el i)))
+@end lisp
+
+@subsection Streams and Generators
+
+For really heavy-duty iteration jobs, nothing less than a
+coroutine-like mechanism will do. Such mechanisms hide the state of
+the iteration behind a convenient abstraction. A @emph{generator} is
+a procedure that returns the next element in the iteration each time
+it is called. A @emph{stream} (in the terminology of [SchemeBook]) is
+a data structure which represents the iteration, but which computes
+the next element only on demand. Generators and streams support a
+similar style of programming. Here, for example, is how you might
+enumerate the leaves of a tree (represented as a Lisp list with atoms
+at the leaves) using streams:
+
+@lisp
+(defun tree-leaves (tree)
+ (if (atom tree)
+ (stream-cons tree empty-stream)
+ (stream-append (tree-leaves (car tree))
+ (tree-leaves (cdr tree)))))
+@end lisp
+
+Although @code{tree-leaves} looks like an ordinary recursion, it will
+only do enough work to find the first leaf before returning. The
+stream it returns can be accessed with @code{stream-car}, which will
+yield the (already computed) first leaf of the tree, or with
+@code{stream-cdr}, which will initiate computation of the next leaf.
+
+Such a computation would be cumbersome to write using @iter{}, or any
+of the other standard iteration constructs; in fact, it is not even
+technically speaking an iteration, if we confine that term to
+processes that take constant space and linear time. Streams, then,
+are definitely more powerful than standard iteration machinery.
+
+Unfortunately, streams are very expensive, since they must somehow
+save the state of the computation. Generators are typically cheaper,
+but are less powerful and still require at least a function call. So
+these powerful tools should be used only when necessary, and that is
+not very often; most of the time, ordinary iteration suffices.
+
+There is one aspect of generators that @iter{} can capture, and that
+is the ability to produce elements on demand. Say we wish to create
+an alist that pairs the non-null elements of a list with the positive
+integers. We saw above that it is easy to iterate over a list and a
+series of numbers simultaneously, but here we would like to do
+something a little different: we want to iterate over the list of
+elements, but only draw a number when we need one (namely, when a list
+element is non-null). The solution employs the @iter{} @code{generate}
+keyword in place of @code{for} and the special clause @code{next}:
+
+@lisp
+(iterate (for el in list)
+ (generate i from 1)
+ (if el
+ (collect (cons el (next i)))))
+@end lisp
+
+Using @code{next} with any driver variable changes how that driver
+works. Instead of supplying its values one at a time on each
+iteration, the driver computes a value only when a @code{next} clause
+is executed. This ability to obtain values on demand greatly
+increases @iter{}'s power. Here, @code{el} is set to the next element
+of the list on each iteration, as usual; but @code{i} is set only when
+@code{(next i)} is executed.
+
+@subsection Series
+
+Richard C. Waters has developed a very elegant notation called Series
+which allows iteration to be expressed as sequence-mapping somewhat in
+the style of APL, but which compiles to efficient looping code
+[Series].
+
+My reasons for not using Series are, again, matters of taste. Like
+many elegant notations, Series can be somewhat cryptic. Understanding
+what a Series expression does can require some effort until one has
+mastered the idiom. And if you wish to share your code with others,
+they will have to learn Series as well. @iter{} suffers from this
+problem to some extent, but since the iteration metaphor it proposes
+is much more familiar to most programmers than that of Series, it is
+considerably easier to learn and read.
+
+@subsection @code{Prog} and @code{Go}
+
+Oh, don't be silly.
+
+@subsection @code{Loop}
+
+@code{loop} is the iteration construct most similar to @iter{} in
+appearance. @code{loop} is a macro written originally for MacLisp and
+in widespread use [Loop]. It has been adopted as part of Common Lisp.
+@code{loop} provides high-level iteration with abstractions for
+collecting, summing, maximizing and so on. Recall our first @iter{}
+example:
+
+@lisp
+(iterate (for el in num-list)
+ (when (> el 3)
+ (collect el)))
+@end lisp
+
+Expressed with \looP, it would read
+
+@lisp
+(loop for el in list
+ when (> el 3)
+ collect el)
+@end lisp
+
+The similarity between the two macros should immediately be apparent.
+Most of @iter{}'s clauses were borrowed from @code{loop}. But
+compared to @iter{}, @code{loop} has a paucity of parens. Though
+touted as more readable than heavily-parenthesized code, @code{loop}'s
+Pascalish syntax creates several problems. First, many
+dyed-in-the-wool Lisp hackers simply find it ugly. Second, it
+requires learning the syntax of a whole new sublanguage. Third, the
+absence of parens makes it hard to parse, both by machine and, more
+importantly, by human. Fourth, one often has to consult the manual to
+recall lesser-used aspects of the strange syntax. Fifth, there is no
+good interface with the rest of Lisp, so @code{loop} clauses cannot
+appear inside Lisp forms and macros cannot expand to pieces of
+@code{loop}. And Sixth, pretty-printers and indenters that don't know
+about @code{loop} will invariably display it wrongly. This is
+particularly a problem with program-editor indenters. A reasonably
+clever indenter, like that of Gnu Emacs, can indent nearly any normal
+Lisp form correctly, and can be easily customized for most new forms.
+But it can't at present handle @code{loop}. The syntax of @iter{} was
+designed to keep parens to a minimum, but conform close enough to Lisp
+so as not to confuse code-display tools. Gnu Emacs indents @iter{}
+reasonably with no modifications.
+
+Indenting is a mere annoyance; @code{loop}'s lack of extensibility is
+a more serious problem. The original @code{loop} was completely
+extensible, but the Symbolics version only provides for the definition
+of new iteration-driving clauses, and the Common Lisp specification
+does not have any extension mechanism. But extensibility is a boon.
+Consider first the problem of adding the elements of a list together,
+which can be accomplished with @iter{} by
+
+@lisp
+(iterate (for el in list)
+ (sum el))
+@end lisp
+
+and in @code{loop} with
+
+@lisp
+(loop for el in list
+ sum el)
+@end lisp
+
+But now, say that you wished to compute the sum of the square roots of
+the elements. You could of course write, in either @code{loop} or
+@iter{},
+
+@lisp
+(iterate (for el in list)
+ (sum (sqrt el)))
+@end lisp
+
+But perhaps you find yourself writing such loops often enough to make
+it worthwhile to create a new abstraction. There is nothing you can
+do in @code{loop}, but in @iter{} you could simply write a macro:
+
+@lisp
+(defmacro (sum-of-sqrts expr &optional into-var)
+ `(sum (sqrt ,expr) into ,into-var))
+@end lisp
+
+@code{sum-of-sqrts} is a perfectly ordinary Lisp macro. Since @iter{}
+expands all macros and processes the results, @code{(sum-of-sqrts el)}
+will behave exactly as if we'd written @code{(sum (sqrt el))}.
+
+There's also a way to define macros that use @iter{}'s clause syntax.
+@c removed citation again
+
+@c Just to beat a dead horse, I'd like to point out that there's no
+@c way to define {\lisp for...maximizing} in \looP.\footnote{In fact,
+@c it was in part the frustration of knowing that \looP\ could
+@c generate code to maximize a value, but could not be easily altered
+@c to supply the element associated with that maximum, that prompted
+@c me to write \iter.}
+
+@section Implementation
+
+A Common Lisp implementation of @iter{} has existed for well over a
+year. It runs under Lucid for HP 300's, Sun 3's and SPARCstations,
+and on Symbolics Lisp machines.
+@c See \iman\ for details.
+
+@section Conclusion
+
+Iteration is a matter of taste. I find @iter{} more palatable than
+other iteration constructs: it's more readable, more efficient than
+most, provides nice abstractions, and can be extended.
+
+If you're new to Lisp iteration, start with @iter{}---look before you
+@code{loop}. If you're already using @code{loop} and like the power
+that it offers, but have had enough of its syntax and inflexibility,
+then my advice to you is, don't @code{looo}---@iter{}.
+
+@section Acknowledgments
+
+Thanks to David Clemens for many helpful suggestions and for the
+egregious pun near the end. Conversations with Richard Waters
+prompted me to add many improvements to @iter{}. Alan Bawden, Sundar
+Narasimhan, and Jerry Roylance also provided useful comments. David
+Clemens and Oren Etzioni shared with me the joys of beta-testing.
+
+@section Bibliography
+
+@itemize
+@item
+[SchemeBook] Abelson, Harold and Gerald Jay Sussman. @emph{Structure
+and Interpretation of Computer Programs.} Cambridge, MA: The MIT
+Press, 1985.
+
+@item
+[Loop] ``The loop Iteration Macro.'' In @emph{Symbolics Common
+Lisp---Language Concepts}, manual 2A of the Symbolics documentation,
+pp. 541--567.
+
+@item
+[CLM] Steele, Guy L. @emph{Common Lisp: The Language}. Bedford, MA:
+Digital Press, 1984.
+
+@item
+[Series] Waters, Richard C. @emph{Optimization of Series Expressions:
+Part I: User's Manual for the Series Macro Package}. MIT AI Lab Memo
+No. 1082.
+@end itemize
+
+@c ===================================================================
+@node Comprehensive Index
+@unnumbered Index
+@printindex cp
+
+@bye
diff -rN -u old-iterate/doc/style.css new-iterate/doc/style.css
--- old-iterate/doc/style.css 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/style.css 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,48 @@
+body {font-family: century schoolbook, serif;
+ line-height: 1.3;
+ padding-left: 5em; padding-right: 1em;
+ padding-bottom: 1em; max-width: 60em;}
+table {border-collapse: collapse}
+span.roman { font-family: century schoolbook, serif; font-weight: normal; }
+h1, h2, h3, h4, h5, h6 {font-family: Helvetica, sans-serif}
+/*h4 {padding-top: 0.75em;}*/
+dfn {font-family: inherit; font-variant: italic; font-weight: bolder }
+kbd {font-family: monospace; text-decoration: underline}
+/*var {font-family: Helvetica, sans-serif; font-variant: slanted}*/
+var {font-variant: slanted;}
+td {padding-right: 1em; padding-left: 1em}
+sub {font-size: smaller}
+.node {padding: 0; margin: 0}
+
+.lisp { font-family: monospace;
+ background-color: #F4F4F4; border: 1px solid #AAA;
+ padding-top: 0.5em; padding-bottom: 0.5em; }
+
+/* coloring */
+
+.lisp-bg { background-color: #F4F4F4 ; color: black; }
+.lisp-bg:hover { background-color: #F4F4F4 ; color: black; }
+
+.symbol { font-weight: bold; color: #770055; background-color : transparent; border: 0px; margin: 0px;}
+a.symbol:link { font-weight: bold; color : #229955; background-color : transparent; text-decoration: none; border: 0px; margin: 0px; }
+a.symbol:active { font-weight: bold; color : #229955; background-color : transparent; text-decoration: none; border: 0px; margin: 0px; }
+a.symbol:visited { font-weight: bold; color : #229955; background-color : transparent; text-decoration: none; border: 0px; margin: 0px; }
+a.symbol:hover { font-weight: bold; color : #229955; background-color : transparent; text-decoration: none; border: 0px; margin: 0px; }
+.special { font-weight: bold; color: #FF5000; background-color: inherit; }
+.keyword { font-weight: bold; color: #770000; background-color: inherit; }
+.comment { font-weight: normal; color: #007777; background-color: inherit; }
+.string { font-weight: bold; color: #777777; background-color: inherit; }
+.character { font-weight: bold; color: #0055AA; background-color: inherit; }
+.syntaxerror { font-weight: bold; color: #FF0000; background-color: inherit; }
+span.paren1 { font-weight: bold; color: #777777; }
+span.paren1:hover { color: #777777; background-color: #BAFFFF; }
+span.paren2 { color: #777777; }
+span.paren2:hover { color: #777777; background-color: #FFCACA; }
+span.paren3 { color: #777777; }
+span.paren3:hover { color: #777777; background-color: #FFFFBA; }
+span.paren4 { color: #777777; }
+span.paren4:hover { color: #777777; background-color: #CACAFF; }
+span.paren5 { color: #777777; }
+span.paren5:hover { color: #777777; background-color: #CAFFCA; }
+span.paren6 { color: #777777; }
+span.paren6:hover { color: #777777; background-color: #FFBAFF; }
diff -rN -u old-iterate/doc/tex/GNUmakefile new-iterate/doc/tex/GNUmakefile
--- old-iterate/doc/tex/GNUmakefile 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/tex/GNUmakefile 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,27 @@
+SOURCES=iterate-bare.tex iterate-manual.tex
+DUMMY_INDEXES=iterate-manual.ind
+MKIDX=makeindex
+MKIDXFLAGS=-l
+LATEX=latex
+
+all: iterate-bare.pdf iterate-manual.pdf iterate-bare.ps iterate-manual.ps
+
+%.dvi: %.tex
+ touch $*.ind $*.idx
+ ${LATEX} $<
+ ${MKIDX} ${MKIDXFLAGS} $*.idx
+ ${LATEX} $<
+
+%.ps: %.dvi
+ dvips -o $@ $*.dvi
+
+%.pdf: %.dvi
+ dvipdf $*.dvi $@
+
+clean:
+ rm -f *.dvi *.log *.aux *.ind *.idx *.toc *.auxs *.ilg
+
+shiny: clean
+ rm -f *.ps *.pdf
+
+# arch-tag: "c8f080e3-313c-11d8-abb9-000c76244c24"
diff -rN -u old-iterate/doc/tex/aimemo.sty new-iterate/doc/tex/aimemo.sty
--- old-iterate/doc/tex/aimemo.sty 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/tex/aimemo.sty 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,250 @@
+% Use the full page
+%
+\oddsidemargin 18pt
+\evensidemargin 18pt
+\topmargin 0pt
+\textheight 595pt
+\textwidth 432pt
+
+% Topheading supplies left and right flushed headings for the
+% lrheading command.
+%
+\def\topheadings#1#2{\def\@toplefthead{#1}\def\@toprighthead{#2}}
+
+% Page style: lrheadings
+% put text suplied by the topheadings command in the left and
+% right corners of the topheading.
+%
+\def\ps@lrheadings{%
+\def\@oddhead{\hbox{}\sl\@toplefthead\hfil\sl\@toprighthead}%
+\def\@evenhead{\sl\@toplefthead\hfil\sl\@toprighthead\hbox{}}%
+\def\@oddfoot{\hbox{}\hfil\rm\thepage\hfil}%
+\def\@evenfoot{\hbox{}\hfil\rm\thepage\hfil}}
+
+% Page style: footpagenumber
+% put nothing in header and center the page number in the footer.
+%
+\def\ps@footpagenumber{%
+\def\@oddhead{}\def\@evenhead{}%
+\def\@oddfoot{\hbox{}\hfil\rm\thepage\hfil}%
+\def\@evenfoot{\hbox{}\hfil\rm\thepage\hfil}}
+
+% \skipline leaves a blank line realitive to the size of the current
+% font.
+%
+\def\skipline{\vskip 2em}
+
+
+%
+% get the title page correct
+%
+
+% set these to do something
+\def\writtenby{Sundar Narasimhan}
+\def\contractno{Fill in appropriate ARPA/ONR contract no.}
+\def\AIMEMO #1#2#3{ %
+\begin{titlepage}
+\begin{center}
+MASSACHUSETTS INSTITUTE OF TECHNOLOGY\\
+ARTIFICIAL INTELLIGENCE LABORATORY
+\end{center}
+\vskip 1in
+\hbox to \hsize{A.I.Memo No. #1 \hfill \shortdate}
+\vskip 1in
+\begin{center}
+{\bf #2}
+\end{center}
+\vskip 0.5in
+\begin{center}
+\writtenby
+\end{center}
+\vskip 1in
+{\bf Abstract: } #3
+\hbox to \hsize{\hrulefill} % draw a line
+\contractno
+\end{titlepage}
+}
+
+%
+% Argument convention - same as before
+%
+\def\AIWORKINGPAPER #1#2#3{ %
+\begin{titlepage}
+\begin{center}
+MASSACHUSETTS INSTITUTE OF TECHNOLOGY\\
+ARTIFICIAL INTELLIGENCE LABORATORY
+\end{center}
+\vskip 1in
+\hbox to \hsize{Working Paper No. #1 \hfill \shortdate}
+\vskip 1in
+\begin{center}
+{\bf #2}
+\end{center}
+\vskip 0.5in
+\begin{center}
+\writtenby
+\end{center}
+\vskip 1.5in
+{\bf Abstract: } #3
+\hbox to \hsize{\hrulefill} % draw a line
+A.I.Lab Working Papers are produced for internal circulation and may
+contain information that is, for example, too preliminary or too detailed
+for formal publication. It is not intended that they should be considered
+papers to which reference can be made in the literature.
+\end{titlepage}
+}
+
+% stuff to change the format of figures
+%
+% change parameters to position floats
+%
+\renewcommand{\topfraction}{.9}
+\renewcommand{\bottomfraction}{.9}
+\renewcommand{\textfraction}{.1}
+\renewcommand{\floatpagefraction}{.8}
+\setcounter{totalnumber}{10}
+\setcounter{topnumber}{10}
+\setcounter{bottomnumber}{10}
+
+%
+% The new definition for chapterhead
+%
+%\def\@chapapp{\sf Section}
+\def\@makechapterhead#1{ \vspace*{10pt} { \parindent 0pt \raggedright
+\hfill \bf \hfill \thechapter. \ #1\par
+\nobreak \vskip 5pt \hrule
+\nobreak \vskip 40pt }}
+
+%
+% new section commands
+%
+\def\section{\@startsection {section}{1}{\z@}{3.5ex plus 1ex minus
+ .2ex}{2.3ex plus .2ex}{\bf}}
+\def\subsection{\@startsection{subsection}{2}{\z@}{3.25ex plus 1ex minus
+ .2ex}{1.5ex plus .2ex}{\bf}}
+\def\subsubsection{\@startsection{subsubsection}{3}{\z@}{3.25ex plus 1ex minus
+ .2ex}{1.5ex plus .2ex}{\normalsize\bf}}
+\def\paragraph{\@startsection
+ {paragraph}{4}{\z@}{3.25ex plus 1ex minus .2ex}{-1em}{\normalsize\bf}}
+\def\subparagraph{\@startsection
+ {subparagraph}{4}{\parindent}{3.25ex plus 1ex minus
+ .2ex}{-1em}{\normalsize\bf}}
+
+%
+% The new quotation environment
+%
+% we use the peni font that looks rather nice.
+%\font\peni=peni10
+%\def\myquot#1{{\hbox{}
+%\hfill\parbox{3.5in}{\raggedright{\peni #1}}
+% \\*[\parskip]}\par}
+
+
+%\def\quotauth#1{\hbox to \hsize{\hfill \small #1 \\} \par}
+
+% Date and time macros
+\newcount\hour \newcount\minute
+\hour=\the\time \minute=\the\time
+\divide\hour by 60 \multiply\hour by 60%
+\advance\minute by -\hour \divide\hour by 60%
+\def\daytime{\number\hour:\ifnum \minute<10 0\fi\number\minute}%
+\def\monthname {\ifcase\month \or
+ Jan\or Feb\or Mar\or Apr\or May\or Jun\or
+ Jul\or Aug\or Sep\or Oct\or Nov\or Dec\fi}%
+\def\date{\monthname~\number\day,~\number\year}%
+\def\datetime{\monthname~\number\day,~\number\year~[\daytime]}%
+\def\slashdate{\number\month/\number\day/\number\year}%
+\def\slashdatetime{\number\month/\number\day/\number\year~[\daytime]}%
+
+% the new list environments - works only for top level environments
+\newenvironment{alphenumerate}{\def\labelenumi{(\alph{enumi})}\begin{enumerate}}{\end{enumerate}}
+
+\newenvironment{romanenumerate}{\def\labelenumi{\roman{enumi}.}\begin{enumerate}}{\end{enumerate}}
+
+\newenvironment{Romanenumerate}{\def\labelenumi{\Roman{enumi}.}\begin{enumerate}}{\end{enumerate}}
+
+\newenvironment{Alphenumerate}{\def\labelenumi{(\Alph{enumi})}\begin{enumerate}}{\end{enumerate}}
+
+% Date and time macros
+\newcount\hour \newcount\minute
+\hour=\the\time \minute=\the\time
+\divide\hour by 60 \multiply\hour by 60%
+\advance\minute by -\hour \divide\hour by 60%
+\def\daytime{\number\hour:\ifnum \minute<10 0\fi\number\minute}%
+\def\monthname {\ifcase\month \or
+ Jan\or Feb\or Mar\or Apr\or May\or Jun\or
+ Jul\or Aug\or Sep\or Oct\or Nov\or Dec\fi}%
+\def\longmonthname {\ifcase\month \or
+ January\or February\or March\or April\or May\or June\or
+ July\or August\or September\or October\or November\or December\fi}%
+\def\date{\monthname~\number\day,~\number\year~[\daytime]}%
+\def\slashdate{\number\month/\number\day/\number\year}%
+\def\shortdate{\longmonthname,~\number\year}%
+
+% Math macros
+\def\v#1{\mbox{$\bf #1$}}
+\def\cross{\times}
+\def\jac_t{{\bf J}^{T}}
+\def\jac_inv{{\bf J}^{-1}}
+\def\jac{{\bf J}}
+
+% Float stuff
+%\def\@float#1{\@ifnextchar[{\@xfloat{#1}}{\edef\@tempa{\noexpand\@xfloat
+% {#1}[\csname fps@#1\endcsname]}\@tempa}}
+%
+%\def\@xfloat#1[#2]{\ifhmode \@bsphack\@floatpenalty -\@Mii\else
+% \@floatpenalty-\@Miii\fi\def\@captype{#1}\ifinner
+% \@parmoderr\@floatpenalty\z@
+% \else\@next\@currbox\@freelist{\@tempcnta\csname ftype@#1\endcsname
+% \multiply\@tempcnta\@xxxii\advance\@tempcnta\sixt@@n
+% \@tfor \@tempa :=#2\do
+% {\if\@tempa h\advance\@tempcnta \@ne\fi
+% \if\@tempa t\advance\@tempcnta \tw@\fi
+% \if\@tempa b\advance\@tempcnta 4\relax\fi
+% \if\@tempa p\advance\@tempcnta 8\relax\fi
+% }\global\count\@currbox\@tempcnta}\@fltovf\fi
+% \global\setbox\@currbox\vbox\bgroup
+% \boxmaxdepth\z@
+% \hsize\columnwidth \@parboxrestore}
+%
+%\def\end@float{\egroup
+% \ifnum\@floatpenalty <\z@
+% \@cons\@currlist\@currbox
+% \ifdim \ht\@currbox >\textheight
+% \ht\@currbox\textheight \fi
+% \global\@outputdonefalse
+% \ifnum\@floatpenalty < -\@Mii
+% \penalty\@floatpenalty
+% \if@outputdone\else\global\@outputdonetrue
+% \vbox{}\penalty\@floatpenalty\fi
+% \else \vadjust{\penalty \@floatpenalty}\@esphack\fi\fi}
+%
+%\def\@dblfloat#1{\if@twocolumn\else\@latexerr{Two-column float
+%on one-column page}\@ehd\fi
+%\@ifnextchar[{\@xdblfloat{#1}}{\@xdblfloat{#1}[tp]}}
+
+% line space commands (from dms.sty)
+\def\varspace#1{\def\baselinestretch{#1}\large\normalsize}
+\def\dspace{\def\baselinestretch{1.5}\large\normalsize}
+\def\mspace{\def\baselinestretch{1.25}\large\normalsize}
+\def\sspace{\def\baselinestretch{1.0}\large\normalsize}
+\def\tspace{\def\baselinestretch{.85}\large\normalsize}
+\let\double=\dspace
+\let\single=\sspace
+
+% Illustrate macros for latex - see GLR's working paper on the subject
+\newcommand{\psbox}[3]{%
+ \makebox[#1][l]{%
+ \parbox[b]{0.0in}{\vspace*{#2}}%
+ \special{psfile=#3}}}
+
+% 4.25in=306 ps points, 5.50 in = 396 ps points
+\newlength{\illheight}
+\newcommand{\illustratefile}[3]{%
+ \makebox[#1]{%
+ \setlength{\illheight}{#2}%
+ \raisebox{0.5\illheight}[\illheight][0.0in]{%
+ \special{psfile=#3 hoffset=-306 voffset=-396}}}}
+\endinput
+
+% arch-tag: "185f1ce2-313d-11d8-abb9-000c76244c24"
Binary files old-iterate/doc/tex/iterate-bare.pdf and new-iterate/doc/tex/iterate-bare.pdf differ
diff -rN -u old-iterate/doc/tex/iterate-bare.tex new-iterate/doc/tex/iterate-bare.tex
--- old-iterate/doc/tex/iterate-bare.tex 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/tex/iterate-bare.tex 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,474 @@
+\documentclass[12pt]{article}
+
+\newcommand{\lisp}{\tt}
+\newcommand{\iter}{{\lisp iterate}}
+\newcommand{\Iter}{{\lisp Iterate}}
+\newcommand{\Do}{{\lisp do}}
+\newcommand{\Doing}{{\lisp doing}}
+\newcommand{\looP}{{\lisp loop}}
+\newcommand{\LooP}{{\lisp Loop}}
+\newcommand{\setf}{{\lisp setf}}
+\newcommand{\iman}{{\em The Iterate Manual\/}}
+
+\begin{document}
+
+
+\title{Don't Loop, Iterate}
+\author{Jonathan Amsterdam}
+
+\maketitle
+
+\section{Introduction}
+
+Above all the wonders of Lisp's pantheon stand its metalinguistic
+tools; by their grace have Lisp's acolytes been liberated from the
+rigid asceticism of lesser faiths. Thanks to Macro and kin, the
+jolly, complacent Lisp hacker can gaze through a fragrant cloud of
+setfs and defstructs at the emaciated unfortunates below, scraping out
+their meager code in inflexible notation, and sneer superciliously.
+It's a good feeling.
+
+But all's not joy in Consville. For---I beg your pardon, but---there
+really is no good way to {\em iterate\/} in Lisp. Now, some are happy
+to map their way about, whether for real with {\lisp mapcar} and
+friends, or with the make-believe of Series; others are so satisfied
+with \Do\ it's a wonder they're not C hackers.\footnote{Hey, don't get
+mad---I'll be much more polite later, when the real paper starts.}
+Still others have gotten by with \looP, but are getting tired of
+looking up the syntax in the manual over and over again. And in the
+elegant schemes of some, only tail recursion and lambdas figure. But
+that still leaves a sizeable majority of folk---well, me, at
+least---who would simply like to {\em iterate,} thank you, but in a
+way that provides nice abstractions, is extensible, and looks like
+honest-to-God Lisp.
+
+In what follows I describe a macro package, called \iter, that
+provides the power and convenient abstractions of \looP\ but in a more
+syntactically palatable way. \iter\ also has many features that
+\looP\ lacks, like generators and better support for nested loops.
+\iter\ generates inline code, so it's more efficient than using the
+higher-order function approach. And \iter\ is also extensible---it's
+easy to add new clauses to its vocabulary in order to express new
+patterns of iteration in a convenient way.
+
+\iter\ is fully documented in AI Lab Memo No. 1236, \iman.
+
+\section{More about \Iter}
+
+A Common Lisp programmer who wonders what's lacking with present-day
+iteration features would do well to consider \setf. Of course,
+\setf\ doesn't iterate, but it has some other nice properties. It's
+easy to use, for one thing. It's extensible---you can define new
+\setf\ methods very easily, so that \setf\ will work with new forms.
+\setf\ is also efficient, turning into code that's as good as anyone
+could write by hand. Arguably, \setf\ provides a nice abstraction:
+it allows you to view value-returning forms, like {\lisp (car ...)} or
+{\lisp (get ...)} as locations that can be stored into. Finally and
+most obviously, \setf\ {\em looks\/} like Lisp; it's got a syntax
+right out of {\lisp setq}.
+
+\iter\ attempts to provide all of these properties. Here is a simple
+use of \iter\ that returns all the elements of {\lisp num-list}
+that are greater than three:
+
+\pagebreak[4]
+
+\begin{verbatim}
+(iterate (for el in num-list)
+ (when (> el 3)
+ (collect el)))
+\end{verbatim}
+
+An \iter\ form consists of the symbol \iter\ followed by some Lisp
+forms. Any legal Lisp form is allowed, as well as certain forms that
+\iter\ treats specially, called {\em clauses}. {\lisp for...in} and
+{\lisp collect} are the two clauses in the above example. An \iter\
+clause can appear anywhere a Lisp form can appear; \iter\ walks its
+body, looking inside every form, processing \iter\ clauses when it
+finds them. It even expands macros, so you can write macros that
+contain \iter\ clauses. Almost all clauses use the syntax of function
+keyword-argument lists: alternating keywords and arguments. \iter\
+keywords don't require a preceding colon, but you can use one if you
+like.
+
+\iter\ provides many convenient iteration abstractions, most of
+them familiar to \looP\ users. Iteration-driving clauses (those
+beginning with {\lisp for}) can iterate over numbers, lists, arrays,
+hashtables, packages and files. There are clauses for collecting
+values into a list, summing and counting, maximizing, finding maximal
+elements, and various other things. Here are a few examples, for
+extra flavor.
+
+\pagebreak[2]
+To sum a list of numbers:
+\begin{verbatim}
+(iterate (for i in list)
+ (sum i))
+\end{verbatim}
+
+\pagebreak[2]
+To find the length of the shortest element in a list:
+\begin{verbatim}
+(iterate (for el in list)
+ (minimize (length el)))
+\end{verbatim}
+
+\pagebreak[2]
+To find the shortest element in a list:
+\begin{verbatim}
+(iterate (for el in list)
+ (finding el minimizing (length el)))
+\end{verbatim}
+
+\pagebreak[2]
+To return {\lisp t} only if every other element of a list is odd:
+\begin{verbatim}
+(iterate (for els on list by #'cddr)
+ (always (oddp (car els))))
+\end{verbatim}
+
+\pagebreak[2]
+To split an association list into two separate lists (this example
+uses \iter's ability to do destructuring):
+\begin{verbatim}
+(iterate (for (key . item) in alist)
+ (collect key into keys)
+ (collect item into items)
+ (finally (return (values keys items))))
+\end{verbatim}
+
+
+\section{Comparisons With Other Iteration Methods}
+
+As with any aspect of coding, how to iterate is a matter of taste. I
+do not wish to dictate taste or even to suggest that \iter\ is a
+``better'' way to iterate than other methods. I would, however, like
+to examine the options, and explain why I prefer \iter\ to its
+competitors.
+
+\subsection{\Do, {\lisp dotimes} and {\lisp dolist}}
+
+The \Do\ form has long been a Lisp iteration staple. It provides for
+binding of iteration variables, an end-test, and a body of arbitrary
+code. It can be a bit cumbersome for simple applications, but
+the most common special cases---iterating over the integers
+from zero and over the members of a list---appear more conveniently as
+{\lisp dotimes} and {\lisp dolist}.
+
+\Do's major problem is that it provides no abstraction. For example,
+collection is typically handled by binding a variable to {\lisp nil},
+pushing elements onto the variable, and {\lisp nreverse}ing the
+result before returning it. Such a common iteration pattern should be
+easier to write. (It is, using {\lisp mapcar}---but see below.)
+
+Another problem with \Do, for me at least, is that it's hard to read.
+The crucial end-test is buried between the bindings and the body,
+marked off only by an extra set of parens (and some indentation). It
+is also unclear, until after a moment of recollection, whether the
+end-test has the sense of a ``while'' or an ``until.''
+
+Despite its flaws, \Do\ is superior to the iteration facilities of
+every other major programming language except CLU. Perhaps that is
+the reason many Lisp programmers don't mind using it.
+
+
+\subsection{Tail Recursion}
+% (check hyphenation)
+
+Tail-recursive implementations of loops, like those found in Scheme
+code \cite{SchemeBook}, are parsimonious and illuminating. They have
+the advantage of looking like recursion, hence unifying the notation
+for two different types of processes. For example, if only
+tail-recursion is used, a loop that operates on list elements from
+front to back looks very much like a recursion that operates on them
+from back to front.
+
+However, using tail-recursion exclusively can lead to cumbersome code
+and a proliferation of functions, especially when one would like to
+embed a loop inside a function. Tail-recursion also provides no
+abstraction for iteration; in Scheme, that is typically done with
+higher-order functions.
+
+
+\subsection{Higher-order Functions}
+
+Lisp's age-old mapping functions, recently revamped for Common Lisp
+\cite{CLM}, are another favorite for iteration. They provide a
+pleasing abstraction, and it's easy to write new higher-order
+functions to express common iteration patterns. Common Lisp already
+comes with many such useful functions, for removing, searching, and
+performing reductions on lists. Another Common Lisp advantage is that
+these functions work on any sequence---vectors as well as lists.
+
+One problem with higher-order functions is that they are inefficient,
+requiring multiple calls on their argument function. While the the
+built-ins, like {\lisp map} and {\lisp mapcar}, can be open-coded,
+that cannot be so easily done for user-written functions. Also, using
+higher-order functions often results in the creation of intermediate
+sequences that could be avoided if the iteration were written out
+explicitly.
+
+The second problem with higher-order functions is very much a matter
+of personal taste. While higher-order functions are theoretically
+elegant, they are often cumbersome to read and write. The unpleasant
+sharp-quote required by Common Lisp is particularly annoying here, and
+even in Scheme, I find the presence of a lambda with its argument list
+visually distracting.
+
+Another problem is that it's difficult to express iteration of
+sequences of integers without creating such sequences explicitly as
+lists or arrays. One could resort to tail-recursion or {\lisp
+dotimes}---but then it becomes very messy to express double
+iterations where one driver is over integers. Multiple iteration is
+easy in \iter, as illustrated by the following example, which creates
+an alist of list elements and their positions:
+
+{\samepage
+\begin{verbatim}
+(iterate (for el in list)
+ (for i from 0)
+ (collect (cons el i)))
+\end{verbatim}
+}
+
+
+\subsection{Streams and Generators}
+
+For really heavy-duty iteration jobs, nothing less than a
+coroutine-like mechanism will do. Such mechanisms hide the state of
+the iteration behind a convenient abstraction. A {\em generator\/} is
+a procedure that returns the next element in the iteration each time
+it is called. A {\em stream\/} (in the terminology of
+\cite{SchemeBook}) is a data structure which represents the iteration,
+but which computes the next element only on demand. Generators and
+streams support a similar style of programming. Here, for example, is
+how you might enumerate the leaves of a tree (represented as a Lisp
+list with atoms at the leaves) using streams:
+\begin{verbatim}
+(defun tree-leaves (tree)
+ (if (atom tree)
+ (stream-cons tree empty-stream)
+ (stream-append (tree-leaves (car tree))
+ (tree-leaves (cdr tree)))))
+\end{verbatim}
+
+Although {\lisp tree-leaves} looks like an ordinary recursion,
+it will only do enough work to find the first leaf before returning.
+The stream it returns can be accessed with {\lisp stream-car}, which
+will yield the (already computed) first leaf of the tree, or with
+{\lisp stream-cdr}, which will initiate computation of the next leaf.
+
+Such a computation would be cumbersome to write using \iter, or any of
+the other standard iteration constructs; in fact, it is not even
+technically speaking an iteration, if we confine that term to
+processes that take constant space and linear time. Streams, then,
+are definitely more powerful than standard iteration machinery.
+
+Unfortunately, streams are very expensive, since they must somehow
+save the state of the computation. Generators are typically cheaper,
+but are less powerful and still require at least a function call.
+So these powerful tools should be used only when necessary, and that
+is not very often; most of the time, ordinary iteration suffices.
+
+There is one aspect of generators that \iter\ can capture, and that is
+the ability to produce elements on demand. Say we wish to
+create an alist that pairs the non-null elements of a list with the
+positive integers. We saw above that it is easy to iterate over
+a list and a series of numbers simultaneously, but here we would like
+to do something a little different: we want to iterate over the list
+of elements, but only draw a number when we need one (namely, when a list
+element is non-null). The solution employs the \iter\ {\lisp generate}
+keyword in place of {\lisp for} and the special clause
+{\lisp next}:
+
+{\samepage
+\begin{verbatim}
+(iterate (for el in list)
+ (generate i from 1)
+ (if el
+ (collect (cons el (next i)))))
+\end{verbatim}
+}
+
+Using {\lisp next} with any driver variable changes how that driver
+works. Instead of supplying its values one at a time on each iteration,
+the driver computes a value only when a {\lisp next} clause is
+executed. This ability to obtain values on demand greatly increases
+\iter's power. Here, {\lisp el} is set to the next element of the
+list on each iteration, as usual; but {\lisp i} is set only when
+{\lisp (next i)} is executed.
+
+\subsection{Series}
+
+Richard C. Waters has developed a very elegant notation called Series
+which allows iteration to be expressed as sequence-mapping somewhat in
+the style of APL, but which compiles to efficient looping code
+\cite{Series}.
+
+My reasons for not using Series are, again, matters of taste. Like many
+elegant notations, Series can be somewhat cryptic. Understanding what a
+Series expression does can require some effort until one has mastered
+the idiom. And if you wish to share your code with others, they will
+have to learn Series as well. \iter\ suffers from this problem to some
+extent, but since the iteration metaphor it proposes is much more
+familiar to most programmers than that of Series, it is considerably
+easier to learn and read.
+
+\subsection{{\lisp Prog} and {\lisp Go}}
+
+Oh, don't be silly.
+
+
+\subsection{\LooP}
+
+\looP\ is the iteration construct most similar to \iter\ in
+appearance. \looP\ is a macro written originally for MacLisp and in
+widespread use \cite{Loop}. It has been adopted as part of Common
+Lisp. \looP\ provides high-level iteration with abstractions for
+collecting, summing, maximizing and so on. Recall our first \iter\
+example:
+
+\pagebreak[2]
+\begin{verbatim}
+(iterate (for el in num-list)
+ (when (> el 3)
+ (collect el)))
+\end{verbatim}
+
+\pagebreak[2]
+Expressed with \looP, it would read
+n
+\begin{verbatim}
+(loop for el in list
+ when (> el 3)
+ collect el)
+\end{verbatim}
+
+The similarity between the two macros should immediately be apparent.
+Most of \iter's clauses were borrowed from \looP. But compared to
+\iter, \looP\ has a paucity of parens. Though touted as more readable
+than heavily-parenthesized code, \looP's Pascalish syntax creates
+several problems. First, many dyed-in-the-wool Lisp hackers simply
+find it ugly. Second, it requires learning the syntax of a whole new
+sublanguage. Third, the absence of parens makes it hard to parse,
+both by machine and, more importantly, by human. Fourth, one often
+has to consult the manual to recall lesser-used aspects of the strange
+syntax. Fifth, there is no good interface with the rest of Lisp, so
+\looP\ clauses cannot appear inside Lisp forms and macros cannot
+expand to pieces of \looP. And Sixth, pretty-printers and indenters
+that don't know about \looP\ will invariably display it wrongly. This
+is particularly a problem with program-editor indenters. A reasonably
+clever indenter, like that of Gnu Emacs, can indent nearly any normal
+Lisp form correctly, and can be easily customized for most new forms.
+But it can't at present handle \looP. The syntax of \iter\ was
+designed to keep parens to a minimum, but conform close enough to Lisp
+so as not to confuse code-display tools. Gnu Emacs indents \iter\
+reasonably with no modifications.
+
+Indenting is a mere annoyance; \looP's lack of extensibility is a more
+serious problem. The original \looP\ was completely extensible, but
+the Symbolics version only provides for the definition of new
+iteration-driving clauses, and the Common Lisp specification does not
+have any extension mechanism. But extensibility is a boon. Consider
+first the problem of adding the elements of a list together, which can
+be accomplished with \iter\ by
+
+\pagebreak[3]
+\begin{verbatim}
+(iterate (for el in list)
+ (sum el))
+\end{verbatim}
+
+and in \looP\ with
+
+\begin{verbatim}
+(loop for el in list
+ sum el)
+\end{verbatim}
+
+But now, say that you wished to compute the sum of the square roots of the
+elements. You could of course write, in either \looP\ or \iter,
+
+\begin{verbatim}
+(iterate (for el in list)
+ (sum (sqrt el)))
+\end{verbatim}
+
+But perhaps you find yourself writing such loops often enough to make
+it worthwhile to create a new abstraction. There is nothing you can
+do in \looP, but in \iter\ you could simply write a macro:
+
+\begin{verbatim}
+(defmacro (sum-of-sqrts expr &optional into-var)
+ `(sum (sqrt ,expr) into ,into-var))
+\end{verbatim}
+
+{\lisp sum-of-sqrts} is a perfectly ordinary Lisp macro. Since
+\iter\ expands all macros and processes the results, {\lisp
+(sum-of-sqrts el)} will behave exactly as if we'd written {\lisp
+(sum (sqrt el))}.
+
+There's also a way to define macros that use \iter's clause syntax.
+It's fully documented in \iman.
+
+%Just to beat a dead horse, I'd like to point out that there's no way
+%to define {\lisp for...maximizing} in
+%\looP.\footnote{In fact, it was in part the frustration of knowing
+%that \looP\ could generate code to maximize a value, but could not be
+%easily altered to supply the element associated with that maximum,
+%that prompted me to write \iter.}
+
+\section{Implementation}
+
+A Common Lisp implementation of \iter\ has existed for well over a year.
+It runs under Lucid for HP 300's, Sun 3's and SPARCstations, and on
+Symbolics Lisp machines. See \iman\ for details.
+
+\section{Conclusion}
+
+Iteration is a matter of taste. I find \iter\ more palatable than
+other iteration constructs: it's more readable, more efficient than
+most, provides nice abstractions, and can be extended.
+
+If you're new to Lisp iteration, start with \iter---look before you
+\looP. If you're already using \looP\ and like the power that it
+offers, but have had enough of its syntax and inflexibility, then my
+advice to you is, don't \looP---\iter.
+
+\pagebreak
+
+\begin{flushleft}
+\bf Acknowledgements
+\end{flushleft}
+
+Thanks to David Clemens for many helpful suggestions and for the
+egregious pun near the end. Conversations with Richard Waters prompted
+me to add many improvements to \iter. Alan Bawden, Sundar Narasimhan,
+and Jerry Roylance also provided useful comments. David Clemens and
+Oren Etzioni shared with me the joys of beta-testing.
+
+\begin{thebibliography}{9}
+
+\bibitem{SchemeBook} Abelson, Harold and Gerald Jay Sussman. {\em
+Structure and Interpretation of Computer Programs.} Cambridge, MA: The
+MIT Press, 1985.
+
+
+\bibitem{Loop} ``The loop Iteration Macro.'' In {\em Symbolics Common
+Lisp---Language Concepts}, manual 2A of the Symbolics documentation,
+pp. 541--567.
+
+\bibitem{CLM} Steele, Guy L. {\em Common Lisp: The Language}.
+Bedford, MA: Digital Press, 1984.
+
+\bibitem{Series} Waters, Richard C. {\em Optimization of Series
+Expressions: Part I: User's Manual for the Series Macro Package}. MIT
+AI Lab Memo No. 1082.
+
+\end{thebibliography}
+
+\end{document}
+
+
+
+% arch-tag: "c0ff23d7-313c-11d8-abb9-000c76244c24"
Binary files old-iterate/doc/tex/iterate-manual.pdf and new-iterate/doc/tex/iterate-manual.pdf differ
diff -rN -u old-iterate/doc/tex/iterate-manual.tex new-iterate/doc/tex/iterate-manual.tex
--- old-iterate/doc/tex/iterate-manual.tex 1969-12-31 16:00:00.000000000 -0800
+++ new-iterate/doc/tex/iterate-manual.tex 2014-04-17 15:33:26.000000000 -0700
@@ -0,0 +1,2070 @@
+% Fix ``.'' spacing in lists
+\documentstyle[12pt,aimemo]{article}
+
+\setlength{\textwidth}{6.0in}
+\setlength{\oddsidemargin}{0.25in}
+\setlength{\evensidemargin}{0.25in}
+\setlength{\topmargin}{0pt}
+\setlength{\headsep}{24pt}
+\setlength{\textheight}{8.5in}
+
+\let\origpar=\par
+
+% somehow, LaTex fucks with things so that the plain Tex \obeyspaces
+% doesn't work. This is the same, except we use an mbox containing
+% a space instead of just a space.
+
+\newcommand{\spc}{\mbox{ }}
+\newcommand{\tAb}{\mbox{ }}
+\def\obspaces{\catcode`\ =\active\catcode`\^^I=\active}
+{\obspaces \global\let =\spc\global\let^^I=\tAb}
+
+\newenvironment{program}{\medskip\samepage\tt\obeylines\obspaces}{\medskip}
+
+% use | for \tt
+\catcode`\|=13
+\newif\ifvbar
+\def|{\ifvbar
+ \endgroup\vbarfalse
+ \else
+ \begingroup\tt\vbartrue
+ \fi}
+
+
+
+\newcommand{\lisp}{\tt}
+\newcommand{\iter}{|iterate|}
+\newcommand{\iterpg}{|iterate-pg|}
+\newcommand{\setf}{|setf|}
+\newcommand{\nil}{|nil|}
+\newcommand{\nonnil}{non-\nil}
+\newcommand{\opt}{{\lisp \&optional}}
+\newcommand{\yields}{$\Rightarrow$}
+
+
+
+\newbox\Dots
+\setbox\Dots=\hbox{\small ...}
+\renewcommand{\dots}{\copy\Dots}
+
+% Here's a way to define an environment which will treat all
+% paragraphs inside it in the same manner. It's, as near as I can
+% figure, the way that Latex does things. Using \everypar won't work;
+% apparently Latex resets that a lot. What you have to do is: at the
+% top of the file do \let\origpar=\par. In the
+% begin part of the environment, do the parshape (or whatever), then say
+% \def\par{{\origpar}}. The extra braces are necessary. That's all
+% you have to do; at the end of the environment things will return to
+% normal automatically. Why does this all work? I have no idea.
+% Another important thing: there should be a blank line (i.e. a \par)
+% between the end of the last paragraph and the \end{environment}.
+
+\newlength{\clindent}
+\setlength{\clindent}{0.5in}
+\newlength{\clparindent}
+\setlength{\clparindent}{\parindent}
+
+\newenvironment{clauses}{\advance\linewidth -\parindent
+ \hangindent\clindent\relax
+ \hangafter=0
+ \parindent=0pt
+ \def\par{{\origpar}}}{}
+
+\newcommand{\cpar}{\hspace \clparindent}
+
+\newcommand{\startitem}{\bigskip\pagebreak[3]}
+\newcommand{\finishitem}{\smallskip}
+
+\newcommand{\clause}[1]{\startitem\Clause{#1}\finishitem}
+\newcommand{\Clause}[1]{\hbox{#1}}
+\newcommand{\clindex}[1]{\index{{\lisp #1}}}
+\newcommand{\clindexx}[2]{\index{{\lisp #1\dots #2}}}
+\newcommand{\clindexxx}[3]{\index{{\lisp #1\dots #2\dots #3}}}
+\newcommand{\clausex}[2]{\startitem\Clausex{#1}{#2}\finishitem}
+\newcommand{\Clausex}[2]{\Clause{|#1| #2}\clindex{#1}}
+
+\newcommand{\defvar}[1]{\startitem\deff{#1}{}{Variable}\finishitem}
+\newcommand{\defunexpvar}[1]{\startitem\deffnoindex{iterate::#1}{}{Variable}
+ \lispindex{#1}\finishitem}
+\newcommand{\defun}[2]{\startitem\deff{#1}{#2}{Function}\finishitem}
+\newcommand{\defmacro}[2]{\startitem\deff{#1}{#2}{Macro}\finishitem}
+\newcommand{\defunx}[3]{\startitem\deffx{#1}{#2}{#3}{Function}\finishitem}
+\newcommand{\defmacrox}[3]{\startitem\deffx{#1}{#2}{#3}{Macro}\finishitem}
+\newcommand{\defunxx}[4]{\startitem\deffxx{#1}{#2}{#3}{#4}{Function}\finishitem}
+\newcommand{\defmacroxx}[4]{\startitem\deffxx{#1}{#2}{#3}{#4}{Macro}\finishitem}
+
+\newcommand{\deff}[3]{\deffnoindex{#1}{#2}{#3}\lispindex{#1}}
+\newcommand{\deffnoindex}[3]{\hbox to \hsize{{\tt #1} {\it #2}\hfill [{\it #3}]}}
+\newcommand{\deffx}[4]{\deff{#1}{#2}{#4}\moreargs{#1}{#3}}
+\newcommand{\deffxx}[5]{\deffx{#1}{#2}{#3}{#5}\moreargs{#1}{#4}}
+
+\newcommand{\moreargs}[2]{\hbox to \hsize{\phantom{\lisp #1} {\it #2}\hfill}}
+
+\newcommand{\lispindex}[1]{\index{{\lisp #1}}}
+
+ \newenvironment{note}[1]{\pagebreak[2]\bigskip
+ \hrule\smallskip\small
+ {\setlength{\parindent}{0pt}
+ \par{\bf #1:}}}{\smallskip\hrule\bigskip}
+
+
+
+\makeindex
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%\thispagestyle{empty}
+
+%\vspace*{2in}
+
+%\title{The |Iterate| Manual}
+%\author{Jonathan Amsterdam}
+
+%\maketitle
+
+%\thispagestyle{empty}
+
+%\begin{center}
+%\Large *** DRAFT ***
+%\end{center}
+%This manual is in beta-test. It will become an AI Memo in a couple of
+%months. I would appreciate any comments or
+%corrections. You can reach me at email address |jba@ai.ai.mit.edu|.
+
+\begin{document}
+
+\def\writtenby{Jonathan Amsterdam}
+\def\contractno{This report describes research done at the Artificial
+Intelligence Laboratory of the Massachusetts Institute of Technology.
+Support for the laboratory's artificial intelligence research is
+provided in part by the Advanced Research Projects Agency of the
+Department of Defense under Office
+of Naval Research contract N00014-85-K-0124.}
+
+\AIMEMO{1236}{\Large The Iterate Manual \\[1in]}
+{This is the manual for version 1.4 of \iter, a powerful iteration
+macro for Common
+Lisp. \iter\ is similar to {\tt loop} but provides numerous additional
+features, is well integrated with Lisp, and is extensible.
+\vfill }
+
+
+% use ~ for \em
+\catcode`\~=13
+\newif\ifem
+\def~{\ifem
+ \/\endgroup\emfalse
+ \else
+ \begingroup\em\emtrue
+ \fi}
+
+
+
+%\pagebreak
+%\setcounter{page}{1}
+
+%\thispagestyle{empty}
+
+
+\tableofcontents
+
+\pagebreak
+\pagestyle{headings}
+
+\section{Introduction}
+
+\begin{sloppypar}
+This manual describes
+\iter, a powerful iteration facility for Common Lisp.
+\iter\ provides abstractions for many common iteration
+patterns and allows for the definition of additional patterns. \iter\ is
+a macro that expands into ordinary Lisp at
+compile-time, so it is more efficient than higher-order
+functions like |map| and |reduce.|
+While it is similar to |loop|, \iter\ offers a more Lisp-like syntax
+and enhanced extensibility.
+(For a more complete
+comparison of \iter\ with other iteration constructs, see MIT AI Lab Working
+Paper No. 324, ~Don't Loop, Iterate.~)
+\end{sloppypar}
+
+An \iter\ form consists of the symbol |iter|\footnote{You can also use
+|iterate|, but |iter| is preferred because it avoids potential conflicts with
+possible future additions to Common Lisp, and because it saves
+horizontal space when writing code.}
+followed by one or more
+forms, some of which may be \iter\
+~clauses.~ Here is a simple example of \iter\ which collects the
+numbers from 1 to 10 into a list, and returns the list. The return
+value is shown following the arrow.
+\begin{program}
+(iter (for i from 1 to 10)
+ (collect i)) \yields (1 2 3 4 5 6 7 8 9 10)
+\end{program}
+This form contains two clauses: a |for| clause that steps the
+variable |i| over the integers from 1 to 10, and a |collect|
+clause that accumulates its argument into a list. With a few
+exceptions, all \iter\ clauses have the same format: alternating
+symbols (called ~keywords~) and expressions (called
+~arguments~). The syntax and terminology are those of Common
+Lisp's keyword lambda lists. One difference is that \iter's keywords
+do not have to begin with a colon---though they may, except for the
+first symbol of a clause. So you can also write |(for i :from
+1 :to 10)| if you prefer.
+
+Any Lisp form can appear in the body of an \iter, where it will have
+its usual meaning. \iter\ walks the entire body, expanding macros,
+and recognizing clauses at any level. This example collects all the
+odd numbers in a list:
+\begin{program}
+(iter (for el in list)
+ (if (and (numberp el) (oddp el))
+ (collect el)))
+\end{program}
+
+There are clauses for iterating over numbers, lists, arrays and other
+objects, and for
+collecting, summing, counting, maximizing and other useful operations.
+\iter\ also supports the creation of new variable bindings, stepping
+over multiple sequences at once, destructuring, and compiler
+declarations of variable types. The following example illustrates
+some of these features:
+\begin{program}
+(iter (for (key . item) in alist)
+ (for i from 0)
+ (declare (fixnum i))
+ (collect (cons i key)))
+\end{program}
+
+This loop takes the keys of an alist and returns a new alist
+associating the keys with their positions in the original list. The
+compiler declaration for |i| will appear in the generated code
+in the appropriate place.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Clauses}
+
+Most of \iter's clauses will be familiar to |loop| programmers.
+(|loop| is an iteration macro that has been incorporated into Common
+Lisp. Seen Guy Steele's {\em Common Lisp, 2nd Edition}.)
+In
+nearly all cases they behave the same as their |loop| counterparts, so
+a |loop| user can switch to \iter\ with little pain (and much gain).
+
+All clauses with the standard keyword-argument syntax consist of two
+parts: a ~required~ part,
+containing keywords that must be present and in the right order; and
+an ~optional~ part, containing keywords that may be omitted and,
+if present, may occur in any order. In the descriptions below, the
+parts are separated by the Lisp lambda-list keyword \opt.
+
+
+\subsection{Drivers}
+
+An iteration-driving clause
+conceptually causes the iteration to go forward. Driver clauses in
+\iter\ allow iteration over numbers, lists, vectors, hashtables, packages,
+files and streams. Iteration-driving clauses must
+appear at the top level of an \iter\ form; they cannot be nested
+inside another clause. The driver variable is updated at the point
+where the driver clause occurs. Before the clause is executed for the
+first time, the value of the variable is undefined.
+
+%Also, regardless of where the driver clause
+%appears in the body, the driver variable is stepped at the top of the
+%loop; hence it is stylistically preferable, though
+%not required, to place driver clauses at the beginning of the \iter.
+
+Multiple drivers may appear in a single \iter\ form, in which case all
+of the driver variables are updated each time through the loop, in the
+order in which the clauses appear. The first driver to terminate will
+terminate the entire loop.
+
+In all cases, the value of the driver variable on exit from the loop,
+including within the epilogue code (see the |finally| clause), is
+undefined.
+
+All the parameters of a driver clause are evaluated once, before the
+loop begins. Hence it is not possible to change the bounds or other
+properties of an iteration by side-effect from within the loop.
+
+With one exception, driver clauses begin with the word |for| (or
+the synonym |as|) and mention an iteration variable, which is
+given a binding within the \iter\ form.
+The exception is |repeat|, which just executes a loop a
+specified number of times:
+
+\begin{clauses}
+
+\clausex{repeat}{~n~}
+Repeats the loop ~n~ times. For example:
+\begin{program}
+(iter (repeat 100)
+ (print "I will not talk in class."))
+\end{program}
+\cpar If $n \leq 0$, the
+loop will never be executed. If ~n~ is not an integer, the
+actual number of executions will be $\lceil n \rceil$.
+
+\end{clauses}
+
+\pagebreak[3]
+
+\subsubsection{Numerical Iteration}
+
+\begin{clauses}
+\clausex{for}{~var~ |\&sequence|}
+The general form for iterating over a sequence of numbers requires a
+variable and, optionally, one or more keywords that provide the bounds
+and step size of the iteration. The |\&sequence|
+lambda-list keyword is a shorthand for these sequence keywords. They are:
+|from|, |upfrom|, |downfrom|, |to|, |downto|, |above|, |below| and |by|.
+|from| provides the starting value for ~var~
+and defaults to zero. |to| provides a final value and implies that the
+successive values of ~var~ will be increasing; |downto| implies that
+they will be decreasing. The loop terminates when ~var~ passes
+the final value (i.e. becomes smaller or larger than it, depending on
+the direction of iteration); in other words, the loop body
+will never be
+executed for values of ~var~ past the final value.
+|below| and |above| are similar to |to| and
+|downto|, except that the loop terminates when ~var~ equals or passes
+the final value.
+
+\cpar If no final value is specified, the variable will be stepped
+forever. Using |from| or |upfrom| will result in increasing
+values, while |downfrom| will give decreasing values.
+
+\cpar On each iteration,
+~var~ is incremented or decremented by the value of the sequence
+keyword |by|, which defaults to 1. It should always be a positive
+number, even for downward iterations.
+
+\cpar In the following examples, the sequence of numbers generated is shown
+next to the clause.
+
+\begin{program}
+(for i upfrom 0) \yields\ 0 1 2 \ldots
+(for i from 5) \yields\ 5 6 7 \ldots ; either from or upfrom is okay
+(for i downfrom 0) \yields\ 0 -1 -2 \ldots
+(for i from 1 to 3) \yields\ 1 2 3
+(for i from 1 below 3) \yields\ 1 2
+(for i from 1 to 3 by 2) \yields\ 1 3
+(for i from 1 below 3 by 2) \yields\ 1
+(for i from 5 downto 3) \yields\ 5 4 3
+\end{program}
+
+\end{clauses}
+
+\subsubsection{Sequence Iteration}
+
+There are a number of clauses for iterating over sequences. In all of
+them, the argument following |for| may be a list instead of a
+symbol, in which case destructuring is performed. See section
+\ref{destructuring}.
+
+\begin{clauses}
+
+\clause{|for| ~var~ |in| ~list~ \opt\ |by| ~step-function~}
+\clindexx{for}{in}
+~var~ is set to successive elements of list.
+~step-function,~ which
+defaults to |cdr|, is used to obtain the next sublist.
+
+\clause{|for| ~var~ |on| ~list~ \opt\ |by| ~step-function~}
+\clindexx{for}{on}
+~var~ is set to successive sublists of list.
+~step-function~ (default |cdr|) is used as in |for\dots in|.
+
+\end{clauses}
+
+\medskip
+
+These two clauses use |atom| to test for the end
+of a list. Hence, given a list whose final |cdr| is not \nil,
+they will silently ignore the last |cdr|. Other choices are
+|endp|, which would signal an error, and |null|, which
+would probably result in an error somewhere else. If you wish to use
+an end-test other than |atom|, set the variable
+|iterate::*list-end-test*|\lispindex{*list-end-test*} to the name of
+the desired function.
+
+\begin{clauses}
+\clause{|for| ~var~ |in-vector| ~vector~ |\&sequence|}
+\clindexx{for}{in-vector}
+~var~ takes on successive elements from ~vector.~ The vector's
+fill-pointer is observed. Here and in subsequent clauses, the |\&sequence|
+keywords include |with-index|, which takes a symbol as argument
+and uses it for the index variable instead of an internally generated
+symbol. The other |\&sequence| keywords behave as in numerical
+iteration, except that the default iteration bounds are the bounds of
+the vector. E.g. in |(for i in-vector v downto 3)|,
+|i| will start off being bound to the last element in |v|,
+and will
+be set to preceding elements down to and including the element with
+index 3.
+
+\clause{|for| ~var~ |in-sequence| ~seq~ |\&sequence|}
+\clindexx{for}{in-sequence}
+This uses Common Lisp's generalized sequence functions, |elt|
+and |length|, to obtain elements and determine the length of
+~seq.~ Hence it will work for any sequence, including lists, and will
+observe the fill-pointers of vectors.
+
+\clause{|for| ~var~ |in-string| ~string~ |\&sequence|}
+\clindexx{for}{in-string}
+~var~ is set to successive characters of ~string.~
+
+\startitem
+\Clause{|for| ~var~ |index-of-vector| ~vector~ |\&sequence|}
+\clindexx{for}{index-of-vector}
+\Clause{|for| ~var~ |index-of-sequence| ~sequence~ |\&sequence|}
+\clindexx{for}{index-of-sequence}
+\Clause{|for| ~var~ |index-of-string| ~string~ |\&sequence|}
+\clindexx{for}{index-of-string}
+\finishitem
+~var~ is set to successive indices of the sequence.
+These clauses avoid the overhead of accessing the sequence elements
+for those applications where they do not need to be examined, or are
+examined rarely. They admit all the optional keywords of the other
+sequence drivers except the (redundant) |with-index| keyword.
+
+\clause{|for| ~(key value)~ |in-hashtable| ~table~}
+\clindexx{for}{in-hashtable}
+
+~key~ and ~value,~ which must appear as shown in a list
+and may be destructuring templates, are set to the keys and values of
+~table~. If ~key~ is |nil|, then the hashtable's keys will be ignored;
+similarly for ~value~.
+The order in which
+elements of ~table~ will be retrieved is unpredictable.
+
+\clause{|for| ~var~ |in-package| ~package~ \opt\ |external-only| ~ext~}
+\clindexx{for}{in-package}
+Iterates over all the symbols in ~package,~ or over only the
+external symbols if ~ext~ is specified and non-|nil|. ~ext~ is not
+evaluated. The same symbol may appear more than once.
+
+\clause{|for| ~var~ |in-packages| ~packages~ \opt\ |having-access| ~symbol-types~}
+\clindexx{for}{in-packages}
+Iterates over all the symbols from the list of packages denoted by the
+descriptor ~packages~ and having accessibility (or visibility) given by
+~symbol-types~. This defaults to the list |(:external :internal :inherited)|
+and is not evaluated. ~var~ must be a list of up to three variables: in each
+iteration, these will be set to a symbol, its access-type and package (as per
+|with-package-iterator| in ANSI-CL). The same symbol may appear more than
+once.
+
+\end{clauses}
+
+\begin{clauses}
+
+\clause{|for| ~var~ |in-file| ~name~ \opt\ |using| ~reader~}
+\clindexx{for}{in-file}
+Opens the file ~name~ (which may be a string or pathname) for input,
+and iterates
+over its contents. ~reader~ defaults to |read|, so by default ~var~
+will be bound to the successive forms in the file. The \iter\ body is
+wrapped in an unwind-protect to ensure that the file is closed no
+matter how the \iter\ is exited.
+
+\clause{|for| ~var~ |in-stream| ~stream~ \opt\ |using| ~reader~}
+\clindexx{for}{in-stream}
+Like |for\dots in-file|, except that ~stream~ should be an existing
+stream object that supports input operations.
+
+\end{clauses}
+
+\subsubsection{Generalized Drivers}
+
+These are primarily useful for writing drivers that can also be used
+as generators (see section \ref{generators}, below).
+
+\begin{clauses}
+
+\clause{|for| ~var~ |next| ~expr~}
+\clindexx{for}{next}
+
+~var~ is set to ~expr~ each time through the loop. Destructuring is
+performed. When the clause is used as a generator, ~expr~ is the code
+that is executed when |(next ~var~)| is
+encountered (see section \ref{generators}, below).
+~expr~ should compute the first value for ~var~, as well
+as all subsequent values, and is responsible for terminating the loop.
+For compatibility with future versions of \iter, this termination
+should be done with |terminate|\clindex{terminate}, which can be
+considered a synonym for |finish| (see section \ref{control-flow}).
+
+\cpar As an example, the following clauses are equivalent to |(for
+i from 1 to 10)|:
+\begin{program}
+(initially (setq i 0))
+(for i next (if (> i 10) (terminate) (incf i)))
+\end{program}
+
+\clause{|for| ~var~ |do-next| ~form~}
+\clindexx{for}{do-next}
+~form~ is evaluated each time through the loop. Its value is ~not~
+set to ~var~; that is ~form's~ job. ~var~ is only present so that
+\iter\ knows it is a driver variable. \linebreak |(for ~var~ next
+~expr~)| is equivalent to |(for ~var~ do-next (dsetq ~var~ ~expr~))|.
+(See section \ref{destructuring} for an explanation of |dsetq|.)
+
+\end{clauses}
+
+\subsubsection{Generators}
+\label{generators}
+
+In all of the above clauses, the driver variable is updated on each
+iteration.
+Sometimes it is desirable to have greater control over updating.
+For instance, consider the problem of associating numbers, in
+increasing order and with no gaps, with the
+\nonnil\ elements of a list. One obvious first pass at writing this is:
+
+\begin{program}
+(iter (for el in list)
+ (for i upfrom 1)
+ (if el (collect (cons el i))))
+\end{program}
+But on the list |(a b nil c)| this produces |((a . 1) (b . 2) (c .
+4))| instead of the desired |((a . 1) (b . 2) (c . 3))|. The problem
+is that |i| is incremented each time through the loop, even when |el|
+is |nil|.
+
+The problem could be solved elegantly if we could step |i| only when
+we wished to. This
+can be accomplished for any \iter\ driver by writing |generate| (or
+its synonym |generating|)
+instead of |for|. Doing so produces a ~generator~---a driver whose
+values are yielded explicitly. To obtain the next value of a
+generator variable ~v~, write \linebreak |(next ~v~)|. The value of a |next|
+form is the next value of ~v~, as determined by its associated driver
+clause. |next| also has the side-effect of updating ~v~ to that
+value. If there is no next value, |next| will terminate the loop,
+just as with a normal driver.
+
+
+Using generators, we can now write our example like this:
+\begin{program}
+(iter (for el in list)
+ (generate i upfrom 1)
+ (if el (collect (cons el (next i)))))
+\end{program}
+Now |i| is updated only when |(next i)| is executed, and this occurs
+only when |el| is \nonnil.
+
+To better understand the relationship between ordinary drivers and
+generators, observe that we can rewrite an ordinary driver using its
+generator form immediately followed by |next|, as this example shows:
+\begin{program}
+(iter (generating i from 1 to 10)
+ (next i)
+ ...)
+\end{program}
+Provided that the loop body contains no |(next i)| forms, this will
+behave just as if we had written |(for i from 1 to 10)|.
+
+We can still refer to a driver variable ~v~ without using |next|; in
+this case, its value is that given to it by the last evaluation of
+|(next ~v~)|. Before |(next ~v~)| has been called the first time, the
+value of ~v~ is undefined.
+
+This semantics is more flexible than
+one in which ~v~ begins the loop bound to its first value and calls
+of |next| supply subsequent values, because it means the loop will not
+terminate too soon if the generator's sequence is empty. For
+instance, consider the following code, which tags \nonnil\ elements of
+a list using a list of tags, and also counts the null elements.
+(We assume there are at least as many tags as \nonnil\ elements.)
+\begin{program}
+(let* ((counter 0)
+ (tagged-list (iter (for el in list)
+ (generating tag in tag-list)
+ (if (null el)
+ (incf counter)
+ (collect (cons el (next tag)))))))
+ ...)
+\end{program}
+It may be that there are just as many tags as non-null elements of
+|list|. If all the elements of |list| are null, we still want the
+counting to proceed, even though |tag-list| is \nil. If |tag| had to be
+assigned its first value before the loop begins, we would have had to
+terminate the loop before the first iteration, since when |tag-list|
+is \nil, |tag|
+has no first value. With the existing semantics, however, |(next
+tag)| will never execute, so the iteration will cover all the elements of
+|list|.
+
+When the ``variable'' of a driver clause is actually a destructuring
+template containing several variables, all the variables are eligible
+for use with |next|. As before, |(next ~v~)| evaluates to ~v's~ next
+value; but the effect is to update all of the template's variables.
+For instance, the following code will return the list |(a 2 c)|.
+\begin{program}
+(iter (generating (key . item) in '((a . 1) (b . 2) (c . 3)))
+ (collect (next key))
+ (collect (next item)))
+\end{program}
+
+Only driver clauses with variables can be made into generators. This
+includes all clauses mentioned so far except for |repeat|. It does
+~not~ include |for\dots previous|, |for\dots =|,
+|for\dots initially\dots then| or |for\dots first\dots then| (see
+below).
+
+\subsubsection{Previous Values of Driver Variables}
+
+Often one would like to access the value of a variable on a previous
+iteration. \iter\ provides a special clause for accomplishing this.
+
+\begin{clauses}
+
+\clause{|for| ~pvar~ |previous| ~var~ \opt\ |initially| ~init~
+|back| ~n~}
+\clindexx{for}{previous}
+Sets ~pvar~ to the previous value of ~var,~ which should be a driver
+variable, a variable from another |for\dots previous| clause, or a
+variable established by a |for\dots =|,
+|for\dots initially\dots then| or |for\dots first\dots then| clause
+(see section \ref{setting}).
+Initially, ~pvar~ is given the value ~init~ (which defaults to \nil).
+The ~init~ expression will be moved outside the loop body, so it
+should not depend on anything computed within the loop.
+~pvar~ retains the value of ~init~ until ~var~ is set to its second
+value, at which point ~pvar~ is set to ~var's~ first value; and so on.
+
+\cpar The
+argument ~n~ to |back| must be a constant, positive integer, and
+defaults to 1. It determines how many iterations back ~pvar~ should
+track ~var~. For example, when ~n~ is 2, then ~pvar~ will be assigned
+~var's~ first value when ~var~ is set to its third value.
+
+\cpar A |for\dots previous| clause may occur after or before its
+associated driver clause. |for\dots previous| works with generators as
+well as ordinary drivers.
+
+\pagebreak[3]
+
+\cpar Example:
+\begin{program}
+(iter (for el in '(1 2 3 4))
+ (for p-el previous el)
+ (for pp-el previous p-el initially 0)
+ (collect pp-el))
+\end{program}
+This evaluates to |(0 0 1 2)|. It could have been written more
+economically as
+\begin{program}
+(iter (for el in '(1 2 3 4))
+ (for pp-el previous el back 2 initially 0)
+ (collect pp-el))
+\end{program}
+
+
+\end{clauses}
+
+\subsection{Variable Binding and Setting}
+\label{setting}
+
+Several clauses exist for establishing new variable bindings or for
+setting variables in the loop. They all support destructuring.
+
+\begin{clauses}
+
+\clausex{with}{~var~ \opt\ |=| ~value~}
+Causes ~var~ to be bound to value before the loop body is entered.
+If ~value~ is not supplied, ~var~ assumes a default
+binding, which will be
+\nil\ in the absence of declarations. Also, if ~value~ is not
+supplied, no destructuring is performed; instead, ~var~ may be a list of
+symbols, all of which are given default
+bindings. If ~value~ is supplied, ~var~ is bound to it, with
+destructuring.
+
+\cpar Because |with|
+creates bindings whose scope includes the entire \iter\ form, it is
+good style to put all |with| clauses at the beginning.
+
+\cpar Successive occurrences of |with| result in sequential
+bindings (as with
+|let*|). There is no way to obtain parallel bindings; see
+section \ref{bindings} for a rationale.
+
+
+\clause{|for| ~var~ |=| ~expr~}
+\clindexx{for}{=}
+On each iteration, ~expr~ is evaluated and ~var~ is set
+to its value.
+
+\cpar This clause may appear to do the same thing as |for\dots next|.
+In fact, they are quite different. |for\dots =| provides only three
+services: it sets up a binding for ~var~, sets it to ~expr~ on each
+iteration, and makes it possible to use |for\dots previous| with
+~var~. |for\dots next| provides these services in addition to the
+ability to turn the driver into a generator.
+%Also, the code which sets ~var~ appears in the loop body in the same
+%place as the |for\dots =| clause; the code for |for\dots next| appears
+%at the top of the loop, as with other drivers (except when being used
+%as a generator).
+
+\clause{|for| ~var~ |initially| ~init-expr~ |then| ~then-expr~}
+\clindexxx{for}{initially}{then}
+Before the loop begins, ~var~ is set to ~init-expr;~ on all
+iterations after the first it is set to ~then-expr.~ This clause
+must occur at top-level. ~init-expr~ will be moved outside the loop
+body and ~then-expr~ will be moved to the end of the loop body, so
+they are subject to code motion problems (see section
+\ref{code-movement}).
+
+\cpar This clause may appear to be similar to |for\dots next|, but in
+fact they differ significantly. |for\dots initially\dots then| is
+typically used to give ~var~ its first value before the loop begins,
+and subsequent values on following iterations. This is incompatible
+with generators, whose first value and subsequent values must all be
+computed by |(next ~var~)|. Also, the update of ~var~ in
+|for\dots initially\dots then| does not occur at the location of the
+clause.
+Use |for\dots initially\dots then| for
+one-shot computations where its idiom is more convenient, but use
+|for\dots next| for extending \iter\ with new drivers (see section
+\ref{extend}).
+
+\clause{|for| ~var~ |first| ~first-expr~ |then| ~then-expr~}
+\clindexxx{for}{first}{then}
+The first time through the loop, ~var~ is set to ~first-expr;~ on
+subsequent iterations, it is set to ~then-expr.~ This differs from
+|for\dots initially| in that ~var~ is set to ~first-expr~
+inside the loop body,
+so ~first-expr~ may depend on the results of other clauses. For
+instance,
+\begin{program}
+(iter (for num in list)
+ (for i first num then (1+ i))
+ ...)
+\end{program}
+will set |i| to the first element of |list| on the first
+iteration, whereas
+\begin{program}
+(iter (for num in list)
+ (for i initially num then (1+ i))
+ ...)
+\end{program}
+is probably erroneous; |i| will be bound to |num|'s
+default binding (usually \nil) for the first iteration.
+
+\end{clauses}
+
+\begin{note}{Compatibility note}
+|loop|'s |for\dots =| works like \iter's, but |loop| used the syntax
+|for\dots =\dots then| to mean |for\dots initially\dots then|. It was
+felt that these two operations were sufficiently different to warrant
+different keywords.
+
+Also, the |for| in the above three clauses is misleading,
+since none is true driver (e.g. none has a corresponding |generate|
+form). |setting| would have been a better choice, but |for| was used
+to retain some compatibility with |loop|.
+\end{note}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Gathering Clauses}
+Many of \iter's clauses accumulate values into a variable, or set a
+variable under certain conditions. At the end of the loop, this
+variable contains the desired result. All these clauses have an
+optional |into| keyword, whose argument should be a symbol. If the
+|into| keyword is not supplied, the accumulation variable will be
+internally generated and its value will be returned at the end of the
+loop; if a variable is specified, that variable is used for the
+accumulation, and is not returned as a result---it is up to the user
+to return it explicitly, in the loop's epilogue code (see |finally|).
+It is safe to examine the accumulation variable during the loop, but
+it should not be modified.
+
+These clauses all begin with a verb. When the verb does
+not conflict with an existing Common Lisp function, then it may be
+used in either its infinitival or present-participle form (e.g. |sum|,
+|summing|). However, when there is a conflict with Common Lisp, only
+the present-participle form may be used (e.g. |unioning|). This is to
+prevent \iter\ clauses from clashing with Common Lisp
+functions.
+
+%although these clauses are described as ``producing a value,'' it is a
+%mistake to think of the lisp list representing the clause as a
+%value-producing form in the usual way. clauses may legally be written
+%where a value is expected, e.g. |(setq x (sum i))|, but the
+%lisp value of a clause in such a context is undefined.
+
+\subsubsection{Reductions}
+
+~Reduction~ is an extremely common iteration pattern in which
+the results of successive applications of a
+binary operation are accumulated.
+For example, a loop that computes the sum of the
+elements of a list is performing a reduction with the addition
+operation. This could be written in Common Lisp as |(reduce \#'+
+list)| or with \iter\ as
+\begin{program}
+(iter (for el in list)
+ (sum el))
+\end{program}
+
+\begin{clauses}
+
+\clausex{sum}{~expr~ \opt\ |into| ~var~}
+Each time through the loop, ~expr~ is evaluated and added to a
+variable, which is bound initially to zero. If ~expr~ has a type,
+it is ~not~ used as the type of the sum variable, which is always
+|number|. To get the result variable to be of a more specific
+type, use an explicit variable, as in
+\begin{program}
+(iter (for el in number-list)
+ (sum el into x)
+ (declare (fixnum x))
+ (finally (return x)))
+\end{program}
+
+\clausex{multiply}{~expr~ \opt\ |into| ~var~}
+Like |sum|, but the initial value of the result variable is $1$,
+and the variable is updated by multiplying ~expr~ into it.
+
+\clausex{counting}{~expr~ \opt\ |into| ~var~}
+~expr~ is evaluated on each iteration. If it is \nonnil, the
+accumulation variable, initially zero, is incremented.
+
+\startitem
+\Clausex{maximize}{~expr~ \opt\ |into| ~var~}
+\Clausex{minimize}{~expr~ \opt\ |into| ~var~}
+\finishitem
+~expr~ is evaluated on each iteration and its extremum (maximum or
+minimum) is stored in the accumulation variable. If ~expr~ is never
+evaluated, then the result is \nil\ (if the accumulation variable is
+untyped) or $0$ (if it has a numeric type).
+
+\clausex{reducing}{~expr~ |by| ~func~ \opt\ |initial-value| ~init-val~ |into| ~var~}
+This is a general way to perform reductions. ~func~ should be a
+function of two arguments, the first of which will be the value
+computed so far and
+the second of which will be the value of ~expr~. It should return the
+new value.
+|reducing| is roughly equivalent to the
+Common Lisp |(reduce ~func~ ~sequence~ :key ~expr-function~)|, where
+~expr-function~ is used to derive values from the successive elements
+of ~sequence~.
+
+\cpar If the |reducing| clause is never executed, the result is
+undefined.
+
+\cpar It is not necessary to provide an
+initial value, but better code can be generated if one is supplied.
+Regardless of its location in the \iter\ body, ~init-val~ will be
+evaluated before the loop is entered, so it should not depend on any
+value computed inside the \iter\ form.
+
+%\cpar if a ~var~ is not specified, you can get \iter\ to declare the
+%type of the internal variable by putting a |the| expression around
+%~func.~ see section \ref{types}.
+
+\end{clauses}
+
+%\begin{note}{implementation note}
+%in principle, |maximize| and |minimize| can be thought of
+%as reductions where the initial value is the smallest (or largest)
+%value that the accumulation variable can assume. because lisp's
+%bignums can represent arbitrary integers, these clauses cannot be
+%implemented as reductions in general. if, however, the type of
+%~expr~ or ~var~ can be determined to be a fixnum
+%or a float, \iter\ will implement the clause as a true reduction,
+%using one of the constants |most-negative-fixnum|, |%most-positive-fixnum|,
+%|most-negative-short-float|, etc. as appropriate.
+%\end{note}
+
+\subsubsection{Accumulations}
+
+All the predefined accumulation clauses add values to a sequence. If
+the sequence is a list, they all
+have the property that the partial list is kept in the correct order
+and available for inspection at any point in the loop.
+
+\begin{clauses}
+
+\clausex{collect}{~expr~ \opt\ |into| ~var~ |at| ~place~ |result-type| ~type~}
+Produces a sequence of the values of ~expr~ on each iteration. ~place~
+indicates where the next value of ~expr~ is added to the list and may
+be one of the symbols |start|, |beginning| (a synonym for |start|) or
+|end|. The symbol may be quoted, but need not be. The default is
+|end|. For example,
+\begin{program}
+(iter (for i from 1 to 5)
+ (collect i))
+\end{program}
+produces |(1 2 3 4 5)|, whereas
+\begin{program}
+(iter (for i from 1 to 5)
+ (collect i at beginning))
+\end{program}
+produces |(5 4 3 2 1)| (and is likely to be faster in most Common Lisp
+implementations).
+
+\cpar If ~type~ is provided, it should be a subtype of |sequence|.
+The default is |list|. Specifying a type other than |list| will
+result in |collect| returning a sequence of that type. ~However,~ the
+type of the sequence being constructed when inside the loop body is
+undefined when a non-|list| type is specified. (As with ~place~,
+quoting ~type~ is optional.)
+
+\clausex{adjoining}{~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~ |result-type| ~type~}
+Like |collect|, but only adds the value of ~expr~ if it is not
+already present. ~test,~ which defaults to |\#'eql|, is
+the test to be used with |member|.
+
+\startitem
+\Clausex{appending}{~expr~ \opt\ |into| ~var~ |at| ~place~}
+\Clausex{nconcing}{\ ~expr~ \opt\ |into| ~var~ |at| ~place~}
+\Clausex{unioning}{\ ~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~}
+\Clausex{nunioning}{~expr~ \opt\ |into| ~var~ |test| ~test~ |at| ~place~}
+\finishitem
+These are like |collect|, but behave like the Common Lisp functions
+|append|, |nconc|, |union| or |nunion|.
+As in Common Lisp, they work only on lists. Also as in Common Lisp,
+|unioning| and |nunioning| assume that the value of ~expr~ contains no
+duplicates.
+
+\clausex{accumulate}{~expr~ |by| ~func~ \opt\ |initial-value| ~init-val~ |into| ~var~}
+This is a general-purpose accumulation clause. ~func~ should be a
+function of two arguments, the value of ~expr~ and the value
+accumulated so far in the iteration, and it should return the updated
+value. If no initial value is supplied, \nil\ is used.
+
+%\cpar If a ~var~ is not specified, you can get \iter\ to declare the
+%type of the internal variable by putting a |the| expression around
+%~func.~ see section \ref{types}.
+
+\cpar The differences between |accumulate| and |reducing| are slight.
+One difference is that the functions take their arguments in a
+different order. Another is that in the absence of ~init-val~,
+|accumulate| will use \nil, whereas |reducing| will generate different
+code that avoids any dependence on the initial value.
+The reason for having both clauses is that one usually
+thinks of reductions (like |sum|) and accumulations (like |collect|)
+as different beasts.
+
+\end{clauses}
+
+
+\subsubsection{Finders}
+
+A ~finder~ is a clause whose value is an expression that meets some
+condition.
+
+\begin{clauses}
+
+\clause{|finding| ~expr~ |such-that| ~test~ \opt\ |into| ~var~ |on-failure| ~failure-value~}
+\clindexx{finding}{such-that}
+If ~test~ (which is an expression) ever evaluates to \nonnil, the loop
+is terminated, the
+epilogue code is run and the value of ~expr~ is returned. Otherwise,
+\nil\ (or ~failure-value,~ if provided) is returned. If ~var~ is
+provided, it will have either the \nonnil\ value of ~expr~ or
+~failure-value~ when the epilogue code is run.
+
+\cpar As a special case, if the ~test~ expression is a sharp-quoted
+function, then it is applied to ~expr~ instead of being simply
+evaluated. E.g. |(finding x such-that \#'evenp)| is equivalent to
+|(finding x such-that (evenp x))|.
+
+%\cpar although ~test~ need have nothing to do with ~%expr~ as in
+%|(finding j such-that (> i 3))|, it usually
+%will: |(finding (length el) such-that (oddp (length el)))|. to
+%avoid performing the |length| computation twice, you could write
+%|(finding (length el) such-that \#'oddp)| or |(finding (length
+%el) such-that 'oddp)|; for these cases, \iter\ generates code that
+%executes ~expr~ only once. the code for |\#'oddp|
+%is slightly different from that for {\lisp 'oddp}; see the discussion
+%under {\lisp for\dots in} and {\lisp for\dots on}.
+
+\cpar |On-failure| is a misnomer. Because it is always evaluated, it behaves
+more like the default third argument to the |gethash| function. As a result,
+|on-failure (error "Not found")| makes no sense. Instead, the clauses |leave|
+or |thereis| can be used in conjunction with |finally| as follows:
+\begin{program}
+(iter (for x in '(1 2 3))
+ (if (evenp x) (leave x))
+ (finally (error "not found")))
+\end{program}
+
+\cpar This clause may appear multiple times when all defaults are
+identical. It can also be used together with either |always|/|never| or
+|thereis| if their defaults match. More specifically, |on-failure nil| is
+compatible with |thereis|, while |on-failure t| is compatible with |always|
+and |never| clauses.
+\begin{program}
+(iter (for i in '(7 -4 2 -3))
+ (if (plusp i)
+ (finding i such-that (evenp i))
+ (finding (- i) such-that (oddp i))))
+\end{program}
+
+\startitem
+\Clause{|finding| ~expr~ |maximizing| ~m-expr~ \opt\ |into| ~var~}
+\clindexx{finding}{maximizing}
+\Clause{|finding| ~expr~ |minimizing| ~m-expr~ \opt\ |into| ~var~}
+\clindexx{finding}{minimizing}
+\finishitem
+Computes the extremum (maximum or minimum) value of ~m-expr~ over all
+iterations, and returns the value of ~expr~ corresponding to the
+extremum. ~expr~ is evaluated inside the loop at the time the new
+extremum is established. If ~m-expr~ is never evaluated (due to, for
+example, being embedded in a conditional clause), then the returned
+value depends on the type, if any, of ~expr~ (or ~var,~ if
+one is supplied). If there is no type, the returned
+value will be \nil; if the type is numeric, the returned value will be
+zero.
+
+\cpar For these two clauses, ~var~ may be a list of two
+symbols; in that case, the first is used to record ~expr~ and
+the second, ~m-expr.~
+
+\cpar As with |finding\dots such-that|, if ~m-expr~ is a sharp-quoted
+function, then it is called on ~expr~ instead of being evaluated.
+
+\end{clauses}
+
+\subsubsection{Boolean Tests}
+
+\begin{clauses}
+
+\clausex{first-iteration-p}{}
+Returns |t| in the first cycle of the loop, otherwise \nil.
+
+\clausex{first-time-p}{}
+Returns |t| the first time the expression is evaluated, and then \nil\ forever.
+This clause comes handy when printing (optional) elements separated
+by a comma:
+
+\begin{program}
+(iter (for el in '(nil 1 2 nil 3))
+ (when el
+ (unless (first-time-p)
+ (princ ", "))
+ (princ el)))
+\end{program}
+produces |"1, 2, 3"|.
+
+\end{clauses}
+
+\subsubsection{Aggregated Boolean Tests}
+
+\begin{clauses}
+
+\clausex{always}{~expr~}
+If ~expr~ ever evaluates to
+\nil, then \nil\ is immediately returned; the epilogue code is not
+executed. If ~expr~ never evaluates to \nil, the epilogue code
+is executed and the last value of ~expr~ (or |t| if ~expr~ was never
+evaluated) is returned (whereas |loop| would constantly return |t|).
+
+% mention last evaluated clause when multiple always clauses?
+
+\clausex{never}{~expr~}
+Like |(always (not ~expr~))|, except it does not influence the last
+value returned by a possible other |always| clause. That is,
+\begin{program}
+(iter (repeat 2)
+ (always 2)
+ (never nil)) \yields 2 ; not t
+\end{program}
+
+\clausex{thereis}{~expr~}
+If ~expr~ is ever \nonnil,
+its value is immediately returned without running epilogue code.
+Otherwise, the epilogue code is performed and \nil\ is returned.
+
+This clause cannot be used together with |always| or |never|, because their
+defaults are opposed (similarly, |(loop always 3 thereis nil)| refuses to
+compile in some implementations of |loop|).
+
+\end{clauses}
+
+
+\subsection{Control Flow}
+\label{control-flow}
+Several clauses can be used to alter the usual flow of control in a loop.
+
+Note: the clauses of this and subsequent sections don't adhere to \iter's
+usual syntax, but instead use standard Common Lisp syntax. Hence the
+format for describing syntax subsequently is
+like the standard format used in the Common Lisp manual, not like the
+descriptions of clauses above.
+
+\begin{clauses}
+
+\clausex{finish}{}
+Stops the loop and runs the epilogue code.
+
+%for example:
+%
+%\begin{program}
+%(iter (with answer = nil)
+% (initially (make-a-mess))
+% (for i from 1 to 10)
+% (when (correct? i)
+% (setq answer i)
+% (finish))
+% (finally (cleanup)))
+%\end{program}
+%
+%this code will execute |cleanup| whether or not the test |(correct?
+%i)| ever succeeds.
+%the (more elegant) formulation,
+%\begin{program}
+%(iter (initially (make-a-mess))
+% (for i from 1 to 10)
+% (finding i such-that (correct? i))
+% (finally (cleanup)))
+%\end{program}
+%would not execute |cleanup| if |(correct? i)| succeeded; it
+%would do an immediate return.
+
+\clausex{leave}{\opt\ ~value~}
+Immediately returns ~value~ (default \nil) from the current \iter\
+form, skipping the epilogue code. Equivalent to using |return-from|.
+
+\clausex{next-iteration}{}
+Skips the remainder of the loop body and begins the next iteration of
+the loop.
+
+\clausex{while}{~expr~}
+If ~expr~ ever evaluates to \nil, the loop is terminated and the
+epilogue code executed. Equivalent to |(if (not ~expr~) (finish))|.
+
+\clausex{until}{~expr~}
+Equivalent to |(if ~expr~ (finish))|.
+
+\clausex{if-first-time}{~then~ \opt\ ~else~}
+If this clause is being executed for the first time in this invocation
+of the \iter\ form, then the ~then~ code is evaluated; otherwise the
+~else~ code is evaluated.
+
+\cpar |(for ~var~ first ~expr1~ then ~expr2~)| is almost equivalent to
+\begin{program}
+(if-first-time (dsetq ~var~ ~expr1~)
+ (dsetq ~var~ ~expr2~))
+\end{program}
+The only difference is that the |for| version makes ~var~ available
+for use with |for\dots previous|.
+
+\end{clauses}
+
+\subsection{Code Placement}
+When fine control is desired over where code appears in a loop
+generated by \iter, the following special clauses may be useful.
+They are all subject to code-motion problems (see section
+\ref{code-movement}).
+
+\begin{clauses}
+
+\clausex{initially}{|\&rest| ~forms~}
+The lisp ~forms~ are placed in the prologue section of the loop, where
+they are executed once, before the loop body is entered.
+
+\clausex{after-each}{|\&rest| ~forms~}
+The ~forms~ are placed at the end of the loop body, where they
+are executed after each iteration. Unlike the other clauses in this
+section, ~forms~ may contain \iter\ clauses.
+
+\clausex{else}{|\&rest| ~forms~}
+The lisp ~forms~ are placed in the epilogue section of the loop, where they
+are executed if this |else| clause is never met during execution of the
+loop and the loop terminates normally.
+
+\clausex{finally}{|\&rest| ~forms~}
+The lisp ~forms~ are placed in the epilogue section of the loop, where
+they are executed after the loop has terminated normally.
+
+\clausex{finally-protected}{|\&rest| ~forms~}
+The lisp ~forms~ are placed in the second form of an unwind-protect
+outside the loop. They are always executed after the loop has
+terminated, regardless of how the termination occurred.
+
+\end{clauses}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Other Features}
+
+\subsection{Multiple Accumulations}
+\label{multiple}
+
+\begin{sloppypar}
+It is permitted to have more than one clause accumulate into the same
+variable, as in the following:
+\begin{program}
+(iter (for i from 1 to 10)
+ (collect i into nums)
+ (collect (sqrt i) into nums)
+ (finally (return nums)))
+\end{program}
+Clauses can only accumulate into the same variable if they are
+compatible. |collect|, |adjoining|, |appending|, |nconcing|,
+|unioning| and |nunioning| are compatible with each other; |sum|,
+|multiply| and |counting| are compatible; |always| and |never| are compatible;
+|finding| \dots |such-that| is compatible with either |thereis| or |always|
+and |never| when their defaults match; and |maximize| and |minimize| clauses
+are compatible only with other |maximize| and |minimize| clauses,
+respectively.
+
+%note that the same variable ~cannot~ be both an accumulation
+%variable and an ordinary variable; there can be only one variable with
+%a given name within an \iter\ form.
+\end{sloppypar}
+
+\subsection{Named Blocks}
+
+Like Common Lisp |block|s, \iter\ forms can be given names. The
+name should be a single symbol, and it must be the first form in the
+\iter. The generated code behaves exactly like a named block; in
+particular, |(return-from ~name~)| can be used to exit it:
+\begin{program}
+(iter fred
+ (for i from 1 to 10)
+ (iter barney
+ (for j from i to 10)
+ (if (> (* i j) 17)
+ (return-from fred j))))
+\end{program}
+An \iter\ form that is not given a name is implicitly named \nil.
+
+Sometimes one would like to write an expression in an inner \iter\ form,
+but have it processed by an outer \iter\ form. This is possible with
+the |in| clause.
+
+\begin{clauses}
+
+\clausex{in}{~name~ |\&rest| ~forms~}
+Evaluates ~forms~ as if they were part of the \iter\ form named
+~name~. In other words, \iter\ clauses are processed by the \iter\
+form named ~name,~ and not by any \iter\ forms that occur inside ~name.~
+
+\cpar As an example, consider the problem of collecting a list of the
+elements in a two-dimensional array. The naive solution,
+\begin{program}
+(iter (for i below (array-dimension ar 0))
+ (iter (for j below (array-dimension ar 1))
+ (collect (aref ar i j))))
+\end{program}
+\noindent is wrong because the list created by the inner \iter\ is simply
+ignored by the outer one. But using |in| we can write:
+\begin{program}
+(iter outer (for i below (array-dimension ar 0))
+ (iter (for j below (array-dimension ar 1))
+ (in outer (collect (aref ar i j)))))
+\end{program}
+\noindent which has the desired result.
+
+\end{clauses}
+
+\subsection{Destructuring}
+\label{destructuring}
+
+In many places within \iter\ clauses where a variable is expected, a
+list can be written instead. In these cases, the value to be assigned
+is ~destructured~ according to the pattern
+described by the list. As a simple example, the clause
+\begin{program}
+(for (key . item) in alist)
+\end{program}
+\noindent will result in |key| being set to the |car| of
+each element in |alist|, and |item| being set to the |cdr|. The
+pattern list may be nested to arbitrary depth, and (as the example
+shows) need not be terminated with \nil; the only requirement is that
+each leaf be a bindable symbol (or \nil, in which case no binding is
+generated for that piece of the structure).
+
+Sometimes, you might like to do the equivalent of a
+|multiple-value-setq| in a clause. This
+``multiple-value destructuring'' can be expressed by writing
+\linebreak |(values $pat_1$ $pat_2 \ldots$)| for a destructuring
+pattern, as in
+\begin{program}
+(for (values (a . b) c d) = (three-valued-function ...))
+\end{program}
+\begin{sloppypar}
+Note that the $pat_i$ can themselves be destructuring patterns (though
+not multiple-value destructuring patterns). You can't do multiple-value
+destructuring in a |with| clause; instead wrap the whole \iter\
+form in a |multiple-value-bind|.
+\end{sloppypar}
+
+\begin{note}{Rationale}
+There are subtle interactions between variable declarations and
+evaluation order that make the correct implementation of
+multiple-value destructuring in a |with| somewhat tricky.
+\end{note}
+
+The destructuring feature of \iter\ is available as a separate
+mechanism, using the |dsetq| macro:
+
+\begin{clauses}
+\defmacro{dsetq}{template expr}
+Performs destructuring of ~expr~ using ~template~. May be used
+outside of an \iter\ form. Yields the primary value of ~expr~.
+
+\end{clauses}
+
+\subsection{On-line Help}
+
+\begin{sloppypar}
+There is a limited facility for on-line help, in the form of the
+|display-iterate-clauses| function.
+\end{sloppypar}
+
+\begin{clauses}
+
+\defun{display-iterate-clauses}{\opt\ clause-spec}
+Displays a list of \iter\ clauses. If ~clause-spec~ is not
+provided, all clauses are shown; if it is a symbol, all clauses
+beginning with that symbol are shown; and if it is a list of symbols,
+all clauses for which ~clause-spec~ is a prefix are shown.
+
+\end{clauses}
+
+\subsection{Parallel Binding and Stepping}
+\label{bindings}
+
+The parallel binding and stepping of variables is a feature that
+\iter\ does ~not~ have. This section attempts to provide a rationale.
+
+We say that two variables are bound ~in parallel~ if neither
+binding shadows the other. This is the usual semantics of |let|
+(as opposed to |let*|). Similarly, we can say that iteration
+variables are stepped in parallel if neither variable is updated
+before the other, conceptually speaking; in other words, if the code
+to update each variable can reference the old values of both variables.
+
+|loop| allows parallel binding of variables and parallel stepping of
+driver variables. My view is that if you are depending on the
+serial/parallel distinction, you are doing something obscure. If you
+need to bind
+variables in parallel using |with|, then you must be using a
+variable name that shadows a name in the existing lexical environment.
+Don't do that. The most common use for parallel stepping is to track
+the values of variables on the previous iteration, but in fact this
+does not require parallel stepping at all; the following will work:
+\begin{program}
+(iter (for current in list)
+ (for prev previous current)
+ ...)
+\end{program}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Types and Declarations}
+\label{types}
+
+\subsection{Discussion}
+
+Sometimes efficiency dictates that the types of variables be declared.
+This type information needs to be communicated to \iter\ so it can
+bind variables to appropriate values. Furthermore, \iter\ must often
+generate internal variables invisible to the user; there needs to be a
+way for these to be declared.
+
+As an example, consider this code, which will return the number of
+odd elements in |number-list|:
+\begin{program}
+(iter (for el in number-list)
+ (count (oddp el)))
+\end{program}
+In processing this form,
+\iter\ will create an internal variable, let us call it |list17|, to
+hold the successive |cdr|s of |number-list|, and
+will bind the variable to |number-list|. It will also generate a
+default binding for |el|; only inside the body of the loop will |el|
+be set to the |car| of |list17|. Finally, \iter\ will generate a
+variable, call it |result|, to hold the result of the count, and will
+bind it to zero.
+
+When dealing with type declarations, \iter\ observes one simple rule:
+~it will never generate a declaration unless requested to do so.~ The
+reason is that such declarations might mask errors in compiled code by
+avoiding error-checks; the resulting problems would be doubly hard to
+track down because the declarations would be hidden from the
+programmer. Of course, a compiler might omit error-checks even in the
+absence of declarations, though this behavior can usually be avoided,
+e.g. by saying |(declaim (optimize (safety 3)))|.
+
+So, the above \iter\ form will generate code with no declarations.
+But say we wish to declare the types of |el| and the internal
+variables |list17| and |result|. How is this done?
+
+Declaring the type of |el| is easy, since the programmer knows
+the variable's name:
+\begin{program}
+(iter (for el in number-list)
+ (declare (fixnum el))
+ (counting (oddp el)))
+\end{program}
+\iter\ can read variable type declarations like this one. Before
+processing any clauses, it scans the entire top-level form for type
+declarations
+and records the types, so that variable bindings can be performed
+correctly. In this case, |el| will be bound to zero
+instead of \nil. Also, \iter\ collects all the top-level declarations
+and puts them at the begining of the generated code, so it is not
+necessary to place all declarations at the beginning of an \iter\
+form; instead, they can be written near the variables whose types they
+declare.
+
+Since \iter\ is not part of the compiler, it will not know
+about declarations that occur outside an \iter\ form; these
+declarations must be repeated inside the form.
+
+Here is another way we could have declared the type of |el|:
+\begin{program}
+(iter (for (the fixnum el) in number-list)
+ (counting (oddp el)))
+\end{program}
+\iter\ extends the Common Lisp |the|\lispindex{the}
+form to apply to variables as well as value-producing forms; anywhere
+a variable is allowed---in a |with| clause, as the iteration
+variable in a driver clause, as the |into| argument of an
+accumulation clause, even inside a destructuring template---you can
+write |(the ~type~ ~symbol~)| instead.
+
+There is one crucial difference between using a |the| form and
+actually declaring the variable: explicit declarations are always
+placed in the generated code, but type information from a |the|
+form is not turned into an actual declaration unless you tell \iter\
+to do so using |iterate:declare-variables|. See below.
+
+\begin{sloppypar}
+Declaring the types of internal variables is harder than declaring the
+types of explicitly mentioned variables, since their names
+are unknown. You do it by declaring |iterate:declare-variables|
+somewhere inside the top level of the \iter\ form. (This will also
+generate declarations for variables declared using |the|.)
+\iter\ does not provide much selectivity here: it's all or none.
+And unfortunately, since \iter\ is not privy to compiler information
+but instead reads declarations itself, it will not hear if you
+|(declaim (iterate:declare-variables))|. Instead, set the variable
+|iterate::*always-declare-variables*| to |t| at
+compile-time, using |eval-when|.
+\end{sloppypar}
+
+To determine the appropriate types for internal variables, \iter\ uses
+three sources of information:
+
+\begin{itemize}
+
+\item Often, the particular clause dictates a certain type for a
+variable; \iter\ will use this information when available. In the
+current example, the variable |list17| will be given the type
+|list|, since that is the only type that makes sense; and the
+variable |result| will be given the type |fixnum|, on the
+assumption that you will not be counting high enough to need bignums.
+You can override this assumption only by using and explicitly declaring a
+variable:
+\begin{verbatim}
+(iter (declare (iterate:declare-variables))
+ (for el in number-list)
+ (count (oddp el) into my-result)
+ (declare (integer my-result))
+ (finally (return my-result)))
+\end{verbatim}
+
+\begin{sloppypar}
+Other examples of the type assumptions that \iter\ makes are: type
+|list| for |into| variables of collection clauses; type |list| for
+expressions that are to be destructured; type |vector| for the
+variable holding the vector in a |for\dots in-vector| clause, and
+similarly for |string| and the |for\dots in-string| clause;
+and the implementation-dependent type
+|(type-of array-dimension-limit)| for the index and limit
+variables generated by sequence iteration drivers like |for\dots
+in-vector| and |for\dots in-string| (but not |for\dots in-sequence|,
+because it may be used to iterate over a list).
+\end{sloppypar}
+
+\item Sometimes, \iter\ will examine expressions and try to determine
+their types in a simple-minded way. If the expression is
+self-evaluating (like a number, for instance), \iter\ knows that the
+expression's type is the same as the type of the value it denotes, so
+it can use that type. If the expression is of the form |(the ~type~
+~expr~)|, \iter\ is smart enough to extract ~type~ and use it.
+However, the current version of \iter\ does not
+examine declarations of function result types or do any type
+inference. It will not determine, for
+example, that the type of |(+ 3 4)| is |fixnum|, or even
+|number|.
+
+\item In some cases, the type of an internal variable should match the
+type of some other variable. For instance, \iter\ generates an
+internal variable for |(f x)| in the
+clause |(for i from 1 to (f x))|, and in the absence of other
+information will give it the same type as |i|. If, however, the
+expression had been written |(the fixnum (f x))|, then \iter\
+would have given the internal variable the type |fixnum|
+regardless of |i|'s type. The type incompatibility errors that
+could arise in this situation are not checked for.
+
+\end{itemize}
+
+Note that if you do declare |iterate:declare-variables|, then
+\iter\ may declare user variables as well as internal ones if they do
+not already have declarations, though only for variables that it
+binds. For instance, in this code:
+
+\begin{program}
+(iter (declare (iterate:declare-variables))
+ (for i from 1 to 10)
+ (collect i into var))
+\end{program}
+the variable |var| will be declared to be of type |list|.
+
+
+\subsection{Summary}
+
+\iter\ understands standard Common Lisp variable type declarations
+that occur within an \iter\ form and
+will pass them through to the generated code. If the declaration
+|(iterate:declare-variables)|\lispindex{declare-variables}
+appears at the top level of an
+\iter\ form, or if
+|iterate::*always-declare-variables*|\lispindex{*always-declare-variables*}
+is \nonnil, then \iter\ will use the type information gleaned from user
+declarations, self-evaluating expressions and |the| expressions,
+combined with reasonable assumptions, to determine variable
+types and declare them.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Problems with Code Movement}
+\label{code-movement}
+
+Some \iter\ clauses, or parts of clauses, result in code being
+moved from the location of the clause to other parts of the loop.
+Drivers behave this way, as do code-placement clauses like |initially|
+and |finally|. When using these clauses, there is a danger of writing
+an expression that makes sense in its apparent location but will be
+invalid or have a different meaning in another location. For example:
+\begin{program}
+(iter (for i from 1 to 10)
+ (let ((x 3))
+ (initially (setq x 4))))
+\end{program}
+While it may appear that the |x| of |(initially (setq x 4))| is the
+same as the |x| of |(let ((x 3)) \dots|, in fact they are not:
+|initially| moves its code outside the loop body, so |x| would refer
+to a global variable. Here is another example of the same problem:
+\begin{program}
+(iter (for i from 1 to 10)
+ (let ((x 3))
+ (collect i into x)))
+\end{program}
+If this code were executed, |collect| would create a binding for its
+|x| at the top level of the \iter\ form that the |let| will shadow.
+
+Happily, \iter\ is smart enough to catch these errors; it
+walks all problematical code to ensure that free variables are not
+bound inside the loop body, and checks all variables it binds for the
+same problem.
+
+However, some errors cannot be caught:
+
+\begin{program}
+(iter (with x = 3)
+ (for el in list)
+ (setq x 1)
+ (reducing el by \#'+ initial-value x))
+\end{program}
+|reducing| moves its |initial-value| argument to the initialization
+part of the loop in order to produce more efficient code. Since
+\iter\ does not perform data-flow analysis, it cannot determine that
+|x| is changed inside the loop; all it can establish is that |x| is
+not bound internally. Hence this code will not signal an
+error and will use $3$ as the initial value of the reduction.
+
+The following list summarizes all cases that are subject to these code
+motion and variable-shadowing problems.
+\begin{itemize}
+\item Any variable for which \iter\ creates a binding, including those
+used in |with| and the |into| keyword of many clauses.
+
+\begin{sloppypar}
+\item The special clauses which place code: |initially|, |after-each|, |else|,
+|finally| and |finally-protected|.
+\end{sloppypar}
+
+\item The variables of a |next| or |do-next| form.
+
+\item The |initially| arguments of |for\dots initially\dots then| and
+|for\dots previous|.
+
+\item The |then| argument of |for\dots initially\dots then|.
+
+\item The |initial-value| arguments of |reducing| and |accumulate|.
+
+\item The |on-failure| argument of |finding\dots such-that|.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Differences Between {\tt Iterate} and {\tt Loop}}
+|loop| contains a great deal of complexity which \iter\ tries to
+avoid. Hence many esoteric features of |loop| don't exist in \iter.
+Other features have been carried over, but in a cleaned-up form.
+And of course, many new features have been added; they are not
+mentioned in this list.
+
+\begin{itemize}
+
+\item \iter's syntax is more Lisp-like than |loop|'s, having a higher
+density of parens.
+
+\item The current implementation of \iter, unlike the current version
+of |loop| (as documented in {\em Common Lisp, 2nd Ed.\/}), is
+extensible (see section \ref{extend}).
+
+\item |loop| puts the updates of all driver variables at the top of
+the loop; \iter\ leaves them where the driver clauses appear.
+
+\item While for the most part \iter\ clauses that resemble |loop| clauses
+behave similarly, there are some differences. For instance, there is
+no |for\dots =\dots then| in \iter; instead use
+|for\dots initially\dots then|.
+
+\item |loop| binds the variable |it| at certain times
+to allow pseudo-English expressions like |when ~expr~ return it|.
+In \iter, you must bind ~expr~ to a variable yourself. Note that
+|when ~expr~ return it| is like |thereis ~expr~| except that the latter is an
+accumulation clause and therefore competes with other accumulations
+(remember section \ref{multiple} above).
+
+% repeat different behaviour of |always| clause here?
+
+\item |loop| has a special |return| clause, illustrated in the
+previous item. \iter\ doesn't need one, since an ordinary Lisp
+|return| has the same effect.
+
+\item |loop| allows for parallel binding and stepping of iteration
+variables. \iter\ does not. (See section \ref{bindings}.)
+
+\item |loop| and \iter\ handle variable type declarations very
+differently. |loop| provides a special syntax for declaring variable
+types, and does not examine declarations. Moreover, the standard
+implementation of |loop| will
+generate declarations when none are requested.
+\iter\ parses standard Common Lisp type declarations, and will never
+declare a variable itself unless declarations are
+specifically requested.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Rolling Your Own}
+\label{extend}
+
+\subsection{Introduction}
+
+\iter\ is extensible---you can write new clauses that embody new
+iteration patterns. You might want to write a new driver clause for a
+data structure of your own, or you might want to write a clause that
+collects or manipulates elements in a way not provided by \iter.
+
+This section describes how to write clauses for \iter. Writing a
+clause is like writing a macro. In fact, writing a clause ~is~
+writing a macro: since \iter\ code-walks its body and macroexpands,
+you can add new abstractions to \iter\ with good old |defmacro|.
+
+Actually, there are two extensions you can make to \iter\ that are
+even easier than writing a macro. They are adding a synonym for an
+existing clause and defining a driver clause for an indexable
+sequence. These can be done with |defsynonym| and
+|defclause-sequence|, respectively. See section \ref{aids}, below.
+
+The rest of this section explains how to write macros that expand into
+\iter\ clauses.
+Here's how you could add a simplified version of \iter's |multiply|
+clause, if \iter\ didn't already have one:
+\begin{program}
+(defmacro multiply (expr)
+ `(reducing ,expr by \#'* initial-value 1))
+\end{program}
+
+If you found yourself summing the square of an expression often, you
+might want to write a macro for that. A first cut might be
+\begin{program}
+(defmacro sum-of-squares (expr)
+ `(sum (* ,expr ,expr)))
+\end{program}
+but if you are an experienced macro writer, you will realize that this
+code will evaluate ~expr~ twice, which is probably a bad idea. A
+better version would use a temporary:
+\begin{program}
+(defmacro sum-of-squares (expr)
+ (let ((temp (gensym)))
+ `(let ((,temp ,expr))
+ (sum (* ,temp ,temp)))))
+\end{program}
+Although this may seem complex, it is just the sort of thing you'd
+have to go through to write any macro, which illustrates the point of
+this section: if you can write macros, you can extend \iter.
+
+Our macros don't use \iter's keyword-argument
+syntax. We could just use keywords with |defmacro|, but we would
+still not be using \iter's clause indexing mechanism. Unlike Lisp,
+which uses just the first symbol of a form to determine what function
+to call, \iter\ individuates clauses by the list of required keywords.
+For instance, |for\dots in| and |for\dots in-vector| are different clauses
+implemented by distinct Lisp functions.
+
+To buy into this indexing scheme, as well as the keyword-argument
+syntax, use |defmacro-clause|:
+
+\begin{clauses}
+
+\defmacro{defmacro-clause}{arglist |\&body| body}
+Defines a new \iter\ clause. ~arglist~ is a list of symbols which are
+alternating keywords and arguments. \opt\ may be used, and the list
+may be terminated by |\&sequence|. ~body~ is an ordinary macro body,
+as with |defmacro|. If the first form of ~body~ is a string, it is
+considered a documentation string and will be shown by
+|display-iterate-clauses|. |defmacro-clause| will signal an error if
+defining the clause would result in an ambiguity. E.g. you cannot
+define the clause |for\dots from| because there would be no way to
+distinguish it from a use of the |for| clause with optional keyword |from|.
+
+\end{clauses}
+
+\medskip
+
+Here is |multiply| using |defmacro-clause|. The keywords are capitalized
+for readability.
+\begin{program}
+(defmacro-clause (MULTIPLY expr \opt\ INTO var)
+ `(reducing ,expr by \#'* into ,var initial-value 1))
+\end{program}
+You don't have to worry about the case when |var| is not supplied; for
+any clause with an |into| keyword, saying |into nil| is equivalent to
+omitting the |into| entirely.
+
+As another, more extended example, consider the fairly common
+iteration pattern that
+involves finding the sequence element that maximizes (or minimizes) some
+function. \iter\ provides this as |finding\dots maximizing|, but it's
+instructive to see how to write it.
+Here, in pseudocode, is how you might write such a loop for
+maximizing a function F:
+
+\begin{quote}
+\begin{tabbing}
+set variable MAX-VAL to NIL; \\
+set variable WINNER to NIL; \\
+for\=\ each element EL in the sequence \\
+\> if\=\ MAX-VAL\=\ is NIL or F(EL) $>$ MAX-VAL then \\
+\>\> set MAX-VAL to F(EL); \\
+\>\> set WINNER to EL; \\
+\> end if; \\
+end for; \\
+return WINNER.
+\end{tabbing}
+\end{quote}
+
+Here is the macro:
+\begin{program}
+(defmacro-clause (FINDING expr MAXIMIZING func \opt\ INTO var)
+ (let ((max-val (gensym))
+ (temp1 (gensym))
+ (temp2 (gensym))
+ (winner (or var iterate::*result-var*)))
+ `(progn
+ (with ,max-val = nil)
+ (with ,winner = nil)
+ (cond
+ ((null ,max-val)
+ (setq ,winner ,expr)
+ (setq ,max-val (funcall ,func ,winner))
+ (t
+ (let* ((,temp1 ,expr)
+ (,temp2 (funcall ,func ,temp1)))
+ (when (> ,temp2 ,max-val)
+ (setq ,max-val ,temp2)
+ (setq ,winner ,temp1))))))
+ (finally (leave ,winner)))))
+\end{program}
+Note that if no |into| variable is supplied, we use
+|iterate::*result-var*|, which contains the internal variable into
+which all clauses place their results. If this variable is bound by
+some clause, then \iter\ will return its value automatically;
+otherwise, \nil\ will be returned.
+
+\subsection{Writing Drivers}
+
+In principle, drivers can be implemented just as easily as other
+\iter\ clauses. In practice, they are a little harder to get right.
+As an example, consider writing a driver that
+iterates over all the
+elements of a vector, ignoring its fill-pointer. |for\dots in-vector|
+won't work for this, because it observes the fill-pointer. It's necessary to
+use |array-dimension| instead of |length| to obtain the size of the
+vector. Here is one approach:
+
+\begin{program}
+(defmacro-clause (FOR var IN-WHOLE-VECTOR v)
+ "All the elements of a vector (disregards fill-pointer)"
+ (let ((vect (gensym))
+ (index (gensym)))
+ `(progn
+ (with ,vect = ,v)
+ (for ,index from 0 below (array-dimension ,vect 0))
+ (for ,var = (aref ,vect ,index)))))
+\end{program}
+Note that we immediately put |v| in a variable, in case it is an
+expression. Again, this is just good Lisp macrology. It also has a
+subtle effect on the semantics of the driver: |v| is evaluated only
+once, at the beginning of the loop, so changes to |v| in the loop have
+no effect on the driver. Similarly, the bounds for numerical iteration
+e.g. the above |array-dimension| are also evaluated once only. This is how
+all of \iter's drivers work.
+
+
+There is an important point concerning the |progn| in this code. We
+need the |progn|, of course, because we are returning several forms,
+one of which is a driver. But \iter\ drivers must occur at top-level.
+Is this code in error? No, because ~top-level~ is defined in \iter\
+to include forms inside a |progn|. This is just the definition of
+top-level that Common Lisp uses, and for the same reason: to allow
+macros to return multiple forms at top-level.
+
+While our |for\dots in-whole-vector| clause will work, it is not
+ideal. In particular, it does not support generating. Do do so, we
+need to use |for\dots next| or |for\dots do-next|. The job is
+simplified by the |defmacro-driver| macro.
+
+\begin{clauses}
+
+\defmacro{defmacro-driver}{arglist |\&body| body}
+Defines a driver clause in
+both the |for| and |generate| forms, and provides a parameter
+|generate| which ~body~ can examine to determine how it was invoked.
+~arglist~ is as in |defmacro-clause|, and should begin with the symbol
+|for|.
+
+\end{clauses}
+
+With |defmacro-driver|, our driver looks like this:
+\begin{program}
+(defmacro-driver (FOR var IN-WHOLE-VECTOR v)
+ "All the elements of a vector (disregards fill-pointer)"
+ (let ((vect (gensym))
+ (end (gensym))
+ (index (gensym))
+ (kwd (if generate 'generate 'for)))
+ `(progn
+ (with ,vect = ,v)
+ (with ,end = (array-dimension ,vect 0))
+ (with ,index = -1)
+ (,kwd ,var next (progn (incf ,index)
+ (if (>= ,index ,end) (terminate))
+ (aref ,vect ,index))))))
+\end{program}
+
+
+We are still missing one thing: the |\&sequence| keywords.
+We can get them easily enough, by writing
+\begin{program}
+(defmacro-driver (FOR var IN-WHOLE-VECTOR v \&sequence)
+ ...)
+\end{program}
+We can now refer to parameters |from|, |to|, |by|, etc. which contain
+either the values for the corresponding keyword, or \nil\ if the
+keyword was not supplied. Implementing the right code for these
+keywords is cumbersome but not difficult; it is left as an exercise.
+But before you begin, see |defclause-sequence| below for an easier way.
+
+\subsection{Extensibility Aids}
+\label{aids}
+
+This section documents assorted features that may be of use in
+extending \iter.
+
+\begin{clauses}
+
+\defunexpvar{*result-var*}
+Holds the variable that is used to return a value as a result of the
+\iter\ form. You may examine this and use it in a |with| clause, but
+you should not change it.
+
+\defmacro{defsynonym}{syn word}
+ Makes ~syn~ a synonym for the existing \iter\ keyword ~word.~ Only
+the first word in each clause can have synonyms.
+
+\defmacroxx{defclause-sequence}{element-name index-name}{|\&key|
+access-fn size-fn sequence-type}{element-type
+element-doc-string index-doc-string}
+Provides
+a simple way to define sequence clauses. Generates two
+clauses, one for iterating over the sequence's elements, the other
+for iterating over its indices. The first symbol of both
+clauses will have print-name |for|.
+~element-name~ and ~index-name~ should be symbols.
+~element-name~ is the second keyword of the element iterator (typically of
+the form
+|in-~sequence-type~|), and ~index-name~ is the second keyword
+of the index-iterator (typically of the form
+|index-of-~sequence-type~|). Either name may be
+\nil, in which case the corresponding clause is not defined. If both
+symbols are supplied, they should be in the same package. The |for|
+that begins the clauses will be in this package.
+
+\cpar ~access-fn~ is the function to be used to
+access elements of the sequence in the element iterator. The function
+should take two
+arguments, a sequence and an index, and return the appropriate element.
+~size-fn~ should denote a function of one argument, a sequence, that
+returns its size. Both ~access-fn~ and ~size-fn~ are required for the
+element iterator, but only ~size-fn~ is needed for the index iterator.
+
+\cpar The ~sequence-type~ and ~element-type~ keywords are used to
+suggest types for the variables
+used to hold the sequence and the
+sequence elements, respectively. The usual rules about \iter's
+treatment of variable type declarations apply (see section \ref{types}).
+
+\cpar ~element-doc-string~ and ~index-doc-string~ are
+the documentation strings, for use with |display-iterate-clauses|.
+
+\cpar The generated element-iterator performs destructuring on the
+element variable.
+
+\cpar As an example, the above |for\dots in-whole-vector| example
+could have been written:
+\begin{program}
+(defclause-sequence IN-WHOLE-VECTOR INDEX-OF-WHOLE-VECTOR
+ :access-fn 'aref
+ :size-fn \#'(lambda (v) (array-dimension v 0))
+ :sequence-type 'vector
+ :element-type t
+ :element-doc-string
+ "Elements of a vector, disregarding fill-pointer"
+ :index-doc-string
+ "Indices of vector, disregarding fill-pointer")
+\end{program}
+
+\end{clauses}
+
+\subsection{Subtleties}
+
+There are some subtleties to be aware of when writing \iter\ clauses.
+First, the code returned by your macros may be |nconc|'ed into a list,
+so you should always returned freshly consed lists, rather than
+constants. Second, \iter\ matches clauses by using |eq| on the first
+symbol and |string=| on the subsequent ones, so the package of the
+first symbol of a clause is relevant. All of the clauses in this manual
+have their first word in the \iter\ package.
+You can use the package system in the usual way to shadow
+\iter\ clauses without replacing them.
+
+%%% say more here, about the badness that only the first word of a
+%%% clause is packagey.
+
+\section{Non-portable Extensions to Iterate (Contribs)}
+\label{contribs}
+
+Currently, there is only one non-portable extension to iterate in the
+distribution: iterate-pg. If you have made an extension that depends
+on non-portable features, feel free to send them to |asf@boinkor.net|
+for inclusion in the iterate distribution.
+
+\subsection{An SQL query driver for iterate}
+
+The pg package by Eric Marsden (see |http://cliki.net/pg|) provides an
+interface to the PostgreSQL database. Using the \iterpg\ extension, it
+is possible to handle the results of SQL queries using \iter.
+
+This usage example should give you an idea of how to use it:
+
+\begin{program}
+(pg:with-pg-connection (c "somedb" "someuser")
+ (iter (for (impl version date) in-relation "select * from version"
+ on-connection *dbconn*)
+ (collect version)))
+\end{program}
+
+To use the extension via |ASDF|, simply make your system depend on the
+|iterate-pg| system instead of the |iterate| system. To load it
+manually, use:
+
+\begin{program}
+ (asdf:oos 'asdf:load-op :iterate-pg)
+\end{program}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Obtaining {\tt Iterate}}
+
+\begin{sloppypar}
+The information in this chapter is obsolete but included for
+completeness's sake; Currently, the most up-to-date information on
+\iter\ can be found at |http://boinkor.net/iterate.html|.
+\end{sloppypar}
+
+\begin{sloppypar}
+\iter\ currently runs on Lisp Machines, and on
+HP's, Sun3's and Sparcstations under Lucid.
+\iter\ source and binaries are available at the MIT AI Lab in the
+subdirectories of |/src/local/lisplib/|. The source file,
+|iterate.lisp|, is also available for anonymous FTP in the directory
+|/com/fpt/pub/| on the machine |TRIX.AI.MIT.EDU| (Internet number
+128.52.32.6). If you are unable to obtain |iterate| in one of these
+ways, send mail to |jba@ai.mit.edu| and I will send you the source
+file.
+\end{sloppypar}
+
+\begin{sloppypar}
+\iter\ resides in the |iterate| package (nickname |iter|). Just say
+\linebreak |(use-package :iterate)| to make all the necessary symbols
+available.
+If a symbol is not exported, it appears in this manual with an
+``|iterate::|'' prefix.
+\end{sloppypar}
+
+Send bug reports to |bug-iterate@ai.mit.edu|. The |info-iterate|
+mailing list will have notices of changes and problems; to have
+yourself added, send mail to |info-iterate-request@ai.mit.edu|.
+
+
+\medskip
+
+\begin{flushleft}
+ \bf Acknowledgements
+\end{flushleft}
+\smallskip
+
+Richard Waters provided invaluable criticism which spurred me to improve
+\iter\ greatly. As early users, David Clemens, Oren Etzioni and Jeff
+Siskind helped ferret out many bugs.
+
+%\begin{theindex}
+% The index files must be generated with the genindex program
+% or from makeindex iterate-manual.idx which creates iterate-manual.ind.
+
+%\baselineskip\normalbaselineskip
+%\advance\baselineskip by -2pt
+
+\input{iterate-manual.ind}
+
+%\underline{Clauses}
+%\input{iterate-manual.clindex}
+%
+%\indexspace
+%\underline{Lisp}
+%\input{iterate-manual.lispindex}
+
+%\end{theindex}
+
+
+\end{document}
+
+
+% arch-tag: "c0f871a6-313c-11d8-abb9-000c76244c24"