### 6.5 Iteration by list contents ¶

Here is an example of a loop macro that implements list iteration.

Composite: foreach (iterator, paren-list, text) ¶
Composite: foreachq (iterator, quote-list, text) ¶

  Takes the name in iterator, which must be a valid macro name, and successively assign it each value from paren-list or quote-list. In `foreach`, paren-list is a comma-separated list of elements contained in parentheses. In `foreachq`, quote-list is a comma-separated list of elements contained in a quoted string. For each assignment to iterator, append text to the overall expansion. text may refer to iterator. Any definition of iterator prior to this invocation is restored.

As an example, this displays each word in a list inside of a sentence, using an implementation of `foreach` distributed as `m4-1.4.19/examples/foreach.m4`, and `foreachq` in `m4-1.4.19/examples/foreachq.m4`.

    $ m4 -I examples
    include(`foreach.m4')
    ⇒
    foreach(`x', (foo, bar, foobar), `Word was: x
    ')dnl
    ⇒Word was: foo
    ⇒Word was: bar
    ⇒Word was: foobar
    include(`foreachq.m4')
    ⇒
    foreachq(`x', `foo, bar, foobar', `Word was: x
    ')dnl
    ⇒Word was: foo
    ⇒Word was: bar
    ⇒Word was: foobar

It is possible to be more complex; each element of the paren-list or quote-list can itself be a list, to pass as further arguments to a helper macro. This example generates a shell case statement:

    $ m4 -I examples
    include(`foreach.m4')
    ⇒
    define(`_case', `  $1)
        $2=" $1";;
    ')dnl
    define(`_cat', `$1$2')dnl
    case $`'1 in
    ⇒case $1 in
    foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
            `_cat(`_case', x)')dnl
    ⇒  a)
    ⇒    vara=" a";;
    ⇒  b)
    ⇒    varb=" b";;
    ⇒  c)
    ⇒    varc=" c";;
    esac
    ⇒esac

The implementation of the `foreach` macro is a bit more involved; it is a wrapper around two helper macros. First, `_arg1` is needed to grab the first element of a list. Second, `_foreach` implements the recursion, successively walking through the original list. Here is a simple implementation of `foreach`:

    $ m4 -I examples
    undivert(`foreach.m4')dnl
    ⇒divert(`-1')
    ⇒# foreach(x, (item_1, item_2, ..., item_n), stmt)
    ⇒#   parenthesized list, simple version
    ⇒define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')')
    ⇒define(`_arg1', `$1')
    ⇒define(`_foreach', `ifelse(`$2', `()', `',
    ⇒  `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')')
    ⇒divert`'dnl

Unfortunately, that implementation is not robust to macro names as list elements. Each iteration of `_foreach` is stripping another layer of quotes, leading to erratic results if list elements are not already fully expanded. The first cut at implementing `foreachq` takes this into account. Also, when using quoted elements in a paren-list, the overall list must be quoted. A quote-list has the nice property of requiring fewer characters to create a list containing the same quoted elements. To see the difference between the two macros, we attempt to pass double-quoted macro names in a list, expecting the macro name on output after one layer of quotes is removed during list iteration and the final layer removed during the final rescan:

    $ m4 -I examples
    define(`a', `1')define(`b', `2')define(`c', `3')
    ⇒
    include(`foreach.m4')
    ⇒
    include(`foreachq.m4')
    ⇒
    foreach(`x', `(``a'', ``(b'', ``c)'')', `x
    ')
    ⇒1
    ⇒(2)1
    ⇒
    ⇒, x
    ⇒)
    foreachq(`x', ```a'', ``(b'', ``c)''', `x
    ')dnl
    ⇒a
    ⇒(b
    ⇒c)

Obviously, `foreachq` did a better job; here is its implementation:

    $ m4 -I examples
    undivert(`foreachq.m4')dnl
    ⇒include(`quote.m4')dnl
    ⇒divert(`-1')
    ⇒# foreachq(x, `item_1, item_2, ..., item_n', stmt)
    ⇒#   quoted list, simple version
    ⇒define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')')
    ⇒define(`_arg1', `$1')
    ⇒define(`_foreachq', `ifelse(quote($2), `', `',
    ⇒  `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')')
    ⇒divert`'dnl

Notice that `_foreachq` had to use the helper macro `quote` defined earlier (see Recursion in `m4`), to ensure that the embedded `ifelse` call does not go haywire if a list element contains a comma. Unfortunately, this implementation of `foreachq` has its own severe flaw. Whereas the `foreach` implementation was linear, this macro is quadratic in the number of list elements, and is much more likely to trip up the limit set by the command line option `--nesting-limit` (or `-L`, see Invoking m4). Additionally, this implementation does not expand ‘`defn(`iterator')`’ very well, when compared with `foreach`.

    $ m4 -I examples
    include(`foreach.m4')include(`foreachq.m4')
    ⇒
    foreach(`name', `(`a', `b')', ` defn(`name')')
    ⇒ a b
    foreachq(`name', ``a', `b'', ` defn(`name')')
    ⇒ _arg1(`a', `b') _arg1(shift(`a', `b'))

It is possible to have robust iteration with linear behavior and sane iterator contents for either list style. See if you can learn from the best elements of both of these implementations to create robust macros (or see Answers).