m4: Macro Arguments

1 
1 4.3 Macro arguments
1 ===================
1 
1 When a name is seen, and it has a macro definition, it will be expanded
1 as a macro.
1 
1    If the name is followed by an opening parenthesis, the arguments will
1 be collected before the macro is called.  If too few arguments are
1 supplied, the missing arguments are taken to be the empty string.
1 However, some builtins are documented to behave differently for a
1 missing optional argument than for an explicit empty string.  If there
1 are too many arguments, the excess arguments are ignored.  Unquoted
1 leading whitespace is stripped off all arguments, but whitespace
1 generated by a macro expansion or occurring after a macro that expanded
1 to an empty string remains intact.  Whitespace includes space, tab,
1 newline, carriage return, vertical tab, and formfeed.
1 
1      define(`macro', `$1')
1      =>
1      macro( unquoted leading space lost)
1      =>unquoted leading space lost
1      macro(` quoted leading space kept')
1      => quoted leading space kept
1      macro(
1       divert `unquoted space kept after expansion')
1      => unquoted space kept after expansion
1      macro(macro(`
1      ')`whitespace from expansion kept')
1      =>
1      =>whitespace from expansion kept
1      macro(`unquoted trailing whitespace kept'
1      )
1      =>unquoted trailing whitespace kept
1      =>
1 
1    Normally 'm4' will issue warnings if a builtin macro is called with
1 an inappropriate number of arguments, but it can be suppressed with the
11 '--quiet' command line option (or '--silent', or '-Q', ⇒Invoking
 m4 Operation modes.).  For user defined macros, there is no check of
1 the number of arguments given.
1 
1      $ m4
1      index(`abc')
1      error->m4:stdin:1: Warning: too few arguments to builtin `index'
1      =>0
1      index(`abc',)
1      =>0
1      index(`abc', `b', `ignored')
1      error->m4:stdin:3: Warning: excess arguments to builtin `index' ignored
1      =>1
1 
1      $ m4 -Q
1      index(`abc')
1      =>0
1      index(`abc',)
1      =>0
1      index(`abc', `b', `ignored')
1      =>1
1 
1    Macros are expanded normally during argument collection, and whatever
1 commas, quotes and parentheses that might show up in the resulting
1 expanded text will serve to define the arguments as well.  Thus, if FOO
1 expands to ', b, c', the macro call
1 
1      bar(a foo, d)
1 
1 is a macro call with four arguments, which are 'a ', 'b', 'c' and 'd'.
1 To understand why the first argument contains whitespace, remember that
1 unquoted leading whitespace is never part of an argument, but trailing
1 whitespace always is.
1 
1    It is possible for a macro's definition to change during argument
1 collection, in which case the expansion uses the definition that was in
1 effect at the time the opening '(' was seen.
1 
1      define(`f', `1')
1      =>
1      f(define(`f', `2'))
1      =>1
1      f
1      =>2
1 
1    It is an error if the end of file occurs while collecting arguments.
1 
1      hello world
1      =>hello world
1      define(
1      ^D
1      error->m4:stdin:2: ERROR: end of file in argument list
1