# m4(9)

    Command:   m4 - macro processor
    Syntax:    m4 [-D name = value] [-U name]
    Flags:     -D  Define a symbol
               -U  Undefine a symbol
    Example:   m4 <m4test               # Run M4

         M4 is a macro processor intended as a front end for Ratfor, Pascal,
    and  other  languages  that  do  not  have  a  built-in macro processing
    capability.  M4 reads standard input, the processed text is  written  on
    the standard output.

         The options and their effects are as follows:

          -D name[=val]  Defines name to val, or to null in val's absence.
          -U name        Undefines name.

         Macro calls have the form: name(arg1,arg2, ..., argn)

    The '(' must immediately follow the name of the macro. If the name of  a
    defined  macro  is  not followed by a ( it is taken to be a call of that
    macro with no arguments, i.e. name().  Potential macro names consist  of
    alphabetic letters and digits.

         Leading unquoted  blanks,  tabs  and  newlines  are  ignored  while
    collecting  arguments.   Left  and right single quotes are used to quote
    strings.  The value of a quoted string is the  string  stripped  of  the
    quotes.

         When a macro name is recognized, its  arguments  are  collected  by
    searching for a matching ).  If fewer arguments are supplied than are in
    the macro definition, the trailing  arguments  are  taken  to  be  null.
    Macro   evaluation  proceeds  normally  during  the  collection  of  the
    arguments, and any commas or right parentheses which happen to  turn  up
    within  the  value  of  a  nested  call are as effective as those in the
    original input text.  (This is typically referred as   inside-out  macro
    expansion.)  After argument collection, the value of the macro is pushed
    back onto the input stream and rescanned.

         M4 makes available the following  built-in  macros.   They  may  be
    redefined,  but  once  this is done the original meaning is lost.  Their
    values are null unless otherwise stated.

         define "(name [, val])" the second argument  is  installed  as  the
    value  of  the  macro  whose name is the first argument.  If there is no
    second argument, the value is null.  Each  occurrence  of  $  n  in  the
    replacement text, where n is a digit, is replaced by the n -th argument.
    Argument 0 is the name of the macro; missing arguments are  replaced  by
    the null string.

         defn "(name [, name ...])" returns the  quoted  definition  of  its
    argument(s). Useful in renaming macros.

         undefine "(name [,  name  ...])"  removes  the  definition  of  the
    macro(s)  named.  If  there  is  more  than one definition for the named
    macro, (due to previous use of pushdef) all definitions are removed.

         pushdef "(name [,  val])"  like  define,  but  saves  any  previous
    definition by stacking the current definition.

         popdef "(name [, name ...])"  removes  current  definition  of  its
    argument(s), exposing the previous one if any.

         ifdef "(name, if-def [,  ifnot-def])"  if  the  first  argument  is
    defined,  the  value  is  the  second argument, otherwise the third.  If
    there is no third argument, the value is null.  A  word  indicating  the
    current operating system is predefined.  (e.g. unix or vms).

         shift "(arg, arg, arg, ...)" returns all but  its  first  argument.
    The  other  arguments are quoted and pushed back with commas in between.
    The  quoting  nullifies  the  effect  of  the  extra  scan   that   will
    subsequently be performed.

         changequote "(lqchar, rqchar)" change quote symbols  to  the  first
    and  second  arguments.  With no arguments, the quotes are reset back to
    the default characters. (i.e., `').

         changecom "(lcchar, rcchar)" change left and right comment  markers
    from  the  default  #  and  newline.   With  no  arguments,  the comment
    mechanism is reset back to the default characters.  With  one  argument,
    the  left  marker  becomes  the  argument  and  the right marker becomes
    newline.  With two arguments, both markers are affected.

         divert  "(divnum)"  maintains  10  output  streams,  numbered  0-9.
    Initially  stream  0 is the current stream. The divert macro changes the
    current output stream to its (digit-string) argument.   Output  diverted
    to a stream other than 0 through 9 is lost.

         undivert "([divnum [, divnum ...]])"  causes  immediate  output  of
    text  from  diversions  named  as  argument(s),  or all diversions if no
    argument.  Text may be undiverted into another  diversion.   Undiverting
    discards the diverted text. At the end of input processing, M4 forces an
    automatic undivert unless is defined.

         divnum "()" returns the value of the current output stream.

         dnl "()" reads and discards characters up to and including the next
    newline.

         ifelse "(arg, arg, if-same [, ifnot-same  |  arg,  arg  ...])"  has
    three  or  more  arguments.  If the first argument is the same string as
    the second, then the value is the third argument.  If not, and if  there
    are  more than four arguments, the process is repeated with arguments 4,
    5, 6 and 7.  Otherwise, the value is either the fourth string, or, if it
    is not present, null.

         incr "(num)" returns the value of its argument  incremented  by  1.
    The  value  of  the  argument  is  calculated by interpreting an initial
    digit-string as a decimal number.

         decr "(num)" returns the value of its argument decremented by 1.

         eval  "(expression)"  evaluates  its   argument   as   a   constant
    expression,  using integer arithmetic.  The evaluation mechanism is very
    similar to that of cpp (#if expression).   The  expression  can  involve
    only  integer  constants  and character constants, possibly connected by
    the binary operators

          *    /    %    +    -    >>   <<    <    >   <=   >=   ==   !=   &
          ^    |     &&   ||

    or the unary operators - ! or tilde or by the ternary  operator  ?  :  .
    Parentheses  may be used for grouping. Octal numbers may be specified as
    in C.

         len "(string)" returns the number of characters in its argument.

         index "(search-string, string)" returns the position in  its  first
    argument  where  the  second  argument begins (zero origin), or 1 if the
    second argument does not occur.

         substr "(string, index [, length])"  returns  a  substring  of  its
    first  argument.  The  second argument is a zero origin number selecting
    the first character (internally treated as  an  expression);  the  third
    argument  indicates  the  length  of  the  substring.   A  missing third
    argument is taken to be large enough to extend to the end of  the  first
    string.

         translit  "(source, from [, to])" transliterates the characters  in
    its  first argument from the set given by the second argument to the set
    given by the third.  If the third argument is shorter than  the  second,
    all  extra  characters in the second argument are deleted from the first
    argument. If the third argument is missing altogether, all characters in
    the second argument are deleted from the first argument.

         include "(filename)" returns the contents of the file that is named
    in the argument.

         sinclude "(filename)"is identical to include, except that  it  says
    nothing if the file is inaccessable.

         paste "(filename)" returns the contents of the file  named  in  the
    argument without any processing, unlike include.

         spaste "(filename)" is identical to  paste,  except  that  it  says
    nothing if the file is inaccessibl[De.

         syscmd "(command)" executes the UNIX command  given  in  the  first
    argument. No value is returned.

         sysval "()" is the return code from the last call to syscmd.
     .PP maketemp '(string)" fills in a string of  XXXXXX  in  its  argument
    with the current process ID.

         m4exit "([exitcode])" causes immediate exit from M4.   Argument  1,
    if given, is the exit code; the default is 0.

         m4wrap "(m4-macro-or-built-n)" argument 1 will be  pushed  back  at
    final EOF; example: m4wrap(`dumptable()').

         errprint "(str [,  str,  str,  ...])"  prints  its  argument(s)  on
    stderr.  If  there is more than one argument, each argument is separated
    by a space during the output.  An arbitrary number of arguments  may  be
    supplied.

         dumpdef "([name, name, ...])" prints current names and definitions,
    for the named items, or for all if no arguments are given.

    Author

         M4 was written by Ozan S. Yigif.