simple iterator protocol for common lisp

1com.clearly-useful.iterator-protocol

Overview: This package provides a simple iterator protocol for common lisp which integrates with the sequence protocol.

From the protocol docstring:

A simple iteration protocol for Common Lisp.

Unlike sequences, iterators are stateful, and arenot intended to be held onto or passed around. Theiruse should be hidden by some other construct. If youare explicitly creating and advancing an iterator,chances are you are Doing It Wrong.Iterators should be be treated as though theyhave dynamic extent.

This package is intentionally minimal, and only provides

a protcol for handling stateful iterators & basic implementationsfor built in types. This protocol e.g. consume an object representingthe lines of a file, or some strings in memory, without having tospecial case anything. The actual implementation of such an objectis beyond the scope of this package.

2exported symbols:

2.1iterator

protocolthe iterator protocol, which has two methods:iterator-next! and iterator-finish!

2.2iterator

typethe type of the iterator protocol

2.3iterator

generic functiona function to produce an iterator from an object.this function acts as the identity function foriterators, and provides a default implementationfor the built in types vector and array, aswell as any object implementing the seq protocol.

2.4iterator-p

functionthe test function for the iterator protocol

2.5iterator-next!

protocol methodreturns two values:

1. the value of the iterator or nil,
2. t or nil depending whether a value was found.

then advances the iterator.

2.6iterator-finish!

protocol methodperforms 'clean up' operations specificto the iterator. e.g. closing a file.

2.7do-iterator

macrosimilar to dolist.

     (do-iterator (x '(a b c) (list x x))
       (print x))

will call iterator on '(a b c),bind x to subsequent values ofiterator-next!, finally calliterator-finish! and return the valueof (list x x), i.e.print a, b, and c, then return '(c c)