m4: Location

1 
1 14.2 Printing current location
1 ==============================
1 
1 To make it possible to specify the location of an error, three utility
1 builtins exist:
1 
1  -- Builtin: __file__
1  -- Builtin: __line__
1  -- Builtin: __program__
1      Expand to the quoted name of the current input file, the current
1      input line number in that file, and the quoted name of the current
1      invocation of 'm4'.
1 
1      errprint(__program__:__file__:__line__: `input error
1      ')
1      error->m4:stdin:1: input error
1      =>
1 
1    Line numbers start at 1 for each file.  If the file was found due to
1 the '-I' option or 'M4PATH' environment variable, that is reflected in
DONTPRINTYET 11 the file name.  The syncline option ('-s', ⇒Invoking m4
 Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (*note1DONTPRINTYET 11 the file name.  The syncline option ('-s', ⇒Invoking m4
 Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (⇒
 Debug Levels), also use this notion of current file and line.
1 Redefining the three location macros has no effect on syncline, debug,
1 warning, or error message output.
1 
1 Include::):
1 
1      $ m4 -I examples
1      define(`foo', ``$0' called at __file__:__line__')
1      =>
1      foo
1      =>foo called at stdin:2
1      include(`incl.m4')
1      =>Include file start
1      =>foo called at examples/incl.m4:2
1      =>Include file end
1      =>
1 
1    The location of macros invoked during the rescanning of macro
1 expansion text corresponds to the location in the file where the
1 expansion was triggered, regardless of how many newline characters the
1 expansion text contains.  As of GNU M4 1.4.8, the location of text
1 wrapped with 'm4wrap' (⇒M4wrap) is the point at which the
1 'm4wrap' was invoked.  Previous versions, however, behaved as though
1 wrapped text came from line 0 of the file "".
1 
1      define(`echo', `$@')
1      =>
1      define(`foo', `echo(__line__
1      __line__)')
1      =>
1      echo(__line__
1      __line__)
1      =>4
1      =>5
1      m4wrap(`foo
1      ')
1      =>
1      foo(errprint(__line__
1      __line__
1      ))
1      error->8
1      error->9
1      =>8
1      =>8
1      __line__
1      =>11
1      m4wrap(`__line__
1      ')
1      =>
1      ^D
1      =>12
1      =>6
1      =>6
1 
1    The '__program__' macro behaves like '$0' in shell terminology.  If
1 you invoke 'm4' through an absolute path or a link with a different
1 spelling, rather than by relying on a 'PATH' search for plain 'm4', it
1 will affect how '__program__' expands.  The intent is that you can use
1 it to produce error messages with the same formatting that 'm4' produces
1 internally.  It can also be used within 'syscmd' (⇒Syscmd) to
1 pick the same version of 'm4' that is currently running, rather than
1 whatever version of 'm4' happens to be first in 'PATH'.  It was first
1 introduced in GNU M4 1.4.6.
1