Next: Text processing Macros, Previous: Looping constructs, Up: Programming in M4sugar [Contents][Index]
The following macros give some control over the order of the evaluation by adding or removing levels of quotes.
Apply the elements of the quoted, comma-separated list as the
arguments to macro. If list is empty, invoke macro
without arguments. Note the difference between m4_indir, which
expects its first argument to be a macro name but can use names that are
otherwise invalid, and m4_apply, where macro can contain
other text, but must end in a valid macro name.
m4_apply([m4_count], []) ⇒0 m4_apply([m4_count], [[]]) ⇒1 m4_apply([m4_count], [[1], [2]]) ⇒2 m4_apply([m4_join], [[|], [1], [2]]) ⇒1|2
This macro returns the decimal count of the number of arguments it was passed.
This macro performs argument currying. The expansion of this macro is another macro name that expects exactly one argument; that argument is then appended to the arg list, and then macro is expanded with the resulting argument list.
m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) ⇒3, 2, 1
Unfortunately, due to a limitation in M4 1.4.x, it is not possible to
pass the definition of a builtin macro as the argument to the output of
m4_curry; the empty string is used instead of the builtin token.
This behavior is rectified by using M4 1.6 or newer.
This macro loops over its arguments and expands each arg in
sequence. Its main use is for readability; it allows the use of
indentation and fewer dnl to result in the same expansion. This
macro guarantees that no expansion will be concatenated with subsequent
text; to achieve full concatenation, use m4_unquote(m4_join([],
arg…)).
m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl m4_do([a],[b])c ⇒abc m4_unquote(m4_join([],[a],[b]))c ⇒3 m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl m4_do([a],[b])c ⇒ABC m4_unquote(m4_join([],[a],[b]))c ⇒3
Return the arguments as a quoted list of quoted arguments. Conveniently, if there is just one arg, this effectively adds a level of quoting.
Return the arguments as a series of double-quoted arguments. Whereas
m4_dquote returns a single argument, m4_dquote_elt returns
as many arguments as it was passed.
Return the arguments, with the same level of quoting. Other than discarding whitespace after unquoted commas, this macro is a no-op.
Return the expansion of arg as a quoted string. Whereas
m4_quote is designed to collect expanded text into a single
argument, m4_expand is designed to perform one level of expansion
on quoted text. One distinction is in the treatment of whitespace
following a comma in the original arg. Any time multiple
arguments are collected into one with m4_quote, the M4 argument
collection rules discard the whitespace. However, with m4_expand,
whitespace is preserved, even after the expansion of macros contained in
arg. Additionally, m4_expand is able to expand text that
would involve an unterminated comment, whereas expanding that same text
as the argument to m4_quote runs into difficulty in finding the
end of the argument. Since manipulating diversions during argument
collection is inherently unsafe, m4_expand issues an error if
arg attempts to change the current diversion (see Diversion support).
m4_define([active], [ACT, IVE])dnl m4_define([active2], [[ACT, IVE]])dnl m4_quote(active, active) ⇒ACT,IVE,ACT,IVE m4_expand([active, active]) ⇒ACT, IVE, ACT, IVE m4_quote(active2, active2) ⇒ACT, IVE,ACT, IVE m4_expand([active2, active2]) ⇒ACT, IVE, ACT, IVE m4_expand([# m4_echo]) ⇒# m4_echo m4_quote(# m4_echo) ) ⇒# m4_echo) ⇒
Note that m4_expand cannot handle an arg that expands to
literal unbalanced quotes, but that quadrigraphs can be used when
unbalanced output is necessary. Likewise, unbalanced parentheses should
be supplied with double quoting or a quadrigraph.
m4_define([pattern], [[!@<:@]])dnl m4_define([bar], [BAR])dnl m4_expand([case $foo in m4_defn([pattern])@:}@ bar ;; *[)] blah ;; esac]) ⇒case $foo in ⇒ [![]) BAR ;; ⇒ *) blah ;; ⇒esac
This macro was introduced in Autoconf 2.62. Expands to nothing, ignoring all of its arguments. By itself, this isn’t very useful. However, it can be used to conditionally ignore an arbitrary number of arguments, by deciding which macro name to apply to a list of arguments.
dnl foo outputs a message only if [debug] is defined. m4_define([foo], [m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])
Note that for earlier versions of Autoconf, the macro __gnu__ can
serve the same purpose, although it is less readable.
This macro exists to aid debugging of M4sugar algorithms. Its net
effect is similar to m4_dquote—it produces a quoted list of
quoted arguments, for each arg. The difference is that this
version uses a comma-newline separator instead of just comma, to improve
readability of the list; with the result that it is less efficient than
m4_dquote.
m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl m4_dquote(zero, [one], [[two]]) ⇒[0],[one],[[two]] m4_make_list(zero, [one], [[two]]) ⇒[0], ⇒[one], ⇒[[two]] m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number]) ⇒ 0 1 two m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number]) ⇒ 0 1 two
Return the arguments as a single entity, i.e., wrap them into a pair of quotes. This effectively collapses multiple arguments into one, although it loses whitespace after unquoted commas in the process.
Outputs each argument with the same level of quoting, but in reverse order, and with space following each comma for readability.
m4_define([active], [ACT,IVE]) ⇒ m4_reverse(active, [active]) ⇒active, IVE, ACT
This macro was introduced in Autoconf 2.62. Expand each argument,
separated by commas. For a single arg, this effectively removes a
layer of quoting, and m4_unquote([arg]) is more efficient
than the equivalent m4_do([arg]). For multiple arguments,
this results in an unquoted list of expansions. This is commonly used
with m4_split, in order to convert a single quoted list into a
series of quoted elements.
The following example aims at emphasizing the difference between several
scenarios: not using these macros, using m4_defn, using
m4_quote, using m4_dquote, and using m4_expand.
$ cat example.m4 dnl Overquote, so that quotes are visible. m4_define([show], [$[]1 = [$1], $[]@ = [$@]]) m4_define([a], [A]) m4_define([mkargs], [1, 2[,] 3]) m4_define([arg1], [[$1]]) m4_divert([0])dnl show(a, b) show([a, b]) show(m4_quote(a, b)) show(m4_dquote(a, b)) show(m4_expand([a, b])) arg1(mkargs) arg1([mkargs]) arg1(m4_defn([mkargs])) arg1(m4_quote(mkargs)) arg1(m4_dquote(mkargs)) arg1(m4_expand([mkargs])) $ autom4te -l m4sugar example.m4 $1 = A, $@ = [A],[b] $1 = a, b, $@ = [a, b] $1 = A,b, $@ = [A,b] $1 = [A],[b], $@ = [[A],[b]] $1 = A, b, $@ = [A, b] 1 mkargs 1, 2[,] 3 1,2, 3 [1],[2, 3] 1, 2, 3
Next: Text processing Macros, Previous: Looping constructs, Up: Programming in M4sugar [Contents][Index]