autoconf: Looping constructs
1
1 8.3.5 Looping constructs
1 ------------------------
1
1 The following macros are useful in implementing recursive algorithms in
1 M4, including loop operations. An M4 list is formed by quoting a list
1 of quoted elements; generally the lists are comma-separated, although
1 `m4_foreach_w' is whitespace-separated. For example, the list `[[a],
1 [b,c]]' contains two elements: `[a]' and `[b,c]'. It is common to see
1 lists with unquoted elements when those elements are not likely to be
1 macro names, as in `[fputc_unlocked, fgetc_unlocked]'.
1
1 Although not generally recommended, it is possible for quoted lists
1 to have side effects; all side effects are expanded only once, and
1 prior to visiting any list element. On the other hand, the fact that
1 unquoted macros are expanded exactly once means that macros without
1 side effects can be used to generate lists. For example,
1
1 m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i])
1 error-->hi
1 =>123
1 m4_define([list], [[1], [2], [3]])
1 =>
1 m4_foreach([i], [list], [i])
1 =>123
1
1 -- Macro: m4_argn (N, [ARG]...)
1 Extracts argument N (larger than 0) from the remaining arguments.
1 If there are too few arguments, the empty string is used. For any
1 N besides 1, this is more efficient than the similar
1 `m4_car(m4_shiftn([N], [], [ARG...]))'.
1
1 -- Macro: m4_car (ARG...)
1 Expands to the quoted first ARG. Can be used with `m4_cdr' to
1 recursively iterate through a list. Generally, when using quoted
1 lists of quoted elements, `m4_car' should be called without any
1 extra quotes.
1
1 -- Macro: m4_cdr (ARG...)
1 Expands to a quoted list of all but the first ARG, or the empty
1 string if there was only one argument. Generally, when using
1 quoted lists of quoted elements, `m4_cdr' should be called without
1 any extra quotes.
1
1 For example, this is a simple implementation of `m4_map'; note how
1 each iteration checks for the end of recursion, then merely
1 applies the first argument to the first element of the list, then
1 repeats with the rest of the list. (The actual implementation in
1 M4sugar is a bit more involved, to gain some speed and share code
1 with `m4_map_sep', and also to avoid expanding side effects in
1 `$2' twice).
1 m4_define([m4_map], [m4_ifval([$2],
1 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl
1 m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]])
1 => 1 2 a
1
1 -- Macro: m4_for (VAR, FIRST, LAST, [STEP], EXPRESSION)
1 Loop over the numeric values between FIRST and LAST including
1 bounds by increments of STEP. For each iteration, expand
1 EXPRESSION with the numeric value assigned to VAR. If STEP is
1 omitted, it defaults to `1' or `-1' depending on the order of the
1 limits. If given, STEP has to match this order. The number of
1 iterations is determined independently from definition of VAR;
1 iteration cannot be short-circuited or lengthened by modifying VAR
1 from within EXPRESSION.
1
1 -- Macro: m4_foreach (VAR, LIST, EXPRESSION)
1 Loop over the comma-separated M4 list LIST, assigning each value
1 to VAR, and expand EXPRESSION. The following example outputs two
1 lines:
1
1 m4_foreach([myvar], [[foo], [bar, baz]],
1 [echo myvar
1 ])dnl
1 =>echo foo
1 =>echo bar, baz
1
1 Note that for some forms of EXPRESSION, it may be faster to use
1 `m4_map_args'.
1
1 -- Macro: m4_foreach_w (VAR, LIST, EXPRESSION)
1 Loop over the white-space-separated list LIST, assigning each value
1 to VAR, and expand EXPRESSION. If VAR is only referenced once in
1 EXPRESSION, it is more efficient to use `m4_map_args_w'.
1
1 The deprecated macro `AC_FOREACH' is an alias of `m4_foreach_w'.
1
1 -- Macro: m4_map (MACRO, LIST)
1 -- Macro: m4_mapall (MACRO, LIST)
1 -- Macro: m4_map_sep (MACRO, SEPARATOR, LIST)
1 -- Macro: m4_mapall_sep (MACRO, SEPARATOR, LIST)
1 Loop over the comma separated quoted list of argument descriptions
1 in LIST, and invoke MACRO with the arguments. An argument
1 description is in turn a comma-separated quoted list of quoted
1 elements, suitable for `m4_apply'. The macros `m4_map' and
1 `m4_map_sep' ignore empty argument descriptions, while `m4_mapall'
1 and `m4_mapall_sep' invoke MACRO with no arguments. The macros
1 `m4_map_sep' and `m4_mapall_sep' additionally expand SEPARATOR
1 between invocations of MACRO.
1
1 Note that SEPARATOR is expanded, unlike in `m4_join'. When
1 separating output with commas, this means that the map result can
1 be used as a series of arguments, by using a single-quoted comma as
1 SEPARATOR, or as a single string, by using a double-quoted comma.
1
1 m4_map([m4_count], [])
1 =>
1 m4_map([ m4_count], [[],
1 [[1]],
1 [[1], [2]]])
1 => 1 2
1 m4_mapall([ m4_count], [[],
1 [[1]],
1 [[1], [2]]])
1 => 0 1 2
1 m4_map_sep([m4_eval], [,], [[[1+2]],
1 [[10], [16]]])
1 =>3,a
1 m4_map_sep([m4_echo], [,], [[[a]], [[b]]])
1 =>a,b
1 m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]]))
1 =>2
1 m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])
1 =>a,b
1 m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]))
1 =>1
1
1 -- Macro: m4_map_args (MACRO, ARG...)
1 Repeatedly invoke MACRO with each successive ARG as its only
1 argument. In the following example, three solutions are presented
1 with the same expansion; the solution using `m4_map_args' is the
1 most efficient.
1 m4_define([active], [ACTIVE])dnl
1 m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))])
1 => plain active
1 m4_map([ m4_echo], [[[plain]], [[active]]])
1 => plain active
1 m4_map_args([ m4_echo], [plain], [active])
1 => plain active
1
1 In cases where it is useful to operate on additional parameters
1 besides the list elements, the macro `m4_curry' can be used in
1 MACRO to supply the argument currying necessary to generate the
1 desired argument list. In the following example, `list_add_n' is
1 more efficient than `list_add_x'. On the other hand, using
1 `m4_map_args_sep' can be even more efficient.
1
1 m4_define([list], [[1], [2], [3]])dnl
1 m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl
1 dnl list_add_n(N, ARG...)
1 dnl Output a list consisting of each ARG added to N
1 m4_define([list_add_n],
1 [m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@)))])dnl
1 list_add_n([1], list)
1 =>2,3,4
1 list_add_n([2], list)
1 =>3,4,5
1 m4_define([list_add_x],
1 [m4_shift(m4_foreach([var], m4_dquote(m4_shift($@)),
1 [,add([$1],m4_defn([var]))]))])dnl
1 list_add_x([1], list)
1 =>2,3,4
1
1 -- Macro: m4_map_args_pair (MACRO, [MACRO-END = `macro'], ARG...)
1 For every pair of arguments ARG, invoke MACRO with two arguments.
1 If there is an odd number of arguments, invoke MACRO-END, which
1 defaults to MACRO, with the remaining argument.
1
1 m4_map_args_pair([, m4_reverse], [], [1], [2], [3])
1 =>, 2, 1, 3
1 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3])
1 =>, 2, 1, [3]
1 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4])
1 =>, 2, 1, 4, 3
1
1 -- Macro: m4_map_args_sep ([PRE], [POST], [SEP], ARG...)
1 Expand the sequence `PRE[ARG]POST' for each argument, additionally
1 expanding SEP between arguments. One common use of this macro is
1 constructing a macro call, where the opening and closing
1 parentheses are split between PRE and POST; in particular,
1 `m4_map_args([MACRO], [ARG])' is equivalent to
1 `m4_map_args_sep([MACRO(], [)], [], [ARG])'. This macro provides
1 the most efficient means for iterating over an arbitrary list of
1 arguments, particularly when repeatedly constructing a macro call
1 with more arguments than ARG.
1
1 -- Macro: m4_map_args_w (STRING, [PRE], [POST], [SEP])
1 Expand the sequence `PRE[word]POST' for each word in the
1 whitespace-separated STRING, additionally expanding SEP between
1 words. This macro provides the most efficient means for iterating
1 over a whitespace-separated string. In particular,
1 `m4_map_args_w([STRING], [ACTION(], [)])' is more efficient than
1 `m4_foreach_w([var], [STRING], [ACTION(m4_defn([var]))])'.
1
1 -- Macro: m4_shiftn (COUNT, ...)
1 -- Macro: m4_shift2 (...)
1 -- Macro: m4_shift3 (...)
1 `m4_shiftn' performs COUNT iterations of `m4_shift', along with
1 validation that enough arguments were passed in to match the shift
1 count, and that the count is positive. `m4_shift2' and
1 `m4_shift3' are specializations of `m4_shiftn', introduced in
1 Autoconf 2.62, and are more efficient for two and three shifts,
1 respectively.
1
1 -- Macro: m4_stack_foreach (MACRO, ACTION)
1 -- Macro: m4_stack_foreach_lifo (MACRO, ACTION)
1 For each of the `m4_pushdef' definitions of MACRO, expand ACTION
1 with the single argument of a definition of MACRO.
1 `m4_stack_foreach' starts with the oldest definition, while
1 `m4_stack_foreach_lifo' starts with the current definition.
1 ACTION should not push or pop definitions of MACRO, nor is there
1 any guarantee that the current definition of MACRO matches the
1 argument that was passed to ACTION. The macro `m4_curry' can be
1 used if ACTION needs more than one argument, although in that case
1 it is more efficient to use M4_STACK_FOREACH_SEP.
1
1 Due to technical limitations, there are a few low-level m4sugar
1 functions, such as `m4_pushdef', that cannot be used as the MACRO
1 argument.
1
1 m4_pushdef([a], [1])m4_pushdef([a], [2])dnl
1 m4_stack_foreach([a], [ m4_incr])
1 => 2 3
1 m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])])
1 => cd bcd
1
1 -- Macro: m4_stack_foreach_sep (MACRO, [PRE], [POST], [SEP])
1 -- Macro: m4_stack_foreach_sep_lifo (MACRO, [PRE], [POST], [SEP])
1 Expand the sequence `PRE[definition]POST' for each `m4_pushdef'
1 definition of MACRO, additionally expanding SEP between
1 definitions. `m4_stack_foreach_sep' visits the oldest definition
1 first, while `m4_stack_foreach_sep_lifo' visits the current
1 definition first. This macro provides the most efficient means
1 for iterating over a pushdef stack. In particular,
1 `m4_stack_foreach([MACRO], [ACTION])' is short for
1 `m4_stack_foreach_sep([MACRO], [ACTION(], [)])'.
1