184 lines
6.7 KiB
Groff
184 lines
6.7 KiB
Groff
.\"
|
|
.\" @(#) $FreeBSD$
|
|
.\"
|
|
.Dd January 26, 1993
|
|
.Dt M4 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm m4
|
|
.Nd macro language processor
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Oo
|
|
.Fl D Ns Ar name Ns Op Ar =value
|
|
.Oc
|
|
.Op Fl U Ns Ar name
|
|
.Op Ar filename
|
|
\|.\|.\|.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is a macro processor that can be used as a front end to any
|
|
language (e.g., C, ratfor, fortran, lex, and yacc).
|
|
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 sent to the standard output.
|
|
.Pp
|
|
Macro calls have the form name(argument1[, argument2, ...,] argumentN).
|
|
.Pp
|
|
There cannot be any space following the macro name and the open
|
|
parentheses '('. If the macro name is not followed by an open
|
|
parentheses it is processed with no arguments.
|
|
.Pp
|
|
Macro names consist of a leading alphabetic or underscore
|
|
possibly followed by alphanumeric or underscore characters, therefore
|
|
valid macro names match this pattern [a-zA-Z_][a-zA-Z0-9_]*.
|
|
.Pp
|
|
In arguments to macros, leading unquoted space, tab and newline
|
|
characters are ignored. To quote strings use left and right single
|
|
quotes (e.g., ` this is a string with a leading space'). You can change
|
|
the quote characters with the changequote built-in macro.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width "-Dname[=value]xxx"
|
|
.It Fl D Ns Ar name Ns Oo
|
|
.Ar =value
|
|
.Oc
|
|
Define the symbol
|
|
.Ar name
|
|
to have some value (or NULL).
|
|
.It Fl "U" Ns Ar "name"
|
|
Undefine the symbol
|
|
.Ar name .
|
|
.El
|
|
.Sh SYNTAX
|
|
.Nm
|
|
provides the following built-in macros. They may be
|
|
redefined, losing their original meaning.
|
|
Return values are NULL unless otherwise stated.
|
|
.Bl -tag -width changequotexxx
|
|
.It changecom
|
|
Change the start and end comment sequences. The default is
|
|
the pound sign `#' and the newline character. With no arguments
|
|
comments are turned off. The maximum length for a comment marker is
|
|
five characters.
|
|
.It changequote
|
|
Defines the quote symbols to be the first and second arguments.
|
|
Note, only the first character of each argument is used. If no arguments are
|
|
given it restores the default open and close single quotes.
|
|
.It decr
|
|
Decrements the argument by 1. The argument must be a valid numeric string.
|
|
.It define
|
|
Define a new macro named by the first argument to have the
|
|
value of the second argument. Each occurrence of $n (where n
|
|
is 0 through 9) is replaced by the n'th argument. $0 is the name
|
|
of the calling macro. Undefined arguments are replaced by a
|
|
NULL string. $# is replaced by the number of arguments; $*
|
|
is replaced by all arguments comma separated; $@ is the same
|
|
as $* but all arguments are quoted against further expansion.
|
|
.It defn
|
|
Returns the quoted definition for each argument. This can be used to rename
|
|
macro definitions (even for built-in macros).
|
|
.It divert
|
|
There are 10 output queues (numbered 0-9).
|
|
At the end of processing
|
|
.Nm
|
|
concatenates all the queues in numerical order to produce the
|
|
final output. Initially the output queue is 0. The divert
|
|
macro allows you to select a new output queue (an invalid argument
|
|
passed to divert causes output to be discarded).
|
|
.It divnum
|
|
Returns the current output queue number.
|
|
.It dnl
|
|
Discard input characters up to and including the next newline.
|
|
.It dumpdef
|
|
Prints the names and definitions for the named items, or for everything
|
|
if no arguments are passed.
|
|
.It errprint
|
|
Prints the first argument on the standard error output stream.
|
|
.It eval
|
|
Computes the first argument as an arithmetic expression using 32-bit
|
|
arithmetic. Operators are the standard C ternary, arithmetic, logical,
|
|
shift, relational, bitwise, and parentheses operators. You can specify
|
|
octal, decimal, and hexadecimal numbers as in C. The second argument (if
|
|
any) specifies the radix for the result and the third argument (if
|
|
any) specifies the minimum number of digits in the result.
|
|
.It expr
|
|
This is an alias for eval.
|
|
.It ifdef
|
|
If the macro named by the first argument is defined then return the second
|
|
argument, otherwise the third. If there is no third argument,
|
|
the value is NULL. The word `unix' is predefined.
|
|
.It ifelse
|
|
If the first argument matches the second argument then ifelse returns
|
|
the third argument. If the match fails the three arguments are
|
|
discarded and the next three arguments are used until there is
|
|
zero or one arguments left, either this last argument or NULL is
|
|
returned if no other matches were found.
|
|
.It include
|
|
Returns the contents of the file specified in the first argument.
|
|
Include aborts with an error message if the file cannot be included.
|
|
.It incr
|
|
Increments the argument by 1. The argument must be a valid numeric string.
|
|
.It index
|
|
Returns the index of the second argument in the first argument (e.g.,
|
|
index(the quick brown fox jumped, fox) returns 16). If the second
|
|
argument is not found index returns -1.
|
|
.It len
|
|
Returns the number of characters in the first argument. Extra arguments
|
|
are ignored.
|
|
.It m4exit
|
|
Immediately exits with the return value specified by the first argument,
|
|
0 if none.
|
|
.It m4wrap
|
|
Allows you to define what happens at the final EOF, usually for cleanup
|
|
purposes (e.g., m4wrap("cleanup(tempfile)") causes the macro cleanup to be
|
|
invoked after all other processing is done.)
|
|
.It maketemp
|
|
Translates the string XXXXX in the first argument with the current process
|
|
ID leaving other characters alone. This can be used to create unique
|
|
temporary file names.
|
|
.It paste
|
|
Includes the contents of the file specified by the first argument without
|
|
any macro processing. Aborts with an error message if the file cannot be
|
|
included.
|
|
.It popdef
|
|
Restores the pushdef'ed definition for each argument.
|
|
.It pushdef
|
|
Takes the same arguments as define, but it saves the definition on a
|
|
stack for later retrieval by popdef.
|
|
.It shift
|
|
Returns all but the first argument, the remaining arguments are
|
|
quoted and pushed back with commas in between. The quoting
|
|
nullifies the effect of the extra scan that will subsequently be
|
|
performed.
|
|
.It sinclude
|
|
Similar to include, except it ignores any errors.
|
|
.It spaste
|
|
Similar to paste, except it ignores any errors.
|
|
.It substr
|
|
Returns a substring of the first argument starting at the offset specified
|
|
by the second argument and the length specified by the third argument.
|
|
If no third argument is present it returns the rest of the string.
|
|
.It syscmd
|
|
Passes the first argument to the shell. Nothing is returned.
|
|
.It sysval
|
|
Returns the return value from the last syscmd.
|
|
.It translit
|
|
Transliterate the characters in the first argument from the set
|
|
given by the second argument to the set given by the third. You cannot
|
|
use
|
|
.Xr tr 1
|
|
style abbreviations.
|
|
.It undefine
|
|
Removes the definition for the macro specified by the first argument.
|
|
.It undivert
|
|
Flushes the named output queues (or all queues if no arguments).
|
|
.It unix
|
|
A pre-defined macro for testing the OS platform.
|
|
.El
|
|
.Sh AUTHORS
|
|
.An Ozan Yigit Aq oz@sis.yorku.ca
|
|
and
|
|
.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU
|