m4 -- Command

Macro processor
m4 [file ...]

The command m4 processes macros.  It allows you to define strings for which
m4 is to search, and strings to replace them; m4 then opens file, reads its
contents, replaces  each macro with  its specified replacement  string, and
writes the results into the standard output stream.

m4  can   also  manipulate   files,  make  conditional   decisions,  select
substrings, and  perform arithmetic.  The  tutorial Introduction to  the m4
Macro Processor introduces m4 in detail.

m4 reads its  files in the order given; if  no file is named, then it reads
the standard input stream.  The file name `-' indicates the standard input.

m4 copies input  to output until it finds a  potential macro.  A macro is a
string of alphanumerics  (letters, digits, or underscores) that begins with
a non-digit  character and is surrounded by  non-alphanumerics.  If m4 does
not recognize  the macro, it simply  copies it to the  output and continues
processing.  If  m4 recognizes the macro  and the next character  is a left
parenthesis `(', an argument set follows:

    macro(arg1,..., argn)

The arguments are collected by processing  them in the same manner as other
text (thus, an arguments may itself be another macro), and resulting output
text is  diverted into storage.  m4  stores up to nine  arguments; any more
will be  processed but not saved.   An argument set consists  of strings of
text separated  by commas (commas inside quotation  marks or parentheses do
not terminate an argument),  and must contain balanced parentheses that are
free of  quotation marks (i.e., that are unquoted).  m4 strips arguments of
unquoted leading space (blanks, tabs, newline characters).

m4 then  removes the  macro and  its optional argument  set from  the input
stream,  processes them,  and replaces  them in the  input stream  with the
resulting value.  The value becomes the next piece of text to be read.

Quotation marks, of the form ` ',  inhibit  the  recognition of  macro.  m4
strips off one level of  quotation marks when it encounters them (quotation
marks are  nestable).  Thus,  `macro' is not  processed, but is  changed to
macro and passed on.

m4 determines  the value of  a user-defined macro  by taking the  text that
constitutes the macro's definition and replacing any occurrence within that
text  of `$n'  (where  n is  `0'  through `9')  with  the text  of the  nth
argument.  Argument 0 is the macro itself.

m4 recognizes the following predefined macros:

changequote[([openquote],[closequote])]
     Changes the quotation  characters.  Missing arguments default to ` for
     open or '  for close.  Quotation characters will not  nest if they are
     defined to be the same character.  Value is null.

decr[(number)]
     Decrement number (default, 0) by one and returns resulting value.

define(macro,definition)
     Define  or redefine  macro. If  a predefined  macro is  redefined, its
     original definition is irrecoverably lost.  Value is null.

divert[(n)]
     Redirects output  to output stream n (default  is zero).  The standard
     output  is zero,  and  one through  nine are  maintained as  temporary
     files.  Any other n results in output being thrown away until the next
     divert macro.  Value is null.

divnum
     Value is current output stream number.

dnl  Delete to newline: removes all  characters from the input stream up to
     and including the next newline.  Value is null.

dumpdef[(macros)]
     Value  is quoted  definitions of  all macros  specified, or  names and
     definitions of all defined macros if no arguments.

errprint(text)
     Print text on standard error file.  Value is null.

eval(expression)
     Value  is a  number  that is  the  value of  evaluated expression.  It
     recognizes, in order  of decreasing precedence: parentheses, **, unary
     +  -, *  / %,  binary  + -,  relations, and  logicals.  Arithmetic  is
     performed in longs.

ifdef(macro,defvalue,undefvalue)
     Return defvalue if macro is defined, and undefvalue if not.

ifelse(arg1,arg2,arg3...)
     Compares arg1  and arg2. If they  are the same, returns  arg3. If not,
     and arg4  is the  last argument,  return arg4. Otherwise,  the process
     repeats, comparing  arg4 and arg5,  and so on.  Like  other m4 macros,
     this takes a maximum of nine arguments.

include(file)
     Value is  the entire contents  of the file  argument.  If file  is not
     accessible, a fatal error results.

incr[(number)]
     Increments given  number (default, zero) by  one and returns resulting
     value.

index(text,pattern)
     Value is  a number  corresponding to position  of pattern in  text. If
     pattern does not occur in text, value is -1.

len(text)
     Value is a number that corresponds to length of text.

maketemp(filenameXXXXXX)
     Value is  filename with last six  characters, usually XXXXXX, replaced
     with current  process id  and a single  letter.  Same as  the COHERENT
     system call mktemp().

sinclude(file)
     Value  is the  entire contents  of  file. If  file is  not accessible,
     return null and continue processing.

substr(text[,start[,count]])
     Value is a substring of text. start may be left-oriented (nonnegative)
     or right-oriented (negative).   count specifies how many characters to
     the right  (if positive) or to  the left (if negative)  to return.  If
     absent, it  is assumed to be  large and of the same  sign as start. If
     start is  omitted, it is  assumed to be  zero if count  is positive or
     omitted, or -1 if count is negative.

syscmd(command)
     Pass  command to  the shell  for execution.  Value  is null.   Same as
     system call system.

translit(text,characters[,replacements])
     Replaces  characters in  text with  the corresponding  characters from
     replacements.  If the  replacements is  absent  or too  short, replace
     characters  with  a  null character.   Value  is  text with  specified
     replacements.

undefine(macro)
     Remove macro  definition.  Value  is null.   If a predefined  macro is
     redefined, its original definition is irrecoverably lost.

undivert[(stream[,...])]
     Dumps each  specified stream into the current  output stream.  With no
     arguments,  undivert dumps  all output streams  in numeric  order.  m4
     will  not  dump  any  output  stream  into  itself.   At  the  end  of
     processing,  m4  automatically dumps  all  diverted  text to  standard
     output in numeric order.  Value is null.

See Also

commands,
mktemp(),
system
Introduction to the m4 Macro Processor

© 2012 by Stephen A. Ness