Colliflower ยป Liter

Liter is a collection of tools to work with basic iterators.

An iterator in Liter is just a function (usually a closure) which returns the next value in the iterable, and signals a ITERATION-ENDED condition if there are no more values. It should follow the following rules:

An iterable is any object for which there is a method defined for GET-ITERATOR. Most liter function accept an iterable, and will get an iterator using GET-ITERATOR. There is a GET-ITERATOR method defined for iterators that is equivalent to the identity function, so iterators can be passed to these functions.

Basic Functionality

get-iterator(iterable)
Get an iterator for some iterable object. Implementations are provided for builtin iterable types.
end-iterationnil
Convenience function to return values for an iterator that has reached the end.
inext(iterator &rest args)

Return the next value of an iterator and whether or not an actual value was retrieved as values.

Any additional arguments are passed through to the iterator function.

iteration-ended
Condition signaled when an iterator has reached the end.
    get-iterator((f function))
    The iterator for a function is just the function
    get-iterator((l list))
    Iterator for the items of a list, or pairs of an alist.
    get-iterator((s vector))
    Iterate over the items of a vector respecting the fill-counter if extant.
    get-iterator((a array))
    Iterate over elements of array in row-major order.
    get-iterator((h hash-table))

    Iterate over elements of a hash-table. Returns a cons of the key and value.

    Since a clousre over a the form from a HASH-TABLE-ITERATOR is undefiend, at the time of creation a list of keys is created and the iterator closes over that.

    If you know of a better way of doing this, please let me know.

    get-iterator((s stream))
    Iterate over the elements of a stream. I.e. the characters of a character stream or the bytes of a byte stream.
    make-hash-key-iterator(h)
    Get an iterator over the keys of H.
    make-hash-value-iterator(h)
    Get an iterator over the values of H.
    make-character-stream-iterator(stream)
    Get an iterator for a character input stream
    make-byte-stream-iterator(stream)
    Get an iterator for a binary input stream.
    make-line-iterator(stream)
    Get an iterator that iterates over lines in a character stream.
    do-iterator((var iterator &optional return) &body body)
    A DO macro in the style of dolist that executes body for each item in ITERATOR.
    do-iterable((var iterable &optional return) &body body)
    Loop over all items in the iterable ITERABLE, in a manner similar to dolist.
    iterator-list(iterator)
    Create a list from an iterator. Note that this will only work if the iterator terminates.

    Liter also provides two iterate drivers:

    FOR var IN-ITERATOR it
    Iterates through the items in an iterator it
    FOR var IN-ITERABLE it
    A more generic driver clause that will iterate over anything with get-iterator defined on it.

    Generators

    The Following API is provided by the liter/generate package (inluded in the liter package). These functions can be used to create iterators that abstract some sort of sequence.
    icounter(&key (from 0) (by 1) (to 0 stop-p))

    Create an iterator that just counts up from FROM by amount BY forever. The returned iterator takes an optional argument which resets the counter if true.

    If a TO parameter is provided, then the counter will stop when the value returned would equal the TO parameter. Note that if using a BY parameter it is possible to step over the TO end-point, but a >= comparison is undesirable because it wouldn't work for a negative step.

    irepeat(v &optional (n -1))

    Create an iterator that returns the value V N times. If N is negative (the default) iterate forever.

    Note that CONSTANTLY is equivalent to IREPEAT with a negative N, and in fact there is a compiler macro that compiles IREPEAT as CONSTANTLY in that case.

    singleton-iterator(element)

    Create an iterator that returns element on the first iteration, and ends on the second.

    Equivalent to `(irepeat element 1)`.

    icycle(iterable)
    Create an iterator that iterates through ITERABLE, and then cycles through the values again. This stores the results of iterating over ITERABLE.
    icycle*(&rest args)
    Create an iterator that cycles through the arguments passed to it.
    make-iterator(&body body)

    Create an iterator that executes BODY each time.

    Basically a simple wrapper for LAMBDA. Iteration can be ended by calling END-ITERATION.

    No node with name make-state-iterator.
    make-state-iterator*(initial-state (&rest lambda-list) &body body)
    Macro form of MAKE-STATE-ITERATOR. Note that in this form INITIAL-STATE is required.

    Tools

    The following API provides additional tools to perform operations on iterators and iterables.
    itransform(iterable map-fun)

    Return an iterator that iterates over transformed values of an iterable.

    ITERABLE is on object for which GET-ITERATOR is defined. MAP-FUN is a function which is called with each value returned by the iterator and returns the value that the new iterator should return.

    ifilter(iterable predicate)
    Return a new iterator that iterates over the values of ITERABLE for which PREDICATE is true.
    ifold(iterable op &optional initial)
    Fold over an iterable. ITERABLE is the iterable to fold over. OP is a binary operation that takes the accumulated result, and an iterated item and returns a new accumulated result. INITIAL is the initial accumulated state.
    iaccumulate(iterable &optional (op (quote +)))

    Return an iterator that accumulates the results of appling OP to the previous result and the current item.

    IACCUMULATE is like IFOLD that keeps track of intermediary results.

    ichain(first &rest rest)
    Return a new iterator that iterates through each of the iterables passed to it in series.
    izip(&rest iterables)

    Zip iterables together.

    This returns an iterator that returns a list of the results of getting the next value from each iterable. The iterator ends when the shortest of the iterables ends.

    izip-longest(missing-value &rest iterables)
    Like IZIP but stops on the longest iterable. When a shorter iterable ends, it will continually return MISSING-VALUE until the whole iterator ends.
    izip-with-index(iterable)

    Zip an iterable with an index.

    Each element of the new iterator is a list of the index (starting with 0) and the next element of ITERABLE.

    itee(iterable &optional (n 2))
    Split a single iterable into N iterators. The iterators are returned as values. Note that ITEE depends on the iterator of iterable signaling an END-ITERATION if the iterator has ended, even if an END-ITERATION has already been signaled.
    itake(iterable n)
    Take the first N elements of iterable. Returns an iterator.
    itake-while(iterable pred)
    Return an iterator that returns elements from ITERABLE as long as PRED returns true when passed the value. Not that this will consume the first item where PRED returns nil and not return it.
    idrop(iterable n)
    Return an iterator over the elements of iterable after dropping the first n.
    idrop-while(iterable pred)
    Return an iterator over the elements of iterable that drops the initial elements while PRED returns false for them. This is the inverse of ITAKE-WHILE.

    ITER-OBJECT

    iter-object

    A class to represent an iterator object.

    If closer-mop is enabled, it is a funcallable object that calls ITER-OBJECT-NEXT when called. Otherwise GET-ITERATOR returns a function that calls ITER-OBJECT-NEXT.

    Subclasses should use a metaclass of FUNCALLABLE-STANDARD-CLASS if mop is available.

      iter-object-next(iter-object &rest args)
      Get the next object in the iter-object iterator.
      iter-object-prev(iter-object &rest args)

      Get the previous object in the iter-object iterator.

      This is optional for iter-object implementations.

      iter-object-end-p(iter-ojbect)
      Predicate to test if the iterator has ended.

      File iterator

      file-iterator
      An iterator object that represents the iteration state of iterating over a file stream.
      • stream
        The stream that the file-iterator is backed by.
      • by-line
        Whether or not we are reading by lines. Only applies to character streams.
      • read-fun
        The function to use to read from the stream.
      make-file-iterator(filename &key by-line (element-type (quote character)) (if-does-not-exist error) (external-format default))

      Create a FILE-ITERATOR using the same arguments as OPEN. In fact this is basically like OPEN, but returns a FILE-ITERATOR instead of a stream.

      If BY-LINE is true, and the ELEMENT-TYPE is a subtype of CHARACTER, then the iterator will return whole lines at a time instead of individual characters.

      with-file-iterator((var filename &key by-line (element-type (quote (quote character))) (if-does-not-exist error) (external-format default)) &body body)
      Macro similar to WITH-OPEN-FILE, but VAR is bound to a file iterator instead of a STREAM.