m4: M4exit

1 
1 14.3 Exiting from 'm4'
1 ======================
1 
1 If you need to exit from 'm4' before the entire input has been read, you
1 can use 'm4exit':
1 
1  -- Builtin: m4exit ([CODE = '0'])
1      Causes 'm4' to exit, with exit status CODE.  If CODE is left out,
1      the exit status is zero.  If CODE cannot be parsed, or is outside
1      the range of 0 to 255, the exit status is one.  No further input is
1      read, and all wrapped and diverted text is discarded.
1 
1      m4wrap(`This text is lost due to `m4exit'.')
1      =>
1      divert(`1') So is this.
1      divert
1      =>
1      m4exit And this is never read.
1 
1    A common use of this is to abort processing:
1 
1  -- Composite: fatal_error (MESSAGE)
1      Abort processing with an error message and non-zero status.  Prefix
1      MESSAGE with details about where the error occurred, and print the
1      resulting string to standard error.
1 
1      define(`fatal_error',
1             `errprint(__program__:__file__:__line__`: fatal error: $*
1      ')m4exit(`1')')
1      =>
1      fatal_error(`this is a BAD one, buster')
1      error->m4:stdin:4: fatal error: this is a BAD one, buster
1 
1    After this macro call, 'm4' will exit with exit status 1.  This macro
1 is only intended for error exits, since the normal exit procedures are
1 not followed, i.e., diverted text is not undiverted, and saved text
1 (⇒M4wrap) is not reread.  (This macro could be made more robust
1 to earlier versions of 'm4'.  You should try to see if you can find
1 weaknesses and correct them; or ⇒Answers Improved fatal_error.).
1 
1    Note that it is still possible for the exit status to be different
1 than what was requested by 'm4exit'.  If 'm4' detects some other error,
1 such as a write error on standard output, the exit status will be
1 non-zero even if 'm4exit' requested zero.
1 
1    If standard input is seekable, then the file will be positioned at
1 the next unread character.  If it is a pipe or other non-seekable file,
1 then there are no guarantees how much data 'm4' might have read into
1 buffers, and thus discarded.
1