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