With a few exceptions, all the M4 native macros are moved in the
‘m4_’ pseudo-namespace, e.g., M4sugar renames
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.
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.
These macros aren't directly builtins, but are closely related to
m4_renameensure that dest is undefined, while
m4_rename_forceoverwrite any existing definition. All four macros then proceed to copy the entire pushdef stack of definitions of source over to dest.
m4_copy_forcepreserve the source (including in the special case where source is undefined), while
m4_rename_forceundefine the original macro name (making it an error to rename an undefined source).
Note that attempting to invoke a renamed macro might not work, since the macro may have a dependence on helper macros accessed via composition of ‘$0’ but that were not also renamed; likewise, other macros may have a hard-coded dependence on source and could break if source has been deleted. On the other hand, it is always safe to rename a macro to temporarily move it out of the way, then rename it back later to restore original semantics.
This macro fails if macro is not defined, even when using older versions of M4 that did not warn. See
m4_undefine. Unfortunately, in order to support these older versions of M4, there are some situations involving unbalanced quotes where concatenating multiple macros together will work in newer M4 but not in m4sugar; use quadrigraphs to work around this.
See Diversion support, for more details about the use of the diversion stack. In particular, this implies that diversion should be a named diversion rather than a raw number. But be aware that it is seldom necessary to explicitly change the diversion stack, and that when done incorrectly, it can lead to syntactically invalid scripts.
m4_dumpdefis like the M4 builtin, except that this version requires at least one argument, output always goes to standard error rather than the current debug file, no sorting is done on multiple arguments, and an error is issued if any name is undefined.
m4_dumpdefsis a convenience macro that calls
m4_dumpdeffor all of the
m4_pushdefstack of definitions, starting with the current, and silently does nothing if name is undefined.
Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a builtin is output as the empty string. This behavior is rectified by using M4 1.6 or newer. However, this behavior difference means that
m4_dumpdefshould only be used while developing m4sugar macros, and never in the final published form of a macro.
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.
maketempto 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
mkstempthat always creates a uniquely named file, but not all versions of GNU M4 support the new macro. In M4sugar,
m4_mkstempare synonyms for each other, and both have the secure semantics regardless of which macro the underlying M4 provides.
if you are not sure whether macro is defined.
Unlike the M4 builtin, at least one diversion must be specified. Also, since the M4sugar diversion stack prefers named diversions, the use of
m4_undivertto include files is risky. See Diversion support, for more details about the use of the diversion stack. But be aware that it is seldom necessary to explicitly change the diversion stack, and that when done incorrectly, it can lead to syntactically invalid scripts.
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_wrapto provide FIFO semantics and
m4_wrap_lifofor 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_wrapfrom within wrapped text work just as in the builtin.