m4: Trace

1 
1 7.2 Tracing macro calls
1 =======================
1 
1 It is possible to trace macro calls and expansions through the builtins
1 'traceon' and 'traceoff':
1 
1  -- Builtin: traceon ([NAMES...])
1  -- Builtin: traceoff ([NAMES...])
1      When called without any arguments, 'traceon' and 'traceoff' will
1      turn tracing on and off, respectively, for all currently defined
1      macros.
1 
1      When called with arguments, only the macros listed in NAMES are
1      affected, whether or not they are currently defined.
1 
1      The expansion of 'traceon' and 'traceoff' is void.
1 
1    Whenever a traced macro is called and the arguments have been
1 collected, the call is displayed.  If the expansion of the macro call is
1 not void, the expansion can be displayed after the call.  The output is
11 printed to the current debug file (defaulting to standard error, ⇒
 Debug Output).
1 
1      $ m4 -d
1      define(`foo', `Hello World.')
1      =>
1      define(`echo', `$@')
1      =>
1      traceon(`foo', `echo')
1      =>
1      foo
1      error->m4trace: -1- foo -> `Hello World.'
1      =>Hello World.
1      echo(`gnus', `and gnats')
1      error->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
1      =>gnus,and gnats
1 
1    The number between dashes is the depth of the expansion.  It is one
1 most of the time, signifying an expansion at the outermost level, but it
1 increases when macro arguments contain unquoted macro calls.  The
1 maximum number that will appear between dashes is controlled by the
1 option '--nesting-limit' (or '-L', ⇒Invoking m4 Limits control.).
1 Additionally, the option '--trace' (or '-t') can be used to invoke
1 'traceon(NAME)' before parsing input.
1 
1      $ m4 -L 3 -t ifelse
1      ifelse(`one level')
1      error->m4trace: -1- ifelse
1      =>
1      ifelse(ifelse(ifelse(`three levels')))
1      error->m4trace: -3- ifelse
1      error->m4trace: -2- ifelse
1      error->m4trace: -1- ifelse
1      =>
1      ifelse(ifelse(ifelse(ifelse(`four levels'))))
1      error->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
1 
1    Tracing by name is an attribute that is preserved whether the macro
1 is defined or not.  This allows the selection of macros to trace before
1 those macros are defined.
1 
1      $ m4 -d
1      traceoff(`foo')
1      =>
1      traceon(`foo')
1      =>
1      foo
1      =>foo
1      defn(`foo')
1      =>
1      define(`foo', `bar')
1      =>
1      foo
1      error->m4trace: -1- foo -> `bar'
1      =>bar
1      undefine(`foo')
1      =>
1      ifdef(`foo', `yes', `no')
1      =>no
1      indir(`foo')
1      error->m4:stdin:9: undefined macro `foo'
1      =>
1      define(`foo', `blah')
1      =>
1      foo
1      error->m4trace: -1- foo -> `blah'
1      =>blah
1      traceoff
1      =>
1      foo
1      =>blah
1 
1    Tracing even works on builtins.  However, 'defn' (⇒Defn) does
1 not transfer tracing status.
1 
1      $ m4 -d
1      traceon(`traceon')
1      =>
1      traceon(`traceoff')
1      error->m4trace: -1- traceon(`traceoff')
1      =>
1      traceoff(`traceoff')
1      error->m4trace: -1- traceoff(`traceoff')
1      =>
1      traceoff(`traceon')
1      =>
1      traceon(`eval', `m4_divnum')
1      =>
1      define(`m4_eval', defn(`eval'))
1      =>
1      define(`m4_divnum', defn(`divnum'))
1      =>
1      eval(divnum)
1      error->m4trace: -1- eval(`0') -> `0'
1      =>0
1      m4_eval(m4_divnum)
1      error->m4trace: -2- m4_divnum -> `0'
1      =>0
1 
1    ⇒Debug Levels, for information on controlling the details of
1 the display.  The format of the trace output is not specified by POSIX,
1 and varies between implementations of 'm4'.
1