— Macro: m4_apply (macro, list)

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

— Macro: m4_count (arg, ...)

This macro returns the decimal count of the number of arguments it was passed.

— Macro: m4_curry (macro, arg...)

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.

— Macro: m4_do (arg, ...)

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

— Macro: m4_dquote (arg, ...)

Return the arguments as a quoted list of quoted arguments. Conveniently, if there is just one arg, this effectively adds a level of quoting.

— Macro: m4_dquote_elt (arg, ...)

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.

— Macro: m4_echo (arg, ...)

Return the arguments, with the same level of quoting. Other than discarding whitespace after unquoted commas, this macro is a no-op.

— Macro: m4_expand (arg)

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

— Macro: m4_ignore (...)

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.

— Macro: m4_make_list (arg, ...)

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

— Macro: m4_quote (arg, ...)

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.

— Macro: m4_reverse (arg, ...)

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

— Macro: m4_unquote (arg, ...)

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.

     $ 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