File: autoconf.info,  Node: Redefined M4 Macros,  Next: Diagnostic Macros,  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:
   − m4_builtin
   − m4_changecom
   − m4_changequote
   − m4_debugfile
   − m4_debugmode
   − m4_decr
   − m4_define
   − m4_divnum
   − m4_errprint
   − m4_esyscmd
   − m4_eval
   − m4_format
   − m4_ifdef
   − m4_incr
   − m4_index
   − m4_indir
   − m4_len
   − m4_pushdef
   − m4_shift
   − m4_substr
   − m4_syscmd
   − m4_sysval
   − m4_traceoff
   − m4_traceon
   − m4_translit

   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_copy (SOURCE, DEST)
 -- Macro: m4_copy_force (SOURCE, DEST)
 -- Macro: m4_rename (SOURCE, DEST)
 -- Macro: m4_rename_force (SOURCE, DEST)
     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.

 -- Macro: m4_defn (MACRO...)
     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.

 -- 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])
     *Note 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.

 -- Macro: m4_dumpdef (NAME...)
 -- Macro: m4_dumpdefs (NAME...)
     ‘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.

 -- Macro: m4_esyscmd_s (COMMAND)
     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.

 -- 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-1, STRING-3, STRING-4,
          EQUAL-2, ..., [NOT-EQUAL])
     This macro corresponds to ‘ifelse’.  STRING-1 and STRING-2 are
     compared literally, so usually one of the two arguments is passed
     unquoted.  *Note 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...)
     This macro fails if MACRO is not defined, even when using older
     versions of M4 that did not warn.  See ‘m4_undefine’.

 -- Macro: m4_undefine (MACRO...)
     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.

 -- Macro: m4_undivert (DIVERSION...)
     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.  *Note
     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.

 -- 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.