Overview
********

1 About iterate
***************

iterate is an iteration construct for Common Lisp
(http://www.lisp.org). It is similar to the CL:LOOP
(http://www.xach.com/clhs?q=loop) macro, with these distinguishing
marks:

   * it is extensible,

   * it supports editors like Emacs (http://www.emacswiki.org) indent
     iterate forms by having a more lisp-like syntax, and

   * it isn't part of the ANSI standard for Common Lisp
     (http://www.lispworks.com/reference/HyperSpec/Front/index.htm)
     (which is sometimes a bad thing and sometimes good).

2 Where to get it
*****************

The canonical site for information about iterate is at
http://boinkor.net/iterate.html (http://boinkor.net/iterate.html).

   iterate has spent most of its life in the CMU AI archive as a lisp
file for pre-ANSI Common Lisps. Some people have adapted it to other
implementations, but the most activly maintained version right now is
the one by me, Andreas Fuchs. You can get it by asdf-install
(http://www.cliki.net/asdf-install), if you have it installed, via:

     CL-USER> (asdf-install:install :iterate)

   several lines of compiler output will come up; you'll be asked if you
want to accept my GPG key (see below for my fingerprint), if you have
gnupg (http://www.gnupg.org) installed, and after that, you have
iterate installed.

   If you don't have ASDF-INSTALL on your lisp, but you have ASDF
(http://cliki.net/ASDF), you can just grab the latest tarball at
http://www.boinkor.net/lisp/iterate/iterate-latest.tar.gz
(http://www.boinkor.net/lisp/iterate/iterate-latest.tar.gz) and unpack
it into a directory, say `/home/you/iterate-1.0.4'. Make a symbolic link
called `iterate.asd' from your `asdf:*central-repository*' directory to
the file `/home/you/iterate-1.0.4/iterate.asd', and you're ready to use
iterate.

3 How to make it available to your code
***************************************

If you're using ASDF (http://cliki.net/asdf) (highly recommended), have
:iterate on the :depends-on list to your system, like this:

     (defsystem my-example
       :depends-on (:iterate)
       :components ((:file "foo")))

   If you're not using ASDF (not recommended), use code like this in one
of the files that use the iterate construct:

     (eval-when (:compile-toplevel :load-toplevel :execute)
       (require 'iterate))

4 Some examples
***************

...to highlight the superiority of the iterate construct (-:

   Finding the longest list in a list of lists:

     (iterate (for elt in list-of-lists)
              (finding elt maximizing (length elt)))

   Whereas with loop, you'd have to use something like:

     (let ((with found-max-elt nil))
       (loop with maximum = 0
             for elt in list-of-lists
             when (> (length elt) maximum)
               (setf found-max-elt elt)
             finally (return found-max-elt)))

   So, which version is clearer? I know which I prefer. (-:

   Here's another example, using generators:

     (iterate (generate i from 0 to 6)
              (for (key . value) in '((a . 2) (zero . 10) (one . 20) (d . 5)))
              (when (>= value 10)
                (collect (cons key (next i)))))
     
     ;; gives:
     ((ZERO . 0) (ONE . 1))

   Generators are like lazy counters - they remain at one value every
time through the loop, until you request the next value. This can be
pretty handy in some situations.

   You can find more documentation on iterate and its features (there
are a lot more than I can demonstrate in this document!) in the `doc/'
directory in your iterate distribution.

5 Bugs, feature suggestions and requests
****************************************

Send those to the current maintainer of iterate, Andreas Fuchs
<<asf@boinkor.net>>.

   The current bugs file can be found at the current iterate bugs page
(http://boinkor.net/iterate.bugs.html).

   Encrypted mail is welcome, of course. My GPG key is available on most
key servers (e.g. pgp.mit.edu). My key ID is `1024D/04D7F45F', dated
2000-12-13, and my fingerprint is `7E3A 9931 2430 BC5A 51AC F960 B9C0
C058 04D7 F45F'.

   I'm looking forward to hearing from you!

