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.
All M4 macros starting with ‘__’ retain their original name: for
example, no m4__file__ is defined.
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.
This macro kept its original name: no m4_dnl is defined.
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.
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.
These macros aren’t directly builtins, but are closely related to
m4_pushdef and m4_defn. m4_copy and
m4_rename ensure that dest is undefined, while
m4_copy_force and m4_rename_force overwrite any existing
definition. All four macros then proceed to copy the entire pushdef
stack of definitions of source over to dest. m4_copy
and m4_copy_force preserve the source (including in the special
case where source is undefined), while m4_rename and
m4_rename_force undefine 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.
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. 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_dumpdef is 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_dumpdefs is a convenience macro that
calls m4_dumpdef for all of the
m4_pushdef stack 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_dumpdef should only be used while developing m4sugar macros,
and never in the final published form of a macro.
Like m4_esyscmd, this macro expands to the result of running
command in a shell. The difference is that any trailing newlines
are removed, so that the output behaves more like shell command
substitution.
This macro corresponds to m4exit.
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.
Like the M4 builtins, but warn against multiple inclusions of file.
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.
This macro fails if macro is not defined, even when using older
versions of M4 that did not warn. See m4_undefine.
This macro fails if macro is not defined, even when using older versions of M4 that did not warn. Use
m4_ifdef([macro], [m4_undefine([macro])])
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_undivert to 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_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.