File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Up: Compatibility

16.1 Extensions in GNU M4
=========================

This version of ‘m4’ contains a few facilities that do not exist in
System V ‘m4’.  These extra facilities are all suppressed by using the
‘-G’ command line option (*note Invoking m4: Limits control.), unless
overridden by other command line options.

   • In the ‘$N’ notation for macro arguments, N can contain several
     digits, while the System V ‘m4’ only accepts one digit.  This
     allows macros in GNU ‘m4’ to take any number of arguments, and not
     only nine (*note Arguments::).

     This means that ‘define(`foo', `$11')’ is ambiguous between
     implementations.  To portably choose between grabbing the first
     parameter and appending 1 to the expansion, or grabbing the
     eleventh parameter, you can do the following:

          define(`a1', `A1')
          ⇒
          dnl First argument, concatenated with 1
          define(`_1', `$1')define(`first1', `_1($@)1')
          ⇒
          dnl Eleventh argument, portable
          define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))')
          ⇒
          dnl Eleventh argument, GNU style
          define(`Eleventh', `$11')
          ⇒
          first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
          ⇒A1
          eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
          ⇒k
          Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
          ⇒k

     Also see the ‘argn’ macro (*note Shift::).

   • The ‘divert’ (*note Divert::) macro can manage more than 9
     diversions.  GNU ‘m4’ treats all positive numbers as valid
     diversions, rather than discarding diversions greater than 9.

   • Files included with ‘include’ and ‘sinclude’ are sought in a user
     specified search path, if they are not found in the working
     directory.  The search path is specified by the ‘-I’ option and the
     ‘M4PATH’ environment variable (*note Search Path::).

   • Arguments to ‘undivert’ can be non-numeric, in which case the named
     file will be included uninterpreted in the output (*note
     Undivert::).

   • Formatted output is supported through the ‘format’ builtin, which
     is modeled after the C library function ‘printf’ (*note Format::).

   • Searches and text substitution through basic regular expressions
     are supported by the ‘regexp’ (*note Regexp::) and ‘patsubst’
     (*note Patsubst::) builtins.  Some BSD implementations use extended
     regular expressions instead.

   • The output of shell commands can be read into ‘m4’ with ‘esyscmd’
     (*note Esyscmd::).

   • There is indirect access to any builtin macro with ‘builtin’ (*note
     Builtin::).

   • Macros can be called indirectly through ‘indir’ (*note Indir::).

   • The name of the program, the current input file, and the current
     input line number are accessible through the builtins
     ‘__program__’, ‘__file__’, and ‘__line__’ (*note Location::).

   • The format of the output from ‘dumpdef’ and macro tracing can be
     controlled with ‘debugmode’ (*note Debug Levels::).

   • The destination of trace and debug output can be controlled with
     ‘debugfile’ (*note Debug Output::).

   • The ‘maketemp’ (*note Mkstemp::) macro behaves like ‘mkstemp’,
     creating a new file with a unique name on every invocation, rather
     than following the insecure behavior of replacing the trailing ‘X’
     characters with the ‘m4’ process id.

   • POSIX only requires support for the command line options ‘-s’,
     ‘-D’, and ‘-U’, so all other options accepted by GNU M4 are
     extensions.  *Note Invoking m4::, for a description of these
     options.

     The debugging and tracing facilities in GNU ‘m4’ are much more
     extensive than in most other versions of ‘m4’.