(autoconf.info)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_dumpdef

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


automatically generated by info2www