227 lines
10 KiB
Groff
227 lines
10 KiB
Groff
|
|
Name
|
|
m4 - Invokes a macro processor.
|
|
|
|
Syntax
|
|
m4 [ option... ] [ file... ]
|
|
|
|
Description
|
|
M4 is a macro processor intended as a front end for Ratfor,
|
|
C, and other languages. Each of the argument files is
|
|
processed in order; if there are no files, or if a filename
|
|
is -, the standard input is read. The processed text is
|
|
written on the standard output.
|
|
|
|
The options and their effects are:
|
|
|
|
-e Operates interactively. Interrupts are ignored and the
|
|
output is unbuffered.
|
|
|
|
-s Enables line sync output for the C preprocessor (#line
|
|
...)
|
|
|
|
-Bint
|
|
Changes the size of the push-back and argument
|
|
collection buffers from the default of 4,096.
|
|
|
|
-Hint
|
|
Changes the size of the symbol table hash array from
|
|
the default of 199. The size should be prime.
|
|
|
|
-Sint
|
|
Changes the size of the call stack from the default of
|
|
100 slots. Macros take three slots, and nonmacro
|
|
arguments take one.
|
|
|
|
-Tint
|
|
Changes the size of the token buffer from the default
|
|
of 512 bytes.
|
|
|
|
To be effective, these flags must appear before any
|
|
filenames and before any -D or -U flags:
|
|
|
|
-Dname[=val]
|
|
Defines name to val or to null in val's absence.
|
|
|
|
-Uname
|
|
Undefines name.
|
|
|
|
Macro Calls
|
|
Macro calls have the form:
|
|
|
|
name(arg1,arg2, ..., argn)
|
|
|
|
The left parenthesis (() must immediately follow the name of
|
|
the macro. If a defined macro name is not followed by a
|
|
left parenthesis ((), it is deemed to have no arguments.
|
|
Leading unquoted blanks, tabs, and newlines are ignored
|
|
while collecting arguments. Potential macro names consist
|
|
of alphabetic letters, digits, and underscore _, where the
|
|
first character is not a digit.
|
|
|
|
Left and right single quotation marks are used to quote
|
|
strings. The value of a quoted string is the string
|
|
stripped of the quotation marks.
|
|
|
|
When a macro name is recognized, its arguments are collected
|
|
by searching for a matching right parenthesis. 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. 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 The second argument is installed as the value of
|
|
the macro whose name is the first argument.
|
|
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; $# is replaced by the number of
|
|
arguments; $* is replaced by a list of all the
|
|
arguments separated by commas; @ $@ is like $*,
|
|
but each argument is quoted (with the current
|
|
quotation marks).
|
|
|
|
undefine Removes the definition of the macro named in its
|
|
argument.
|
|
|
|
defn Returns the quoted definition of its
|
|
argument(s). It is useful for renaming macros,
|
|
especially built-ins.
|
|
|
|
pushdef Like define, but saves any previous definition.
|
|
|
|
popdef Removes current definition of its argument(s),
|
|
exposing the previous one if any.
|
|
|
|
ifdef 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.
|
|
|
|
shift 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 Changes quotation marks to the first and second
|
|
arguments. The symbols may be up to five
|
|
characters long. Changequote without arguments
|
|
restores the original values.
|
|
|
|
changecom Changes left and right comment markers from the
|
|
default # and newline. With no arguments, the
|
|
comment mechanism is effectively disabled. With
|
|
one argument, the left marker becomes the
|
|
argument and the right marker becomes newline.
|
|
With two arguments, both markers are affected.
|
|
Comment markers may be up to five characters
|
|
long.
|
|
|
|
divert M4 maintains 10 output streams, numbered 0-9.
|
|
The final output is the concatenation of the
|
|
streams in numerical order; 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 discarded.
|
|
|
|
undivert Causes immediate output of text from diversions
|
|
named as arguments, or all diversions if no
|
|
argument. Text may be undiverted into another
|
|
diversion. Undiverting discards the diverted
|
|
text.
|
|
|
|
divnum Returns the value of the current output stream.
|
|
|
|
dnl Reads and discards characters up to and
|
|
including the next newline.
|
|
|
|
ifelse 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 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 Returns the value of its argument decremented by
|
|
1.
|
|
|
|
eval Evaluates its argument as an arithmetic
|
|
expression, using 32-bit arithmetic. Operators
|
|
include +, -, *, /, %, ^ (exponentiation),
|
|
bitwise &, |, ^, and ~; relationals;
|
|
parentheses. Octal and hex numbers may be
|
|
specified as in C. The second argument
|
|
specifies the radix for the result; the default
|
|
is 10. The third argument may be used to
|
|
specify the minimum number of digits in the
|
|
result.
|
|
|
|
len Returns the number of characters in its
|
|
argument.
|
|
|
|
index Returns the position in its first argument where
|
|
the second argument begins (zero origin), or -1
|
|
if the second argument does not occur.
|
|
|
|
substr Returns a substring of its first argument. The
|
|
second argument is a zero origin number
|
|
selecting the first character; 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 Transliterates the characters in its first
|
|
argument from the set given by the second
|
|
argument to the set given by the third. No
|
|
abbreviations are permitted.
|
|
|
|
include Returns the contents of the file named in the
|
|
argument.
|
|
|
|
sinclude Identical to include, except that it says
|
|
nothing if the file is inaccessible.
|
|
|
|
syscmd Executes the XENIX command given in the first
|
|
argument. No value is returned.
|
|
|
|
sysval Is the return code from the last call to syscmd.
|
|
|
|
maketemp Fills in a string of XXXXX in its argument with
|
|
the current process ID.
|
|
|
|
m4exit Causes immediate exit from m4. Argument 1, if
|
|
given, is the exit code; the default is 0.
|
|
|
|
m4wrap Argument 1 will be pushed back at final end-of-
|
|
file; for example, m4wrap(`cleanup()').
|
|
|
|
errprint Prints its argument on the diagnostic output
|
|
file.
|
|
|
|
dumpdef Prints current names and definitions, for the
|
|
named items, or for all if no arguments are
|
|
given.
|
|
|
|
traceon With no arguments, turns on tracing for all
|
|
macros (including built-ins). Otherwise, turns
|
|
on tracing for named macros.
|
|
|
|
traceoff Turns off trace globally and for any macros
|
|
specified. Macros specifically traced by
|
|
traceon can be untraced only by specific calls
|
|
to traceoff.
|