home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
138.lha
/
M4
/
m4.man
< prev
next >
Wrap
Text File
|
1986-11-20
|
14KB
|
271 lines
M4(local) UNIX Programmer's Manual M4(local)
NAME
pd m4 - macro processor
ORIGIN
MetaSystems
SYNOPSIS
m4[ options ]
DESCRIPTION
Pd M4 is a un*x M4 look-alike macro processor intended as a
front end for Ratfor, Pascal, and other languages that do
not have a built-in macro processing capability. Pd M4
reads standard input, the processed text is written on the
standard output.
The options and their effects are as follows:
-Dname[=val]
Defines name to val or to null in val's absence.
-Uname
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 sup-
plied than are in the macro definition, the trailing argu-
ments are taken to be null. Macro evaluation proceeds nor-
mally 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 ori-
ginal 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 res-
canned.
Printed 5/16/88 30 Aug 1987 1
M4(local) UNIX Programmer's Manual M4(local)
Pd 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 usage: 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 replace-
ment 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 usage: defn(name [, name ...])
returns the quoted definition of its
argument(s). Useful in renaming macros.
undefine usage: 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 usage: pushdef(name [, val])
like define, but saves any previous definition
by stacking the current definition.
popdef usage: popdef(name [, name ...])
removes current definition of its argument(s),
exposing the previous one if any.
ifdef usage: 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 usage: shift(arg, arg, arg, ...)
returns all but its first argument. The other
arguments are quoted and pushed back with com-
mas in between. The quoting nullifies the
effect of the extra scan that will subse-
quently be performed.
changequote usage: 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.,
).
Printed 5/16/88 30 Aug 1987 2
M4(local) UNIX Programmer's Manual M4(local)
changecom usage: 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 usage: divert(divnum)
m4 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
disappears into bitbucket.
undivert usage: undivert([divnum [, divnum ...]])
causes immediate output of text from diver-
sions 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 m4wrap
is defined.
divnum usage: divnum()
returns the value of the current output
stream.
dnl usage: dnl()
reads and discards characters up to and
including the next newline.
ifelse usage: 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 usage: 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 usage: decr(num)
returns the value of its argument decremented
Printed 5/16/88 30 Aug 1987 3
M4(local) UNIX Programmer's Manual M4(local)
by 1.
eval usage: eval(expression)
evaluates its argument as a constant expres-
sion, using integer arithmetic. The evalua-
tion mechanism is very similar to that of cpp
(#if expression). The expression can involve
only integer constants and character con-
stants, possibly connected by the binary
operators
* / % + - >> << < >
<= >= == != & ^ | && ||
or the unary operators - ~ ! or by the ter-
nary operator ? : . Parentheses may be used
for grouping. Octal numbers may be specified
as in C.
len usage: len(string)
returns the number of characters in its argu-
ment.
index usage: index(search-string, string)
returns the position in its first argument
where the second argument begins (zero ori-
gin), or -1 if the second argument does not
occur.
substr usage: 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 usage: 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 usage: include(filename)
returns the contents of the file named in the
Printed 5/16/88 30 Aug 1987 4
M4(local) UNIX Programmer's Manual M4(local)
argument.
sinclude usage: sinclude(filename)
is identical to include, except that it says
nothing if the file is inaccessible.
paste usage: paste(filename)
returns the contents of the file named in the
argument without any processing, unlike
include.
spaste usage: spaste(filename)
is identical to paste, except that it says
nothing if the file is inaccessible.
syscmd usage: syscmd(command)
executes the UNIX command given in the first
argument. No value is returned.
sysval usage: sysval()
is the return code from the last call to
syscmd.
maketemp usage: maketemp(string)
fills in a string of XXXXXX in its argument
with the current process ID.
m4exit usage: m4exit([exitcode])
causes immediate exit from m4. Argument 1, if
given, is the exit code; the default is 0.
m4wrap usage: m4wrap(m4-macro-or-built-in)
argument 1 will be pushed back at final EOF;
example: m4wrap(`dumptable()').
errprint usage: 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.
dumpdef usage: dumpdef([name, name, ...])
prints current names and definitions, for the
named items, or for all if no arguments are
given.
AUTHOR
Ozan S. Yigit (oz)
BUGS
Pd M4 is distributed at the source level, and does not
require an expensive license agreement.
Printed 5/16/88 30 Aug 1987 5
M4(local) UNIX Programmer's Manual M4(local)
A sufficiently complex M4 macro set is about as readable as
APL.
All complex uses of M4 require the ability to program in
deep recursion. Previous lisp experience is recommended.
Pd M4 is slower than V7 M4.
EXAMPLES
The following macro program illustrates the type of things
that can be done with M4.
changequote(<,>) define(HASHVAL,99) dnl
define(hash,<expr(str(substr($1,1),0)%HASHVAL)>) dnl
define(str,
<ifelse($1,",$2,
<str(substr(<$1>,1),<expr($2+'substr($1,0,1)')>)>)
>) dnl
define(KEYWORD,<$1,hash($1),>) dnl
define(TSTART,
<struct prehash {
char *keyword;
int hashval;
} keytab[] = {>) dnl
define(TEND,< "",0
};>) dnl
Thus a keyword table containing the keyword string and its
pre-calculated hash value may be generated thus:
TSTART
KEYWORD("foo")
KEYWORD("bar")
KEYWORD("baz")
TEND
which will expand into:
struct prehash {
char *keyword;
int hashval;
} keytab[] = {
"foo",27,
"bar",12,
"baz",20,
"",0
};
Presumably, such a table would speed up the installation of
the keywords into a dynamic hash table. (Note that the above
macro cannot be used with M4, since eval does not handle
character constants.)
Printed 5/16/88 30 Aug 1987 6
M4(local) UNIX Programmer's Manual M4(local)
SEE ALSO
cc(1), m4(1), cpp(1). The M4 Macro Processor by B. W. Ker-
nighan and D. M. Ritchie.
Printed 5/16/88 30 Aug 1987 7