

MACRO (1)                    10/1/79                    MACRO (1)


NAME
   macro - general-purpose macro processor

SYNOPSIS
   macro [-0] [files...]

DESCRIPTION
   Macro  is  a general-purpose macro processor.  Macro reads the
   files and writes onto the standard output a new file with  the
   macro  definitions  deleted and the macro references expanded.
   If no files are given, or  the  file  "-"  is  specified,  the
   standard input is read. 

   Macros  permit  the  definition  of symbolic constants so that
   subsequent occurrences of the constant  are  replaced  by  the
   defining  string  of  characters.  The general form of a macro
   definition is

                   define(name,replacement text)

   All subsequent occurrences of  "name"  in  the  file  will  be
   replaced  by  "replacement  text".  The placement of blanks in
   definitions is significant; they should  only  appear  in  the
   replacement  text where desired.  Upper and lower case letters
   are also significant.  The replacement text may be  more  than
   one  line  long.   However, when an entire macro definition is
   followed immediately by a newline, the newline  is  discarded.
   This  prevents  extraneous  blank  lines from appearing in the
   output. 

   Nesting of definitions is allowed, as is recursion. 

   An elementary example of a macro is:

                           define(EOF,-1)

   Thereafter, all occurrences of "EOF"  in  the  file  would  be
   replaced by "-1". 

   Macros  with  arguments may also be specified.  Any occurrence
   in the replacement text of "$n", where n is between 1  and  9,
   will  be  replaced  by  the  nth  argument  when  the macro is
   actually called.  For example,

             define(copen,$3 = open($1,$2)
                     if ($3 == ERR)
                        call cant($1) )

   would define a macro that, when called by

                       copen(name, READ, fd)

   would expand into
             fd = open(name,READ)
             if (fd == ERR)
                call cant(name)







MACRO (1)                    10/1/79                    MACRO (1)


   If a macro  definition  refers  to  an  argument  that  wasn't
   supplied,  the  "$n" will be ignored.  "$0" refers to the name
   of the macro itself.   If  a  character  other  than  a  digit
   follows "$", the "$" is taken literally. 

   Macros  can  be  nested,  and  any  macros  encountered during
   argument collection are expanded immediately, unless they  are
   surrounded  by  brackets  "[]".   That is, input surrounded by
   brackets is left absolutely alone, except that one level of  [
   and  ]  is  stripped  off.   Thus  it is possible to write the
   macro "d" as

                     define(d,[define($1,$2)])

   The replacement text for "d", protected  by  the  brackets  is
   literally "define($1,$2)" so one could say

                              d(a,bc)

   to  define "a" as "bc".  Brackets must also be used when it is
   desired to redefine a macro, e.g. 

                            define(x,y)
                            define(x,z)

   would define "y" in the second  line,  instead  of  redefining
   "x".    To   avoid  redefining  "y",  the  operation  must  be
   expressed as

                            define(x,y)
                            define([x],z)

   Normally, brackets appearing outside any macro  calls  ("level
   0"  brackets)  are  ___not  removed,  unless  the  -0  option  is
   specified. 


   The following built-in macros are provided:

   define(a,b)
        defines a to be b and returns the null string. 

   ifelse(a,b,c,d)
        returns c if a is identical to b and d otherwise. 

   incr(a)
        interprets a as an integer and returns a+1. 

   substr(a,b,c)
        returns a substring of "a" starting at  character  number
        b and extending for c characters. 

   len(a)
        returns the length of a. 

   includ(a)







MACRO (1)                    10/1/79                    MACRO (1)


        returns the contents of file a. 

   expr(a)
        returns  the  result  of  evaluating  infix expression a.
        Operators  in  increasing  order  of  precedence  are  as
        follows.  Parentheses may be used as usual. 

             | &             logical OR and AND
             !               unary logical NOT
             == ^= <= < > >= arithmetic comparison (!= and ~= are
                             equivalent to ^=)
             + -             addition and subtraction
             * / %           multiplication, division, modulo (remainder)
             **              exponentiation
             + -             unary plus and negation

        Logical operators return 0 or 1 (false or true). 

FILES
   None

SEE ALSO
   Kernighan and Plauger's "Software Tools", pages. 251-283
   ratfor

DIAGNOSTICS
   arith evaluation stack overflow
        The  max  level of nested arithmetic expressions has been
        exceeded.  The size is set by the MAXSTACK definition  in
        the source code. 

   arg stack overflow
        The  maximum number of total arguments has been exceeded;
        the size is set by the ARGSIZE definition in  the  source
        code. 

   call stack overflow
        The  maximum  level  of  nesting  of definitions has been
        exceeded.  The size is set by the CALLSIZE definition  in
        the source code. 

   EOF in string
        An  end-of-file  has  been encountered before a bracketed
        string has been terminated. 

   evaluation stack overflow
        The  total  number  of  characters  permitted  for  name,
        definition,  and arguments has been exceeded.  Set by the
        EVALSIZE definition in the source code. 

   unexpected EOF
        An end-of-file was reached before  the  macro  definition
        was terminated. 

   filename: can't open
        The indicated file could not be opened. 







MACRO (1)                    10/1/79                    MACRO (1)


   filename: can't includ
        The  indicated  file could not be included via the includ
        builtin. 

   includs nested too deeply
        Includ builtins were nested deeper than the system  would
        allow.    The  number  is  determined  by  the  MAXOFILES
        definition in the general symbols definition file. 

   expression: invalid infix expression
        There  is  a  syntax  error  in   the   indicated   infix
        expression as passed to the expr builtin. 

   too many characters pushed back
        A  macro  expansion  is  too  large to be rescanned.  The
        size is set by  the  BUFSIZE  definition  in  the  source
        code. 

   name: too many definitions
        The   table   space   for   macro  definitions  has  been
        exhausted; this  occurred  upon  the  definition  of  the
        indicated macro. 

   token too long
        A  name  or symbol in the input was longer than the token
        buffer.  Size is determined by the MAXTOK  definition  in
        the source code. 

AUTHORS
   Original  by Kernighan and Plauger, with enhancements by David
   Hanson  and  friends  (U.  of  Arizona)  and  Philip  Scherrer
   (Stanford U.)

BUGS/DEFICIENCIES
   This  macro processor is incompatible with the one included in
   the ratfor preprocessor. 

























