Unified for Loop

This package consolidates the various Iteration and Comprehension Forms into a single for macro that compiles directly to efficient named let code. It also allows identifiers to be bound via match patterns.

Warning: this package is experimental and subject to breaking changes.

All identifiers are bound via match patterns. Each pattern must successfully match, otherwise a exn:misc:match? exception is thrown.

1 Iterators

An iterator is a Syntax Transformer for use in the iterator-clause of for. See Extending for on deriving new iterators.

If start-expr or step-expr are not provided, they are 0 and 1 respectively.

2 Accumulators

An accumulator is a syntax transformer for use in the maybe-accumulator clause of for. See Extending for on deriving new accumulators.

If #:reverse? is not provided, or reverse?-expr evaluates to #t, to-list accumulates items like for/list. Otherwise, to-list returns items in the opposite order.

The to-list accumulator normally collects elements in reverse order by consing them together, then applying reverse to the result. With #:reverse? #f, to-list does not reverse the result. This can give better performance.

If expandable-option is supplied, to-vector will copy the existing values to a fresh mutable vector? each time iteration exceeds its length. The size of the new vector is calculated as (* old-length multiplier-expr). The vector is trimmed to the correct size when iteration concludes.

When no arguments are supplied, to-vector uses the expandable-options #:grow-from 16 #:by 2.

If fixed-option is supplied, to-vector creates a single mutable vector?. Iteration is stopped as soon as the vector is completely filled. The length-expr option specifies the size of the vector, and fill-expr specifies what to place in the vector if it is not completely filled by iteration. By default, fill-expr is 0.

Supplying a length via #:length length-expr can be more efficient than the default behavior, since the accumulator will only ever create one vector.

The init-exprs are evaluated and bound to arg-ids in the body forms of the for loop. The body of the for loop must evaluate to as many values as there are arg-ids. These values are then bound to each arg-id in the next iteration.

If result-form is supplied, it is evaluated at the end of iteration and its result returned. By default, result-form is (values arg-id ...).

3 Extending for

Creating a new iterator or accumulator involves using define-syntax to make a Syntax Transformer that expands into a syntax list. It is similar to the process of using :do-in to extend the traditional for loop. The for macro local-expands each iterator and accumulator and splices their results into its own expansion.

Both accumulators and iterators expand to similar forms. The first element, ([(outer-id ...) outer-expr] ...) specifies identifiers and expressions to be bound via let*-values outside the loop. This is useful when the iterator or accumulator needs to evaluate an expression only once. For example, to-vector with the #:fill option creates its vector? here.

The second element, (outer-check-expr ...), specifies a list of expressions which are evaluated for their side effects, after outer-ids are bound, and before the loop begins. This is useful for checking that all sub-forms of the iterator or accumulator are of valid types. For example, from-range uses this space to throw an exception if its sub-forms do not evaluate to real? numbers.

Next is ([loop-id loop-expr] ...). These identifiers are bound to their expressions at the start of the loop, once all outer-checks have been evaluated. Later, during the iteration of the for form, they are bound to the result of evaluating the loop-args. For example, the from-list iterator binds loop-id to the list? being iterated over. The to-fold accumulator uses these bindings to keep track of its arg-ids and their bindings.

The pos-guard-expr form is evaluated once at the beginning of each iteration of the loop. If it produces a #t value, the loop continues. Otherwise, iteration ends immediately, and the accumulator’s done-expr is returned. This form is useful for checking whether the sequence being iterated over is empty or not. For example, from-vector uses this space to ensure that the current index in the vector, which it bound as a loop-arg is less than its length. The from-naturals iterator expands here to #t its iteration is infinite.

After each pos-guard-expr is checked, ([(inner-id ...) inner-expr] ...) is bound via let*-values. This is useful for creating bindings that differ on each iteration, and happen before the evaluation of for’s bodys.

After inner-ids are bound, the pre-guard-expr is evaluated. If it produces a #t value, the loop continues. Otherwise, iteration ends immediately and the accumulator’s done-expr is returned. This can be useful for ending iteration based off of a value bound to an inner-id.

The next form is different for iterators and accumulators. For iterators, it is match-expr, and it specifies what expression to match against for’s match-patterns. For example, from-hash’s match-expr evaluates to two values, the current key and value of the hash? being iterated over. For accumulators, this form is (body-result-id ...). It specifies the identifiers to bind via let-values to the result of for’s bodys. The to-list accumulator supplies one identifier here, which it conses onto its loop-id in its loop-arg-expr.

Both iterators and accumulators then have a post-guard-expr. If post-guard-expr evaluates to a #t value, the loop continues. Otherwise, iteration ends immediately and the accumulator’s done-expr is returned. This can be useful for ending iteration based off of a value bound to a body-result-id in the case of accumulators, or a side effect of for’s bodys, in the case of iterators.

The (loop-arg-expr ...) form is then evaluated, and its result is bound to each loop-ids on the next iteration. An iterator, like from-vector, uses this form to step to the next element in the sequence, usually by adding 1 to an index, or using a cdr-like operation. An accumulator, like to-list, uses this form to add an element to its collection, usually the one bound by body-result-id.

Each accumulator must specify one more form, done-expr, which is evaluated and returned whenever any pos-guard-expr, pre-guard-expr, or post-gurd-expr returns a #f value. For example, to-list with #:reverse? #t uses this space to reverse the accumulated list bound to its loop-id.

Here is the full expansion of a for form, with one accumulator bound to a, and any number of iterators bound to (i ...).

(let*-values ([(a.outer-id ...) a.outer-expr] ...

[(i.outer-id ...) i.outer-expr] ... ...)

a.outer-check-expr ...

i.outer-check-expr ... ...

(let loop ([a.loop-id a.loop-expr] ...

[i.loop-id i.loop-expr] ... ...)

(if (and a.pos-guard-expr i.pos-guard-expr ...)

(let*-values ([(a.inner-id ...) a.inner-expr] ...

[(i.inner-id ...) i.inner-expr] ... ...)

(if (and a.pre-guard-expr i.pre-guard-expr ...)

(let-values ([(a.body-result-id ...)

(match-let-values

([(pattern ...) i.match-expr] ...)

body ...)])

(if (and a.post-guard-expr i.post-guard-expr ...)

(loop a.loop-arg-expr ... i.loop-arg-expr ... ...)

a.done-expr))

a.done-expr))

a.done-expr)))