Commit a1753b81 authored by Joerg-Cyril Hoehle's avatar Joerg-Cyril Hoehle
Browse files

Use @:, @. and two spaces between sentences

Move section on predicate (first-time-p) outside of gathering clauses
Various typos and some clarifications

darcs-hash:5b5854a2ee03c6d4bb12991029e4eb351be51ad8
parent 0a95bcee
\input texinfo @c -*- Mode: Texinfo; Mode: auto-fill -*-
@c %**start of header
@setfilename iterate.info
@settitle The Iterate Manual
@settitle The Iterate Manual and Paper
@exampleindent 2
@c @documentencoding utf-8
......@@ -20,8 +20,8 @@
@end macro
@macro impnote {text}
@quotation
@strong{Implementor's note:} @emph{\text\}
@quotation Implementor's note
@emph{\text\}
@end quotation
@end macro
......@@ -75,8 +75,8 @@ Copyright @copyright{} 1989 Jonathan Amsterdam <jba at ai.mit.edu> @*
@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
The present manual is a conversion 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
......@@ -85,12 +85,15 @@ 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.}
The appendix includes Jonathan Amsterdam's Working Paper 324,
MIT AI Lab entitled ``Don't Loop, Iterate.''
@end quotation
@end copying
@c %**end of header
@titlepage
@title The Iterate Manual
@title The Iterate Manual and Paper
@c @subtitle Version X.X
@c @author Jonathan Amsterdam
......@@ -134,7 +137,7 @@ 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
@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}.)
......@@ -216,6 +219,7 @@ keyword @code{&optional}.
* Variable Binding and Setting::
* Gathering Clauses::
* Control Flow::
* Predicates::
* Code Placement::
@end menu
......@@ -295,7 +299,7 @@ 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
(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
......@@ -383,7 +387,7 @@ fill-pointer is observed. Here and in subsequent clauses, the
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
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.
......@@ -780,7 +784,7 @@ binding (usually @code{nil}) for the first iteration.
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}
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
......@@ -803,23 +807,22 @@ 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},
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}).
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 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
......@@ -917,7 +920,7 @@ entered, so it should not depend on any value computed inside the
@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 |most-negative-short-float|, etc.@: as appropriate.}
@c ===================================================================
@node Accumulations
......@@ -1033,7 +1036,7 @@ 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
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
......@@ -1087,8 +1090,8 @@ 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.
value will be @code{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,
......@@ -1099,33 +1102,6 @@ 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
......@@ -1177,11 +1153,13 @@ implementations of @code{loop}).
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
@quotation 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.
@end quotation
@clauseu{finish}
@deffn Clause finish
......@@ -1237,7 +1215,7 @@ the epilogue code executed. Equivalent to @code{(if (not @var{expr})
@end deffn
@clauseu{until}
@deffn Clause until @v{~expr~}
@deffn Clause until @v{expr}
Equivalent to @code{(if @var{expr} (finish))}.
@end deffn
......@@ -1261,6 +1239,38 @@ The only difference is that the @code{for} version makes @var{var}
available for use with @code{for@dots{} previous}.
@end deffn
@c ===================================================================
@node Predicates
@section Predicates
@quotation Compatibility Note
The clauses in this section were added in the twenty-first century and
not part of Jonathan Amsterdam's original design.
@end quotation
@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)))
@print{} 1, 2, 3
@end lisp
@end deffn
@c ===================================================================
@node Code Placement
@section Code Placement
......@@ -1417,14 +1427,14 @@ 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
destructuring'' can be expressed by writing @code{(values @var{pat_1}
@var{pat_2} @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
Note that the @var{pat_i} 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}.
......@@ -1530,7 +1540,7 @@ 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)))}.
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
......@@ -1778,13 +1788,13 @@ mentioned in this list.
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}).
The current implementation of @iter{}, unlike the standardised version
of @code{loop}, 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.
loop; @iter{} leaves them where the driver clauses appear. In
particular, @iter{} allows to place drivers after @code{while} clauses.
@item
While for the most part @iter{} clauses that resemble @code{loop}
......@@ -1899,7 +1909,7 @@ 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
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}.
......@@ -2000,7 +2010,7 @@ 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
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.
......@@ -2052,7 +2062,7 @@ We can get them easily enough, by writing
@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
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}
......@@ -2118,6 +2128,7 @@ documentation strings, for use with @code{display-iterate-clauses}.
The generated element-iterator performs destructuring on the element
variable.
@end defmac
As an example, the above @code{for@dots{} in-whole-vector} example
could have been written:
......@@ -2131,7 +2142,6 @@ could have been written:
: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
......@@ -2155,16 +2165,16 @@ replacing them.
@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.
distribution: @code{iterate-pg}. If you have made an extension that
depends on non-portable features, feel free to send them to
the @iter{} project team for inclusion in the iterate distribution.
@section An SQL query driver for iterate
@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}.
@code{in-relation} driver, it is possible to handle the results of SQL
queries with @iter{}.
This usage example should give you an idea of how to use it:
......@@ -2175,9 +2185,12 @@ This usage example should give you an idea of how to use it:
(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:
The distribution now contains an @file{iterate.asd} system definition
file for the @iter{} package.
To use the extension via @acronym{ASDF, Another System Definition
Facility}, 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)
......@@ -2187,30 +2200,44 @@ load it manually, use:
@node Obtaining Iterate
@chapter Obtaining @code{Iterate}
@impnote{This chapter is very, very obsolete.}
@iter{} has been successfully ported to most implementations that
purport to conform to ANSI CL. Since 2006, source and project
information is available from
@url{http://common-lisp.net/project/iterate/}. The mailing list for
all purposes is @email{iterate-devel@@common-lisp.net}, but you need
to subscribe to it before posting.
The source file was split into two files in 2003: @file{package.lisp}
contains the package definition, @file{iterate.lisp} the main code.
Other files in the distribution contain user contributions, test cases
and documentation.
@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.
The regression test suite in @file{iterate-test.lisp}, based on
@acronym{MIT}'s @code{RT} package, contains many examples.
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}.
@quotation Note
The rest of this chapter serves history.
@end quotation
@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/}.
at the @acronym{MIT} @acronym{AI} Lab in the subdirectories of
@file{/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
FTP in the directory @file{/com/ftp/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.
@email{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
Send bug reports to @email{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}.
@email{info-iterate-request@@ai.mit.edu}.
@c ===================================================================
@node Acknowledgements
......@@ -2220,13 +2247,18 @@ 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.
Thanks to Andreas Fuch, J@"org H@"ohle and Attila Lendvai, who more
than a decade after the original release, ported the code to ANSI CL
and fixed long-standing 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.''
This appendix is a Texinfo conversion performed by Lu@'{@dotless{i}}s
Oliveira of Jonathan Amsterdam's Working Paper 324, MIT AI Lab
entitled ``Don't Loop, Iterate.''
@end quotation
@section Introduction
......@@ -2262,7 +2294,7 @@ 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.
@c \iter\ is fully documented in AI Lab Memo No.@: 1236, \iman.
@section More about @iter{}
......@@ -2398,7 +2430,7 @@ 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
@subsection High-order Functions
Lisp's age-old mapping functions, recently revamped for Common Lisp
[CLM], are another favorite for iteration. They provide a pleasing
......@@ -2536,7 +2568,7 @@ example:
(collect el)))
@end lisp
Expressed with \looP, it would read
Expressed with @code{loop}, it would read
@lisp
(loop for el in list
......@@ -2634,7 +2666,7 @@ 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{}.
then my advice to you is, don't @code{loop}---@iter{}.
@section Acknowledgments
......@@ -2655,16 +2687,16 @@ Press, 1985.
@item
[Loop] ``The loop Iteration Macro.'' In @emph{Symbolics Common
Lisp---Language Concepts}, manual 2A of the Symbolics documentation,
pp. 541--567.
pp.@: 541--567.
@item
[CLM] Steele, Guy L. @emph{Common Lisp: The Language}. Bedford, MA:
[CLM] Steele, Guy L@. @emph{Common Lisp: The Language}. Bedford, MA:
Digital Press, 1984.
@item
[Series] Waters, Richard C. @emph{Optimization of Series Expressions:
[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.
No.@: 1082.
@end itemize
@c ===================================================================
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment