13. Miscellaneous builtin macros

This chapter describes various builtins, that do not really belong in any of the previous chapters.

13.1 Printing error messages

You can print error messages using errprint:

Builtin: errprint (message, …)

Prints message and the rest of the arguments on the standard error output, separated by spaces.

The expansion of errprint is void. The macro errprint is recognized only with parameters.

errprint(`Invalid arguments to forloop
')
error-->Invalid arguments to forloop
⇒

A trailing newline is not printed automatically, so it must be supplied as part of the argument, as in the example. BSD implementations of m4 do append a trailing newline on each errprint call, while some other implementations only print the first argument.

13.2 Printing current location

To make it possible to specify the location of an error, three utility builtins exist:

Builtin: __file__

Builtin: __line__

Builtin: __program__

Expand to the quoted name of the current input file, the current input line number in that file, and the quoted name of the current invocation of m4.

errprint(__program__:__file__:__line__: `input error
')
error-->m4:stdin:1: input error
⇒

Line numbers start at 1 for each file. If the file was found due to the `-I' option or M4PATH environment variable, that is reflected in the file name. The syncline option (`-s', see section Invoking m4), and the `f' and `l' flags of debugmode (see section Controlling debugging output), also use this notion of current file and line. Redefining the three location macros has no effect on syncline, debug, or warning message output. Assume this example is run in the `checks' directory of the GNU M4 package, using `--include=../examples' in the command line to find the file `incl.m4' mentioned earlier:

define(`foo', ``$0' called at __file__:__line__')
⇒
foo
⇒foo called at stdin:2
include(`incl.m4')
⇒Include file start
⇒foo called at ../examples/incl.m4:2
⇒Include file end
⇒

Currently, all text wrapped with m4wrap (see section Saving input) behaves as though it came from line 0 of the file "". It is hoped that a future release of m4 can overcome this limitation and remember which file invoked the call to m4wrap.

The __program__ macro behaves like `$0' in shell terminology. If you invoke m4 through an absolute path or a link with a different spelling, rather than by relying on a PATH search for plain `m4', it will affect how __program__ expands. The intent is that you can use it to produce error messages with the same formatting that m4 produces internally. It can also be used within syscmd (see section Executing simple commands) to pick the same version of m4 that is currently running, rather than whatever version of m4 happens to be first in PATH.

13.3 Exiting from m4

If you need to exit from m4 before the entire input has been read, you can use m4exit:

Builtin: m4exit ([code = `'])

Causes m4 to exit, with exit status code. If code is left out, the exit status is zero. If code cannot be parsed, or is outside the range of 0 to 255, the exit status is one. No further input is read, and all wrapped and diverted text is discarded.

A common use of this is to abort processing:

Composite: fatal_error (message)

Abort processing with an error message and non-zero status. Prefix message with details about where the error occurred, and print the resulting string to standard error.

define(`fatal_error',
       `errprint(__program__:__file__:__line__`: fatal error: $*
')m4exit(`1')')
⇒
fatal_error(`this is a BAD one, buster')
error-->m4:stdin:4: fatal error: this is a BAD one, buster

After this macro call, m4 will exit with exit status 1. This macro is only intended for error exits, since the normal exit procedures are not followed, e.g., diverted text is not undiverted, and saved text (see section Saving input) is not reread. (This macro has a subtle bug, when invoked from wrapped text. You should try to see if you can find it and correct it. see section Correct version of some examples)

m4wrap(`This text is lost to `m4exit'.')
⇒
divert(`1') And so is this.
divert
⇒
m4exit

Note that it is still possible for the exit status to be different than what was requested by m4exit. If m4 detects some other error, such as a write error on standard out, the exit status will be non-zero even if m4exit requested zero.

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.