autoconf: Redefined M4 Macros
1
1 8.3.1 Redefined M4 Macros
1 -------------------------
1
1 With a few exceptions, all the M4 native macros are moved in the `m4_'
1 pseudo-namespace, e.g., M4sugar renames `define' as `m4_define' etc.
1
1 The list of macros unchanged from M4, except for their name, is:
1 - m4_builtin
1
1 - m4_changecom
1
1 - m4_changequote
1
1 - m4_debugfile
1
1 - m4_debugmode
1
1 - m4_decr
1
1 - m4_define
1
1 - m4_divnum
1
1 - m4_errprint
1
1 - m4_esyscmd
1
1 - m4_eval
1
1 - m4_format
1
1 - m4_ifdef
1
1 - m4_incr
1
1 - m4_index
1
1 - m4_indir
1
1 - m4_len
1
1 - m4_pushdef
1
1 - m4_shift
1
1 - m4_substr
1
1 - m4_syscmd
1
1 - m4_sysval
1
1 - m4_traceoff
1
1 - m4_traceon
1
1 - m4_translit
1
1 Some M4 macros are redefined, and are slightly incompatible with
1 their native equivalent.
1
1 -- Macro: __file__
1 -- Macro: __line__
1 All M4 macros starting with `__' retain their original name: for
1 example, no `m4__file__' is defined.
1
1 -- Macro: __oline__
1 This is not technically a macro, but a feature of Autom4te. The
1 sequence `__oline__' can be used similarly to the other m4sugar
1 location macros, but rather than expanding to the location of the
1 input file, it is translated to the line number where it appears
1 in the output file after all other M4 expansions.
1
1 -- Macro: dnl
1 This macro kept its original name: no `m4_dnl' is defined.
1
1 -- Macro: m4_bpatsubst (STRING, REGEXP, [REPLACEMENT])
1 This macro corresponds to `patsubst'. The name `m4_patsubst' is
1 kept for future versions of M4sugar, once GNU M4 2.0 is released
1 and supports extended regular expression syntax.
1
1 -- Macro: m4_bregexp (STRING, REGEXP, [REPLACEMENT])
1 This macro corresponds to `regexp'. The name `m4_regexp' is kept
1 for future versions of M4sugar, once GNU M4 2.0 is released and
1 supports extended regular expression syntax.
1
1 -- Macro: m4_copy (SOURCE, DEST)
1 -- Macro: m4_copy_force (SOURCE, DEST)
1 -- Macro: m4_rename (SOURCE, DEST)
1 -- Macro: m4_rename_force (SOURCE, DEST)
1 These macros aren't directly builtins, but are closely related to
1 `m4_pushdef' and `m4_defn'. `m4_copy' and `m4_rename' ensure that
1 DEST is undefined, while `m4_copy_force' and `m4_rename_force'
1 overwrite any existing definition. All four macros then proceed
1 to copy the entire pushdef stack of definitions of SOURCE over to
1 DEST. `m4_copy' and `m4_copy_force' preserve the source
1 (including in the special case where SOURCE is undefined), while
1 `m4_rename' and `m4_rename_force' undefine the original macro name
1 (making it an error to rename an undefined SOURCE).
1
1 Note that attempting to invoke a renamed macro might not work,
1 since the macro may have a dependence on helper macros accessed
1 via composition of `$0' but that were not also renamed; likewise,
1 other macros may have a hard-coded dependence on SOURCE and could
1 break if SOURCE has been deleted. On the other hand, it is always
1 safe to rename a macro to temporarily move it out of the way, then
1 rename it back later to restore original semantics.
1
1 -- Macro: m4_defn (MACRO...)
1 This macro fails if MACRO is not defined, even when using older
1 versions of M4 that did not warn. See `m4_undefine'.
1 Unfortunately, in order to support these older versions of M4,
1 there are some situations involving unbalanced quotes where
1 concatenating multiple macros together will work in newer M4 but
1 not in m4sugar; use quadrigraphs to work around this.
1
1 -- Macro: m4_divert (DIVERSION)
1 M4sugar relies heavily on diversions, so rather than behaving as a
1 primitive, `m4_divert' behaves like:
1 m4_divert_pop()m4_divert_push([DIVERSION])
1 ⇒Diversion support, for more details about the use of the
1 diversion stack. In particular, this implies that DIVERSION
1 should be a named diversion rather than a raw number. But be
1 aware that it is seldom necessary to explicitly change the
1 diversion stack, and that when done incorrectly, it can lead to
1 syntactically invalid scripts.
1
1 -- Macro: m4_dumpdef (NAME...)
1 -- Macro: m4_dumpdefs (NAME...)
1 `m4_dumpdef' is like the M4 builtin, except that this version
1 requires at least one argument, output always goes to standard
1 error rather than the current debug file, no sorting is done on
1 multiple arguments, and an error is issued if any NAME is
1 undefined. `m4_dumpdefs' is a convenience macro that calls
1 `m4_dumpdef' for all of the `m4_pushdef' stack of definitions,
1 starting with the current, and silently does nothing if NAME is
1 undefined.
1
1 Unfortunately, due to a limitation in M4 1.4.x, any macro defined
1 as a builtin is output as the empty string. This behavior is
1 rectified by using M4 1.6 or newer. However, this behavior
1 difference means that `m4_dumpdef' should only be used while
1 developing m4sugar macros, and never in the final published form
1 of a macro.
1
1 -- Macro: m4_esyscmd_s (COMMAND)
1 Like `m4_esyscmd', this macro expands to the result of running
1 COMMAND in a shell. The difference is that any trailing newlines
1 are removed, so that the output behaves more like shell command
1 substitution.
1
1 -- Macro: m4_exit (EXIT-STATUS)
1 This macro corresponds to `m4exit'.
1
1 -- Macro: m4_if (COMMENT)
1 -- Macro: m4_if (STRING-1, STRING-2, EQUAL, [NOT-EQUAL])
1 -- Macro: m4_if (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4,
1 EQUAL-2, ..., [NOT-EQUAL])
1 This macro corresponds to `ifelse'. STRING-1 and STRING-2 are
1 compared literally, so usually one of the two arguments is passed
1 unquoted. ⇒Conditional constructs, for more conditional
1 idioms.
1
1 -- Macro: m4_include (FILE)
1 -- Macro: m4_sinclude (FILE)
1 Like the M4 builtins, but warn against multiple inclusions of FILE.
1
1 -- Macro: m4_mkstemp (TEMPLATE)
1 -- Macro: m4_maketemp (TEMPLATE)
1 Posix requires `maketemp' to replace the trailing `X' characters
1 in TEMPLATE with the process id, without regards to the existence
1 of a file by that name, but this a security hole. When this was
1 pointed out to the Posix folks, they agreed to invent a new macro
1 `mkstemp' that always creates a uniquely named file, but not all
1 versions of GNU M4 support the new macro. In M4sugar,
1 `m4_maketemp' and `m4_mkstemp' are synonyms for each other, and
1 both have the secure semantics regardless of which macro the
1 underlying M4 provides.
1
1 -- Macro: m4_popdef (MACRO...)
1 This macro fails if MACRO is not defined, even when using older
1 versions of M4 that did not warn. See `m4_undefine'.
1
1 -- Macro: m4_undefine (MACRO...)
1 This macro fails if MACRO is not defined, even when using older
1 versions of M4 that did not warn. Use
1
1 m4_ifdef([MACRO], [m4_undefine([MACRO])])
1
1 if you are not sure whether MACRO is defined.
1
1 -- Macro: m4_undivert (DIVERSION...)
1 Unlike the M4 builtin, at least one DIVERSION must be specified.
1 Also, since the M4sugar diversion stack prefers named diversions,
11 the use of `m4_undivert' to include files is risky. ⇒
Diversion support, for more details about the use of the
1 diversion stack. But be aware that it is seldom necessary to
1 explicitly change the diversion stack, and that when done
1 incorrectly, it can lead to syntactically invalid scripts.
1
1 -- Macro: m4_wrap (TEXT)
1 -- Macro: m4_wrap_lifo (TEXT)
1 These macros correspond to `m4wrap'. Posix requires arguments of
1 multiple wrap calls to be reprocessed at EOF in the same order as
1 the original calls (first-in, first-out). GNU M4 versions through
1 1.4.10, however, reprocess them in reverse order (last-in,
1 first-out). Both orders are useful, therefore, you can rely on
1 `m4_wrap' to provide FIFO semantics and `m4_wrap_lifo' for LIFO
1 semantics, regardless of the underlying GNU M4 version.
1
1 Unlike the GNU M4 builtin, these macros only recognize one
1 argument, and avoid token pasting between consecutive invocations.
1 On the other hand, nested calls to `m4_wrap' from within wrapped
1 text work just as in the builtin.
1