212 lines
10 KiB
HTML
212 lines
10 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>m4(9)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>m4(9)</H1>
|
|
<HR>
|
|
<PRE>
|
|
<STRONG>Command:</STRONG> <STRONG>m4</STRONG> <STRONG>-</STRONG> <STRONG>macro</STRONG> <STRONG>processor</STRONG>
|
|
<STRONG>Syntax:</STRONG> <STRONG>m4</STRONG> [<STRONG>-D</STRONG> <EM>name</EM> = <EM>value</EM>] [<STRONG>-U</STRONG> <EM>name</EM>]
|
|
<STRONG>Flags:</STRONG> <STRONG>-D</STRONG> Define a symbol
|
|
<STRONG>-U</STRONG> Undefine a symbol
|
|
<STRONG>Example:</STRONG> m4 <m4test # Run M4
|
|
|
|
<EM>M4</EM> 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.
|
|
|
|
<STRONG>define</STRONG> <STRONG>"(name</STRONG> <STRONG>[,</STRONG> <STRONG>val])"</STRONG> 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.
|
|
|
|
<STRONG>defn</STRONG> <STRONG>"(name</STRONG> <STRONG>[,</STRONG> <STRONG>name</STRONG> <STRONG>...])"</STRONG> returns the quoted definition of its
|
|
argument(s). Useful in renaming macros.
|
|
|
|
<STRONG>undefine</STRONG> <STRONG>"(name</STRONG> <STRONG>[,</STRONG> <STRONG>name</STRONG> <STRONG>...])"</STRONG> 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.
|
|
|
|
<STRONG>pushdef</STRONG> <STRONG>"(name</STRONG> <STRONG>[,</STRONG> <STRONG>val])"</STRONG> like define, but saves any previous
|
|
definition by stacking the current definition.
|
|
|
|
<STRONG>popdef</STRONG> <STRONG>"(name</STRONG> <STRONG>[,</STRONG> <STRONG>name</STRONG> <STRONG>...])"</STRONG> removes current definition of its
|
|
argument(s), exposing the previous one if any.
|
|
|
|
<STRONG>ifdef</STRONG> <STRONG>"(name,</STRONG> <STRONG>if</STRONG>-<STRONG>def</STRONG> <STRONG>[,</STRONG> <STRONG>ifnot</STRONG>-<STRONG>def])"</STRONG> 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).
|
|
|
|
<STRONG>shift</STRONG> <STRONG>"(arg,</STRONG> <STRONG>arg,</STRONG> <STRONG>arg,</STRONG> <STRONG>...)"</STRONG> 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.
|
|
|
|
<STRONG>changequote</STRONG> <STRONG>"(lqchar,</STRONG> <STRONG>rqchar)"</STRONG> change quote symbols to the first
|
|
and second arguments. With no arguments, the quotes are reset back to
|
|
the default characters. (i.e., `').
|
|
|
|
<STRONG>changecom</STRONG> <STRONG>"(lcchar,</STRONG> <STRONG>rcchar)"</STRONG> 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.
|
|
|
|
<STRONG>divert</STRONG> <STRONG>"(divnum)"</STRONG> 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.
|
|
|
|
<STRONG>undivert</STRONG> <STRONG>"([divnum</STRONG> <STRONG>[,</STRONG> <STRONG>divnum</STRONG> <STRONG>...]])"</STRONG> 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.
|
|
|
|
<STRONG>divnum</STRONG> <STRONG>"()"</STRONG> returns the value of the current output stream.
|
|
|
|
<STRONG>dnl</STRONG> <STRONG>"()"</STRONG> reads and discards characters up to and including the next
|
|
newline.
|
|
|
|
|
|
<STRONG>ifelse</STRONG> <STRONG>"(arg,</STRONG> <STRONG>arg,</STRONG> <STRONG>if</STRONG>-<STRONG>same</STRONG> <STRONG>[,</STRONG> <STRONG>ifnot</STRONG>-<STRONG>same</STRONG> <STRONG>|</STRONG> <STRONG>arg,</STRONG> <STRONG>arg</STRONG> <STRONG>...])"</STRONG> 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.
|
|
|
|
<STRONG>incr</STRONG> <STRONG>"(num)"</STRONG> 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.
|
|
|
|
<STRONG>decr</STRONG> <STRONG>"(num)"</STRONG> returns the value of its argument decremented by 1.
|
|
|
|
<STRONG>eval</STRONG> <STRONG>"(expression)"</STRONG> 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.
|
|
|
|
<STRONG>len</STRONG> <STRONG>"(string)"</STRONG> returns the number of characters in its argument.
|
|
|
|
<STRONG>index</STRONG> <STRONG>"(search</STRONG>-<STRONG>string,</STRONG> <STRONG>string)"</STRONG> returns the position in its first
|
|
argument where the second argument begins (zero origin), or 1 if the
|
|
second argument does not occur.
|
|
|
|
<STRONG>substr</STRONG> <STRONG>"(string,</STRONG> <STRONG>index</STRONG> <STRONG>[,</STRONG> <STRONG>length])"</STRONG> 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.
|
|
|
|
<STRONG>translit</STRONG> <STRONG>"(source,</STRONG> <STRONG>from</STRONG> <STRONG>[,</STRONG> <STRONG>to])"</STRONG> 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.
|
|
|
|
<STRONG>include</STRONG> <STRONG>"(filename)"</STRONG> returns the contents of the file that is named
|
|
in the argument.
|
|
|
|
|
|
<STRONG>sinclude</STRONG> <STRONG>"(filename)"</STRONG>is identical to include, except that it says
|
|
nothing if the file is inaccessable.
|
|
|
|
<STRONG>paste</STRONG> <STRONG>"(filename)"</STRONG> returns the contents of the file named in the
|
|
argument without any processing, unlike include.
|
|
|
|
<STRONG>spaste</STRONG> <STRONG>"(filename)"</STRONG> is identical to paste, except that it says
|
|
nothing if the file is inaccessibl[De.
|
|
|
|
<STRONG>syscmd</STRONG> <STRONG>"(command)"</STRONG> executes the UNIX command given in the first
|
|
argument. No value is returned.
|
|
|
|
<STRONG>sysval</STRONG> <STRONG>"()"</STRONG> is the return code from the last call to syscmd.
|
|
.PP <STRONG>maketemp</STRONG> <STRONG>'(string)"</STRONG> fills in a string of XXXXXX in its argument
|
|
with the current process ID.
|
|
|
|
<STRONG>m4exit</STRONG> <STRONG>"([exitcode])"</STRONG> causes immediate exit from M4. Argument 1,
|
|
if given, is the exit code; the default is 0.
|
|
|
|
<STRONG>m4wrap</STRONG> <STRONG>"(m4</STRONG>-<STRONG>macro</STRONG>-<STRONG>or</STRONG>-<STRONG>built</STRONG>-<STRONG>n)"</STRONG> argument 1 will be pushed back at
|
|
final EOF; example: m4wrap(`dumptable()').
|
|
|
|
<STRONG>errprint</STRONG> <STRONG>"(str</STRONG> <STRONG>[,</STRONG> <STRONG>str,</STRONG> <STRONG>str,</STRONG> <STRONG>...])"</STRONG> 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.
|
|
|
|
<STRONG>dumpdef</STRONG> <STRONG>"([name,</STRONG> <STRONG>name,</STRONG> <STRONG>...])"</STRONG> prints current names and definitions,
|
|
for the named items, or for all if no arguments are given.
|
|
|
|
|
|
<STRONG>Author</STRONG>
|
|
|
|
|
|
<EM>M4</EM> was written by Ozan S. Yigif.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|