M4(1) | General Commands Manual | M4(1) |
m4
—
m4 |
[-EGgiPQsv ]
[-D name[= value]]
[-d flags]
[-F filename]
[-I dirname]
[-L number]
[-o filename]
[-R filename]
[-t macro]
[-U name]
[file ...] |
m4
utility is a macro processor that can be used as
a front end to any language (e.g., C, ratfor, fortran, lex, and yacc). If no
input files are given, m4
reads from the standard
input, otherwise files specified on the command line are processed in the
given order. Input files can be regular files, files in the
m4
include paths, or a single dash
(‘-
’), denoting standard input.
m4
writes the processed text to the standard output,
unless told otherwise.
Macro calls have the form
name
(argument1
[argument2 ...
argumentN]);
There cannot be any space following the macro name and the open
parenthesis ‘(
’. If the macro name is
not followed by an open parenthesis it is processed with no arguments.
Macro names consist of a leading alphabetic or underscore possibly
followed by alphanumeric or underscore characters, i.e. valid macro names
match the pattern
“[a-zA-Z_][a-zA-Z0-9_]*
”.
In arguments to macros, leading unquoted space, tab, and newline
(‘\n’) 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.
Most built-ins don't make any sense without arguments, and hence are not recognized as special when not followed by an open parenthesis.
The options are as follows:
-D
,
-
-define
name[=
value]-d
,
-
-debug
flagsa
c
e
f
l
q
t
x
V
By default, trace is set to
‘eq
’.
-E
,
-
-fatal-warnings
m4
exit.-F
,
-
-freeze-state
filename-G
,
-
-traditional
-g
,
-
-gnu
translit
handles simple character ranges (e.g.,
‘a-z
’), regular expressions mimic
emacs behavior, multiple m4wrap
calls are handled
as a stack, the number of diversions is unlimited, empty names for macro
definitions are allowed, and eval
understands
‘0r
base:
value’
numbers.-
-help
-I
,
-
-include
dirname-i
,
-
-interactive
-L
,
-
-nesting-limit
-o
,
-
-error-output
filename-P
,
-
-prefix-builtins
m4_
’. For example, instead of
writing define
, use
m4_define
.-Q
,
-
-quiet
,
-
-silent
-R
,
-
-reload-state
filename-s
,
-
-synclines
-t
,
-
-trace
macro-U
,
-
-undefine
name-v
,
-
-version
m4
provides the following built-in macros. They may be
redefined, losing their original meaning. Return values are null unless
otherwise stated.
builtin
(name)changecom
(startcomment,
endcomment)# This is a comment
With no arguments, comments are turned off. With one single argument, the end comment sequence is set to the newline character.
changequote
(beginquote,
endquote)`Here is a quoted
string'
With no arguments, the default quotes are restored. With one single argument, the close quote sequence is set to the newline character.
decr
(arg)define
(name,
value)$
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.defn
(name,
...)divert
(num)m4
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).divnum
dnl
dumpdef
(name,
...)errprint
(msg)esyscmd
(cmd)m4
.eval
(expr,
radix, minimum)expr
(expr)eval
.format
(formatstring,
arg1, ...)*
’-specified field widths, and the
‘%s
’ and
‘%c
’ data type.ifdef
(name,
yes, no)unix
’ is
predefined.ifelse
(a,
b, yes,
...)ifelse
() returns the
third argument yes. 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.include
(name)-I
on the command line,
then the environment variable M4PATH
, as a
colon-separated list of directories. Include aborts with an error message
if the file cannot be included.incr
(arg)index
(string,
substring)index(the quick brown fox jumped,
fox)
returns 16. If the second argument is not found index returns -1.
indir
(macro,
arg1, ...)len
(arg)m4exit
(code)m4wrap
(todo)EOF
, usually for cleanup purposes. E.g.,
m4wrap(`cleanup(tempfile)')
causes the macro
‘cleanup
’ to be invoked after all
other processing is done.
Multiple calls to m4wrap
() get
inserted in sequence at the final EOF
.
maketemp
(template)paste
(file)patsubst
(string,
regexp, replacement)&
’) is replaced by the string
matching the regular expression. The string
‘\
#’, where
# is a digit, is replaced by the corresponding
back-reference.popdef
(arg,
...)pushdef
ed definition for each
argument.pushdef
(name,
value)define
, but it saves
the existing definition on a stack for later retrieval by
popdef
().regexp
(string,
regexp, replacement)shift
(arg1,
...)sinclude
(file)include
, except it ignores any
errors.spaste
(file)paste
, except it ignores any
errors.substr
(string,
offset, length)syscmd
(cmd)sysval
syscmd
.traceon
(name,
...)traceoff
(name,
...)translit
(string,
mapfrom, mapto)undefine
(name,
...)undivert
(arg,
...)unix
__file__
__line__
m4
utility is compliant with the
IEEE Std 1003.1-2008 (“POSIX.1”)
specification.
The flags -dgIot
and the macros
builtin
, esyscmd
,
expr
, format
,
indir
, paste
,
patsubst
, regexp
,
spaste
, unix
,
__file__
, and __line__
are
extensions to that specification.
The output format of tracing and of
dumpdef
are not specified in any standard, are
likely to change and should not be relied upon. The current format of
tracing is closely modelled on GNU m4, to allow
autoconf
to work.
The built-ins pushdef
and
popdef
handle macro definitions as a stack. However,
define
interacts with the stack in an undefined way.
In this implementation, define
replaces the top-most
definition only. Other implementations may erase all definitions on the
stack instead.
All built-ins do expand without arguments in many other
m4
.
Many other m4
have dire size limitations
with respect to buffer sizes.
GNU m4 compatibility extensions by Marc Espie <espie@cvs.openbsd.org>.
June 25, 2020 | NetBSD 10.0 |