10.0;macro, revision 1.0, 88/01/21
macro -- Expand macro definitions.
usage: macro [-0] [pathname ...]
DESCRIPTION
macro is a general purpose macro processor. macro reads the files and
writes to standard output a new file with the macro definitions deleted
and the macro references expanded.
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 string name can consist of letters (a-z and A-Z),
digits (0-9), underscores (_), and dollar signs ($). The placement of
blanks in definitions is significant; they should only appear in the
replacement text where desired. Uppercase and lowercase 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.
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. No space is allowed
between the command (in this case, define), and the left parenthesis.
ARGUMENTS
pathname (optional)
Specify file containing macro definitions to be processed.
Multiple pathnames are permitted.
Default if omitted: read standard input
OPTIONS
-0 (Zero, not letter O)
Remove one level of brackets in macro calls prior to
processing. Normally, brackets appearing outside any macro
calls (level zero brackets) are not removed.
Built In Macros
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. Otherwise, it returns d.
incr(a) Interprets a as an integer and returns a+1.
substr(a,m,n)
Returns a substring of the string a starting at character
number m and extending for n characters.
len(a) Returns the length of a.
includ(a) 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
+ - Addition and subtraction
* / % Multiplication, division, modulus (remainder)
** Exponentiation
+ - Unary plus and negation
Logical operators return 0 (false) or 1 (true)
EXAMPLES
A simple example of a macro is
define(EOF,-1)
Thereafter, all occurrences of EOF in the file are replaced by '-1'.
You may specify arguments in macro definitions with the characters $n,
where n is a number between 0 and 9. The arguments to be inserted when
the macro is encountered are given inside parentheses following the macro
name. $0 refers to the name of the macro itself. For example,
define(copen,$3 = open($1,$2) )
defines a macro that, when called by
copen(name, read, fd)
expands into
fd = open(name,read)
If a macro definition refers to an argument that was not supplied, the $n
is ignored. The $ is taken literally if a character other than a digit
follows it.
Macros can be nested, and can be called recursively. Any macros
encountered during argument collection are expanded immediately, unless
they are surrounded by square brackets ([ ]). That is, input surrounded
by brackets is left 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 you could use:
d(a,bc)
to define a as bc. Brackets must also be used to redefine a macro. For
example
define(x,y)
.
.
.
define(x,z)
defines y in the second line, instead of redefining x. To define x the
second time, the operation must be expressed as
define(x,y)
.
.
.
define([x],z)
Normally, brackets appearing outside any macro calls (level zero
brackets) are not removed. When the -0 (zero, not letter O) option is
specified, one level of brackets is removed both inside and outside the
macros. One level of brackets is also removed when the macro reference
is expanded. Thus, to rewrite the d macro above so that it is evaluated
to the literal string 'define($1,$2)', the definition is
define(d,[[define($1,$2)]])
In order to redefine the macro define (for example, so that the Pascal
keyword 'define' can be used) the following definition can be used:
define([define], [[define])
One level of brackets is stripped from both arguments when the definition
is processed. The second argument is stripped when the macro is invoked.
DIAGNOSTICS
arith evaluation stack overflow
Arithmetic expressions can be nested only to 30 deep.
arg stack overflow
The total number of arguments exceeds the limit of 100.
call stack overflow
Definitions can be nested only to 20 deep.
EOF in string
An end-of-file was encountered before a bracketed string was
terminated.
evaluation stack overflow
Too many characters are used for the name, definition, and
arguments of one macro. 2500 characters are allowed.
unexpected EOF
An end-of-file was reached before a macro definition was
terminated.
filename: can't open
The named file can not be opened.
filename: can't include
The indicated file cannot be included with the built-in macro
includ.
includes nested too deeply
Files included with the built-in macro includ can be nested
only up to 128 deep.
expression: invalid infix expression
There is a syntax error in the indicated infix expression as
passed to the built-in macro expr.
too many characters pushed back
A macro expansion is too large to be rescanned. A macro
definition may contain up to 2500 characters.
name: too many definitions
The table space for macro definitions has been exhausted; this
occurred upon the definition of the named macro.
token too long
A name or symbol in the input was longer than the token buffer.
Each token may be up to 200 characters long.