Next: , Up: Programming in M4sugar


8.3.1 Redefined M4 Macros

With a few exceptions, all the M4 native macros are moved in the `m4_' pseudo-namespace, e.g., M4sugar renames define as m4_define etc.

The list of macros unchanged from M4, except for their name, is:

Some M4 macros are redefined, and are slightly incompatible with their native equivalent.

— Macro: __file__
— Macro: __line__

All M4 macros starting with `__' retain their original name: for example, no m4__file__ is defined.

— Macro: __oline__

This is not technically a macro, but a feature of Autom4te. The sequence __oline__ can be used similarly to the other m4sugar location macros, but rather than expanding to the location of the input file, it is translated to the line number where it appears in the output file after all other M4 expansions.

— Macro: dnl

This macro kept its original name: no m4_dnl is defined.

— Macro: m4_bpatsubst (string, regexp, [replacement])

This macro corresponds to patsubst. The name m4_patsubst is kept for future versions of M4sugar, once GNU M4 2.0 is released and supports extended regular expression syntax.

— Macro: m4_bregexp (string, regexp, [replacement])

This macro corresponds to regexp. The name m4_regexp is kept for future versions of M4sugar, once GNU M4 2.0 is released and supports extended regular expression syntax.

— Macro: m4_defn (macro)

Unlike the M4 builtin, this macro fails if macro is not defined. Also, while newer M4 can concatenate multiple definitions, this version currently only supports a single macro. See m4_undefine.

— Macro: m4_divert (diversion)

M4sugar relies heavily on diversions, so rather than behaving as a primitive, m4_divert behaves like:

          m4_divert_pop()m4_divert_push([diversion])
     

See Diversion support, for more details about the use of the diversion stack.

— Macro: m4_exit (exit-status)

This macro corresponds to m4exit.

— Macro: m4_if (comment)
— Macro: m4_if (string-1, string-2, equal, [not-equal])
— Macro: m4_if (string-1, string-2, equal, ...)

This macro corresponds to ifelse. string-1 and string-2 are compared literally, so usually one of the two arguments is passed unquoted. See Conditional constructs, for more conditional idioms.

— Macro: m4_include (file)
— Macro: m4_sinclude (file)

Like the M4 builtins, but warn against multiple inclusions of file.

— Macro: m4_mkstemp (template)
— Macro: m4_maketemp (template)

Posix requires maketemp to replace the trailing `X' characters in template with the process id, without regards to the existence of a file by that name, but this a security hole. When this was pointed out to the Posix folks, they agreed to invent a new macro mkstemp that always creates a uniquely named file, but not all versions of GNU M4 support the new macro. In M4sugar, m4_maketemp and m4_mkstemp are synonyms for each other, and both have the secure semantics regardless of which macro the underlying M4 provides.

— Macro: m4_popdef (macro)

Unlike the M4 builtin, this macro fails if macro is not defined. Also, while newer M4 can pop multiple definitions at once, this version currently only supports a single macro. See m4_undefine.

— Macro: m4_undefine (macro)

Unlike the M4 builtin, this macro fails if macro is not defined. Also, while newer M4 can undefine multiple definitions at once, this version currently only supports a single macro. Use

          m4_ifdef([macro], [m4_undefine([macro])])
     

to recover the behavior of the builtin.

— Macro: m4_undivert (diversion)

Unlike the M4 builtin, only one diversion can be undiverted per invocation. Also, since the M4sugar diversion stack prefers named diversions, the use of m4_undivert to include files is risky. See Diversion support, for more details about the use of the diversion stack.

— Macro: m4_wrap (text)
— Macro: m4_wrap_lifo (text)

These macros correspond to m4wrap. Posix requires arguments of multiple wrap calls to be reprocessed at EOF in the same order as the original calls (first-in, first-out). GNU M4 versions through 1.4.10, however, reprocess them in reverse order (last-in, first-out). Both orders are useful, therefore, you can rely on m4_wrap to provide FIFO semantics and m4_wrap_lifo for LIFO semantics, regardless of the underlying GNU M4 version.

Unlike the GNU M4 builtin, these macros only recognize one argument, and avoid token pasting between consecutive invocations. On the other hand, nested calls to m4_wrap from within wrapped text work just as in the builtin.