544 lines
15 KiB
Groff
544 lines
15 KiB
Groff
.\" $NetBSD: m4.1,v 1.31 2020/06/27 19:07:15 uwe Exp $
|
|
.\" @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $
|
|
.\"
|
|
.\" Copyright (c) 1989, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Ozan Yigit at York University.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd June 25, 2020
|
|
.Dt M4 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm m4
|
|
.Nd macro language processor
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl EGgiPQsv
|
|
.Oo
|
|
.Sm off
|
|
.Fl D Ar name Op Cm = Ar value
|
|
.Sm on
|
|
.Oc
|
|
.Op Fl d Ar flags
|
|
.Op Fl F Ar filename
|
|
.Op Fl I Ar dirname
|
|
.Op Fl L Ar number
|
|
.Op Fl o Ar filename
|
|
.Op Fl R Ar filename
|
|
.Op Fl t Ar macro
|
|
.Op Fl U Ns Ar name
|
|
.Op Ar
|
|
.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).
|
|
If no input files are given,
|
|
.Nm
|
|
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
|
|
.Nm
|
|
include paths, or a
|
|
single dash
|
|
.Pq Sq Fl ,
|
|
denoting standard input.
|
|
.Nm
|
|
writes
|
|
the processed text to the standard output, unless told otherwise.
|
|
.Pp
|
|
Macro calls have the form
|
|
.Fo name
|
|
.Fa argument1\|
|
|
.Bo \" should be Oo/Oc but mandoc chokes on it
|
|
.Fa argument2
|
|
.Fa \&...
|
|
.Fa argumentN\|
|
|
.Bc Ns Fc
|
|
.Pp
|
|
There cannot be any space following the macro name and the open
|
|
parenthesis
|
|
.Ql \&( .
|
|
If the macro name is not followed by an open
|
|
parenthesis it is processed with no arguments.
|
|
.Pp
|
|
Macro names consist of a leading alphabetic or underscore
|
|
possibly followed by alphanumeric or underscore characters,
|
|
i.e. valid macro names match the pattern
|
|
.Dq Li [a-zA-Z_][a-zA-Z0-9_]*\| .
|
|
.Pp
|
|
In arguments to macros, leading unquoted space, tab, and newline
|
|
.Pq Sq \en
|
|
characters are ignored.
|
|
To quote strings, use left and right single quotes, e.g.\&
|
|
.Li "\` this is a string with a leading space\(aq" .
|
|
You can change the quote characters with the
|
|
.Ic changequote
|
|
built-in macro.
|
|
.Pp
|
|
Most built-ins don't make any sense without arguments, and hence are not
|
|
recognized as special when not followed by an open parenthesis.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Fl
|
|
.It Fl D , Fl Fl define Ar name Ns Op Ns Cm = Ns Ar value
|
|
Define the symbol
|
|
.Ar name
|
|
to have
|
|
.Ar value
|
|
or to be a null string.
|
|
.It Fl d , Fl Fl debug Ar "flags"
|
|
Set trace flags.
|
|
.Ar flags
|
|
may hold the following:
|
|
.Pp
|
|
.Bl -tag -width ".Li XX" -compact
|
|
.It Cm a
|
|
print macro arguments.
|
|
.It Cm c
|
|
print macro expansion over several lines.
|
|
.It Cm e
|
|
print result of macro expansion.
|
|
.It Cm f
|
|
print filename location.
|
|
.It Cm l
|
|
print line number.
|
|
.It Cm q
|
|
quote arguments and expansion with the current quotes.
|
|
.It Cm t
|
|
start with all macros traced.
|
|
.It Cm x
|
|
number macro expansions.
|
|
.It Cm V
|
|
turn on all trace flags.
|
|
.El
|
|
.Pp
|
|
By default, trace is set to
|
|
.Ql eq .
|
|
.It Fl E , Fl Fl fatal-warnings
|
|
Warnings make
|
|
.Nm
|
|
exit.
|
|
.It Fl F , Fl Fl freeze-state Ar filename
|
|
Save the input state to
|
|
.Ar filename .
|
|
.It Fl G , Fl Fl traditional
|
|
Disable GNU\~m4 extensions.
|
|
.It Fl g , Fl Fl gnu
|
|
Activate GNU\~m4 compatibility mode.
|
|
In this mode
|
|
.Ic translit
|
|
handles simple character
|
|
ranges (e.g.,
|
|
.Sq Li a-z ) ,
|
|
regular expressions mimic emacs behavior,
|
|
multiple
|
|
.Ic m4wrap
|
|
calls are handled as a stack,
|
|
the number of diversions is unlimited,
|
|
empty names for macro definitions are allowed,
|
|
and
|
|
.Ic eval
|
|
understands
|
|
.Sq Ic 0r Ns Ar base Ns Cm \&: Ns Ar value
|
|
numbers.
|
|
.It Fl Fl help
|
|
Print help message and exit.
|
|
.It Fl I , Fl Fl include Ar "dirname"
|
|
Add directory
|
|
.Ar dirname
|
|
to the include path.
|
|
.It Fl i , Fl Fl interactive
|
|
Set unbuffered output, disable tty signals.
|
|
.It Fl L , Fl Fl nesting-limit
|
|
Set the nesting limit in macro expansions.
|
|
This is unimplemented and unlimited.
|
|
.It Fl o , Fl Fl error-output Ar filename
|
|
Send trace output to
|
|
.Ar filename .
|
|
.It Fl P , Fl Fl prefix-builtins
|
|
Prefix all built-in macros with
|
|
.Sq Li m4_ .
|
|
For example, instead of writing
|
|
.Ic define ,
|
|
use
|
|
.Ic m4_define .
|
|
.It Fl Q , Fl Fl quiet , Fl Fl silent
|
|
Don't print warnings.
|
|
.It Fl R , Fl Fl reload-state Ar filename
|
|
Reload a previously saved state from
|
|
.Ar filename .
|
|
.It Fl s , Fl Fl synclines
|
|
Output line synchronization directives, suitable for
|
|
.Xr cpp 1 .
|
|
.It Fl t , Fl Fl trace Ar macro
|
|
Turn tracing on for
|
|
.Ar macro .
|
|
.It Fl U , Fl Fl undefine Ar "name"
|
|
Undefine the symbol
|
|
.Ar name .
|
|
.It Fl v , Fl Fl version
|
|
Print the version and exit.
|
|
.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 changequote
|
|
.It Fn builtin name
|
|
Calls a built-in by its
|
|
.Fa name ,
|
|
overriding possible redefinitions.
|
|
.It Fn changecom startcomment endcomment
|
|
Changes the start comment and end comment sequences.
|
|
Comment sequences may be up to five characters long.
|
|
The default values are the hash sign
|
|
and the newline character.
|
|
.Pp
|
|
.Dl # This is a comment
|
|
.Pp
|
|
With no arguments, comments are turned off.
|
|
With one single argument, the end comment sequence is set
|
|
to the newline character.
|
|
.It Fn changequote beginquote endquote
|
|
Defines the open quote and close quote sequences.
|
|
Quote sequences may be up to five characters long.
|
|
The default values are the backquote character and the quote
|
|
character.
|
|
.Pp
|
|
.Dl \&\`Here is a quoted string\(aq
|
|
.Pp
|
|
With no arguments, the default quotes are restored.
|
|
With one single argument, the close quote sequence is set
|
|
to the newline character.
|
|
.It Fn decr arg
|
|
Decrements the argument
|
|
.Fa arg
|
|
by 1.
|
|
The argument
|
|
.Fa arg
|
|
must be a valid numeric string.
|
|
.It Fn define name value
|
|
Define a new macro named by the first argument
|
|
.Fa name
|
|
to have the
|
|
value of the second argument
|
|
.Fa value .
|
|
Each occurrence of
|
|
.Sq Li \&$ Ns Ar n
|
|
(where
|
|
.Ar n
|
|
is 0 through 9) is replaced by the
|
|
.Ar n Ns 'th
|
|
argument.
|
|
.Sq Li $0
|
|
is the name of the calling macro.
|
|
Undefined arguments are replaced by a null string.
|
|
.Sq Li $#
|
|
is replaced by the number of arguments;
|
|
.Sq Li $*\|
|
|
is replaced by all arguments comma separated;
|
|
.Sq Li $@
|
|
is the same as
|
|
.Sq Li $*\|
|
|
but all arguments are quoted against further expansion.
|
|
.It Fn defn name ...
|
|
Returns the quoted definition for each argument.
|
|
This can be used to rename
|
|
macro definitions (even for built-in macros).
|
|
.It Fn divert num
|
|
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 Ic divnum
|
|
Returns the current output queue number.
|
|
.It Ic dnl
|
|
Discard input characters up to and including the next newline.
|
|
.It Fn dumpdef name ...
|
|
Prints the names and definitions for the named items, or for everything
|
|
if no arguments are passed.
|
|
.It Fn errprint msg
|
|
Prints the first argument on the standard error stream.
|
|
.It Fn esyscmd cmd
|
|
Passes its first argument to a shell and returns the shell's standard output.
|
|
Note that the shell shares its standard input and standard error with
|
|
.Nm .
|
|
.It Fn eval expr radix minimum
|
|
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 optional second argument
|
|
.Fa radix
|
|
specifies the radix for the result and the optional third argument
|
|
.Fa minimum
|
|
specifies the minimum number of digits in the result.
|
|
.It Fn expr expr
|
|
This is an alias for
|
|
.Ic eval .
|
|
.It Fn format formatstring arg1 ...
|
|
Returns
|
|
.Fa formatstring
|
|
with escape sequences substituted with
|
|
.Fa arg1
|
|
and following arguments, in a way similar to
|
|
.Xr printf 3 .
|
|
This built-in is only available in GNU\~m4 compatibility mode, and the only
|
|
parameters implemented are there for autoconf compatibility:
|
|
left-padding flag, an optional field width, a maximum field width,
|
|
.So Li \&*\| Sc Ns -specified
|
|
field widths, and the
|
|
.Ql %s
|
|
and
|
|
.Ql %c
|
|
data type.
|
|
.It Fn ifdef name yes no
|
|
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
|
|
.Sq Li unix
|
|
is predefined.
|
|
.It Fn ifelse a b yes ...
|
|
If the first argument
|
|
.Fa a
|
|
matches the second argument
|
|
.Fa b
|
|
then
|
|
.Fn ifelse
|
|
returns
|
|
the third argument
|
|
.Fa 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.
|
|
.It Fn include name
|
|
Returns the contents of the file specified in the first argument.
|
|
If the file is not found as is, look through the include path:
|
|
first the directories specified with
|
|
.Fl I
|
|
on the command line, then the environment variable
|
|
.Ev M4PATH ,
|
|
as a colon-separated list of directories.
|
|
Include aborts with an error message if the file cannot be included.
|
|
.It Fn incr arg
|
|
Increments the argument by 1.
|
|
The argument must be a valid numeric string.
|
|
.It Fn index string substring
|
|
Returns the index of the second argument in the first argument, e.g.,
|
|
.Pp
|
|
.Dl index(the quick brown fox jumped, fox)
|
|
.Pp
|
|
returns 16.
|
|
If the second
|
|
argument is not found index returns \-1.
|
|
.It Fn indir macro arg1 ...
|
|
Indirectly calls the macro whose name is passed as the first argument,
|
|
with the remaining arguments passed as first, etc arguments.
|
|
.It Fn len arg
|
|
Returns the number of characters in the first argument.
|
|
Extra arguments
|
|
are ignored.
|
|
.It Fn m4exit code
|
|
Immediately exits with the return value specified by the first argument,
|
|
0 if none.
|
|
.It Fn m4wrap todo
|
|
Allows you to define what happens at the final
|
|
.Dv EOF ,
|
|
usually for cleanup purposes.
|
|
E.g.,
|
|
.Pp
|
|
.Dl m4wrap(\`cleanup(tempfile)\(aq)
|
|
.Pp
|
|
causes the macro
|
|
.Ql cleanup
|
|
to be invoked after all other processing is done.
|
|
.Pp
|
|
Multiple calls to
|
|
.Fn m4wrap
|
|
get inserted in sequence at the final
|
|
.Dv EOF .
|
|
.It Fn maketemp template
|
|
Invokes
|
|
.Xr mkstemp 3
|
|
on the first argument, and returns the modified string.
|
|
This can be used to create unique
|
|
temporary file names.
|
|
.It Fn paste file
|
|
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 Fn patsubst string regexp replacement
|
|
Substitutes a regular expression in a string with a replacement string.
|
|
Usual substitution patterns apply: an ampersand
|
|
.Pq Ql \&&
|
|
is replaced by the string matching the regular expression.
|
|
The string
|
|
.Sq Li \&\e Ns Ar \&# ,
|
|
where
|
|
.Ar \&#
|
|
is a digit, is replaced by the corresponding back-reference.
|
|
.It Fn popdef arg ...
|
|
Restores the
|
|
.Ic pushdef Ns ed
|
|
definition for each argument.
|
|
.It Fn pushdef name value
|
|
Takes the same arguments as
|
|
.Ic define ,
|
|
but it saves the existing definition on a
|
|
stack for later retrieval by
|
|
.Fn popdef .
|
|
.It Fn regexp string regexp replacement
|
|
Finds a regular expression in a string.
|
|
If no further arguments are given,
|
|
it returns the first match position or \-1 if no match.
|
|
If a third argument
|
|
is provided, it returns the replacement string, with sub-patterns replaced.
|
|
.It Fn shift arg1 ...
|
|
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 Fn sinclude file
|
|
Similar to
|
|
.Ic include ,
|
|
except it ignores any errors.
|
|
.It Fn spaste file
|
|
Similar to
|
|
.Ic paste ,
|
|
except it ignores any errors.
|
|
.It Fn substr string offset length
|
|
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 Fn syscmd cmd
|
|
Passes the first argument to the shell.
|
|
Nothing is returned.
|
|
.It Ic sysval
|
|
Returns the return value from the last
|
|
.Ic syscmd .
|
|
.It Fn traceon name ...
|
|
Enables tracing of macro expansions for the given arguments, or for all
|
|
macros if no argument is given.
|
|
.It Fn traceoff name ...
|
|
Disables tracing of macro expansions for the given arguments, or for all
|
|
macros if no argument is given.
|
|
.It Fn translit string mapfrom mapto
|
|
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 Fn undefine name ...
|
|
Removes the definition for the macros specified by its arguments.
|
|
.It Fn undivert arg ...
|
|
Flushes the named output queues (or all queues if no arguments).
|
|
.It Ic unix
|
|
A pre-defined macro for testing the OS platform.
|
|
.It Ic __file__
|
|
Returns the current file's name.
|
|
.It Ic __line__
|
|
Returns the current file's line number.
|
|
.El
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility is compliant with the
|
|
.St -p1003.1-2008
|
|
specification.
|
|
.Pp
|
|
The flags
|
|
.Fl dgIot
|
|
and the macros
|
|
.Ic builtin ,
|
|
.Ic esyscmd ,
|
|
.Ic expr ,
|
|
.Ic format ,
|
|
.Ic indir ,
|
|
.Ic paste ,
|
|
.Ic patsubst ,
|
|
.Ic regexp ,
|
|
.Ic spaste ,
|
|
.Ic unix ,
|
|
.Ic __file__ ,
|
|
and
|
|
.Ic __line__
|
|
are extensions to that specification.
|
|
.Pp
|
|
The output format of tracing and of
|
|
.Ic 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
|
|
.Nm autoconf
|
|
to work.
|
|
.Pp
|
|
The built-ins
|
|
.Ic pushdef
|
|
and
|
|
.Ic popdef
|
|
handle macro definitions as a stack.
|
|
However,
|
|
.Ic define
|
|
interacts with the stack in an undefined way.
|
|
In this implementation,
|
|
.Ic define
|
|
replaces the top-most definition only.
|
|
Other implementations may erase all definitions on the stack instead.
|
|
.Pp
|
|
All built-ins do expand without arguments in many other
|
|
.Nm .
|
|
.Pp
|
|
Many other
|
|
.Nm
|
|
have dire size limitations with respect to buffer sizes.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
.An Ozan Yigit Aq Mt oz@sis.yorku.ca
|
|
and
|
|
.An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU .
|
|
.Pp
|
|
GNU\~m4 compatibility extensions by
|
|
.An Marc Espie Aq Mt espie@cvs.openbsd.org .
|