[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Macros can be defined, redefined and deleted in several different ways. Also, it is possible to redefine a macro without losing a previous value, and bring back the original value at a later time.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The normal way to define or redefine macros is to use the builtin
define
:
Defines name to expand to expansion. If expansion is not given, it is taken to be empty.
The expansion of define
is void.
The macro define
is recognized only with parameters.
The following example defines the macro foo to expand to the text ‘Hello World.’.
define(`foo', `Hello world.') ⇒ foo ⇒Hello world. |
The empty line in the output is there because the newline is not
a part of the macro definition, and it is consequently copied to
the output. This can be avoided by use of the macro dnl
.
See section Deleting whitespace in input, for details.
The first argument to define
should be quoted; otherwise, if the
macro is already defined, you will be defining a different macro. This
example shows the problems with underquoting, since we did not want to
redefine one
:
define(foo, one) ⇒ define(foo, two) ⇒ one ⇒two |
GNU m4
normally replaces only the topmost
definition of a macro if it has several definitions from pushdef
(see section Temporarily redefining macros). Some other implementations of m4
replace all
definitions of a macro with define
. See section Facilities in System V m4
not in GNU m4
,
for more details.
As a GNU extension, the first argument to define
does
not have to be a simple word.
It can be any text string, even the empty string. A macro with a
non-standard name cannot be invoked in the normal way, as the name is
not recognized. It can only be referenced by the builtins indir
(see section Indirect call of macros) and defn
(see section Renaming macros).
Arrays and associative arrays can be simulated by using non-standard macro names.
Provide access to entries within an array. array
reads the entry
at location index, and array_set
assigns value to
location index.
define(`array', `defn(format(``array[%d]'', `$1'))') ⇒ define(`array_set', `define(format(``array[%d]'', `$1'), `$2')') ⇒ array_set(`4', `array element no. 4') ⇒ array_set(`17', `array element no. 17') ⇒ array(`4') ⇒array element no. 4 array(eval(`10 + 7')) ⇒array element no. 17 |
Change the ‘%d’ to ‘%s’ and it is an associative array.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Macros can have arguments. The nth argument is denoted by
$n
in the expansion text, and is replaced by the nth actual
argument, when the macro is expanded. Replacement of arguments happens
before rescanning, regardless of how many nesting levels of quoting
appear in the expansion. Here is an example of a macro with
two arguments.
Expands to arg2 followed by arg1, effectively exchanging their order.
define(`exch', `$2, $1') ⇒ exch(`arg1', `arg2') ⇒arg2, arg1 |
This can be used, for example, if you like the arguments to
define
to be reversed.
define(`exch', `$2, $1') ⇒ define(exch(``expansion text'', ``macro'')) ⇒ macro ⇒expansion text |
See section On Quoting Arguments to macros, for an explanation of the double quotes.
(You should try and improve this example so that clients of exch
do not have to double quote; or see section Answers).
As a special case, the zeroth argument, $0
, is always the name
of the macro being expanded.
define(`test', ``Macro name: $0'') ⇒ test ⇒Macro name: test |
If you want quoted text to appear as part of the expansion text, remember that quotes can be nested in quoted strings. Thus, in
define(`foo', `This is macro `foo'.') ⇒ foo ⇒This is macro foo. |
The ‘foo’ in the expansion text is not expanded, since it is a quoted string, and not a name.
GNU m4
allows the number following the ‘$’ to
consist of one or more digits, allowing macros to have any number of
arguments. The extension of accepting multiple digits is incompatible
with POSIX, and is different than traditional implementations
of m4
, which only recognize one digit. Therefore, future
versions of GNU M4 will phase out this feature. To portably
access beyond the ninth argument, you can use the argn
macro
documented later (see section Recursion in m4
).
POSIX also states that ‘$’ followed immediately by
‘{’ in a macro definition is implementation-defined. This version
of M4 passes the literal characters ‘${’ through unchanged, but M4
2.0 will implement an optional feature similar to sh
, where
‘${11}’ expands to the eleventh argument, to replace the current
recognition of ‘$11’. Meanwhile, if you want to guarantee that you
will get a literal ‘${’ in output when expanding a macro, even
when you upgrade to M4 2.0, you can use nested quoting to your
advantage:
define(`foo', `single quoted $`'{1} output') ⇒ define(`bar', ``double quoted $'`{2} output'') ⇒ foo(`a', `b') ⇒single quoted ${1} output bar(`a', `b') ⇒double quoted ${2} output |
To help you detect places in your M4 input files that might change in behavior due to the changed behavior of M4 2.0, you can use the ‘--warn-macro-sequence’ command-line option (see section Invoking m4) with the default regular expression. This will add a warning any time a macro definition includes ‘$’ followed by multiple digits, or by ‘{’. The warning is not enabled by default, because it triggers a number of warnings in Autoconf 2.61 (and Autoconf uses ‘-E’ to treat warnings as errors), and because it will still be possible to restore older behavior in M4 2.0.
$ m4 --warn-macro-sequence define(`foo', `$001 ${1} $1') error-->m4:stdin:1: Warning: definition of `foo' contains sequence `$001' error-->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}' ⇒ foo(`bar') ⇒bar ${1} bar |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There is a special notation for the number of actual arguments supplied, and for all the actual arguments.
The number of actual arguments in a macro call is denoted by $#
in the expansion text.
Expands to a count of the number of arguments supplied.
define(`nargs', `$#') ⇒ nargs ⇒0 nargs() ⇒1 nargs(`arg1', `arg2', `arg3') ⇒3 nargs(`commas can be quoted, like this') ⇒1 nargs(arg1#inside comments, commas do not separate arguments still arg1) ⇒1 nargs((unquoted parentheses, like this, group arguments)) ⇒1 |
Remember that ‘#’ defaults to the comment character; if you forget quotes to inhibit the comment behavior, your macro definition may not end where you expected.
dnl Attempt to define a macro to just `$#' define(underquoted, $#) oops) ⇒ underquoted ⇒0) ⇒oops |
The notation $*
can be used in the expansion text to denote all
the actual arguments, unquoted, with commas in between. For example
define(`echo', `$*') ⇒ echo(arg1, arg2, arg3 , arg4) ⇒arg1,arg2,arg3 ,arg4 |
Often each argument should be quoted, and the notation $@
handles
that. It is just like $*
, except that it quotes each argument.
A simple example of that is:
define(`echo', `$@') ⇒ echo(arg1, arg2, arg3 , arg4) ⇒arg1,arg2,arg3 ,arg4 |
Where did the quotes go? Of course, they were eaten, when the expanded
text were reread by m4
. To show the difference, try
define(`echo1', `$*') ⇒ define(`echo2', `$@') ⇒ define(`foo', `This is macro `foo'.') ⇒ echo1(foo) ⇒This is macro This is macro foo.. echo1(`foo') ⇒This is macro foo. echo2(foo) ⇒This is macro foo. echo2(`foo') ⇒foo |
See section Tracing macro calls, if you do not understand this. As another example of the difference, remember that comments encountered in arguments are passed untouched to the macro, and that quoting disables comments.
define(`echo1', `$*') ⇒ define(`echo2', `$@') ⇒ define(`foo', `bar') ⇒ echo1(#foo'foo foo) ⇒#foo'foo ⇒bar echo2(#foo'foo foo) ⇒#foobar ⇒bar' |
A ‘$’ sign in the expansion text, that is not followed by anything
m4
understands, is simply copied to the macro expansion, as any
other text is.
define(`foo', `$$$ hello $$$') ⇒ foo ⇒$$$ hello $$$ |
If you want a macro to expand to something like ‘$12’, the
judicious use of nested quoting can put a safe character between the
$
and the next character, relying on the rescanning to remove the
nested quote. This will prevent m4
from interpreting the
$
sign as a reference to an argument.
define(`foo', `no nested quote: $1') ⇒ foo(`arg') ⇒no nested quote: arg define(`foo', `nested quote around $: `$'1') ⇒ foo(`arg') ⇒nested quote around $: $1 define(`foo', `nested empty quote after $: $`'1') ⇒ foo(`arg') ⇒nested empty quote after $: $1 define(`foo', `nested quote around next character: $`1'') ⇒ foo(`arg') ⇒nested quote around next character: $1 define(`foo', `nested quote around both: `$1'') ⇒ foo(`arg') ⇒nested quote around both: arg |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A macro definition can be removed with undefine
:
For each argument, remove the macro name. The macro names must necessarily be quoted, since they will be expanded otherwise.
The expansion of undefine
is void.
The macro undefine
is recognized only with parameters.
foo bar blah ⇒foo bar blah define(`foo', `some')define(`bar', `other')define(`blah', `text') ⇒ foo bar blah ⇒some other text undefine(`foo') ⇒ foo bar blah ⇒foo other text undefine(`bar', `blah') ⇒ foo bar blah ⇒foo bar blah |
Undefining a macro inside that macro’s expansion is safe; the macro still expands to the definition that was in effect at the ‘(’.
define(`f', ``$0':$1') ⇒ f(f(f(undefine(`f')`hello world'))) ⇒f:f:f:hello world f(`bye') ⇒f(bye) |
It is not an error for name to have no macro definition. In that
case, undefine
does nothing.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is possible to rename an already defined macro. To do this, you need
the builtin defn
:
Expands to the quoted definition of each name. If an argument is not a defined macro, the expansion for that argument is empty.
If name is a user-defined macro, the quoted definition is simply
the quoted expansion text. If, instead, there is only one name
and it is a builtin, the
expansion is a special token, which points to the builtin’s internal
definition. This token is only meaningful as the second argument to
define
(and pushdef
), and is silently converted to an
empty string in most other contexts. Combining a builtin with anything
else is not supported; a warning is issued and the builtin is omitted
from the final expansion.
The macro defn
is recognized only with parameters.
Its normal use is best understood through an example, which shows how to
rename undefine
to zap
:
define(`zap', defn(`undefine')) ⇒ zap(`undefine') ⇒ undefine(`zap') ⇒undefine(zap) |
In this way, defn
can be used to copy macro definitions, and also
definitions of builtin macros. Even if the original macro is removed,
the other name can still be used to access the definition.
The fact that macro definitions can be transferred also explains why you
should use $0
, rather than retyping a macro’s name in its
definition:
define(`foo', `This is `$0'') ⇒ define(`bar', defn(`foo')) ⇒ bar ⇒This is bar |
Macros used as string variables should be referred through defn
,
to avoid unwanted expansion of the text:
define(`string', `The macro dnl is very useful ') ⇒ string ⇒The macro defn(`string') ⇒The macro dnl is very useful ⇒ |
However, it is important to remember that m4
rescanning is purely
textual. If an unbalanced end-quote string occurs in a macro
definition, the rescan will see that embedded quote as the termination
of the quoted string, and the remainder of the macro’s definition will
be rescanned unquoted. Thus it is a good idea to avoid unbalanced
end-quotes in macro definitions or arguments to macros.
define(`foo', a'a) ⇒ define(`a', `A') ⇒ define(`echo', `$@') ⇒ foo ⇒A'A defn(`foo') ⇒aA' echo(foo) ⇒AA' |
On the other hand, it is possible to exploit the fact that defn
can concatenate multiple macros prior to the rescanning phase, in order
to join the definitions of macros that, in isolation, have unbalanced
quotes. This is particularly useful when one has used several macros to
accumulate text that M4 should rescan as a whole. In the example below,
note how the use of defn
on l
in isolation opens a string,
which is not closed until the next line; but used on l
and
r
together results in nested quoting.
define(`l', `<[>')define(`r', `<]>') ⇒ changequote(`[', `]') ⇒ defn([l])defn([r]) ]) ⇒<[>]defn([r]) ⇒) defn([l], [r]) ⇒<[>][<]> |
Using defn
to generate special tokens for builtin macros outside
of expected contexts can sometimes trigger warnings. But most of the
time, such tokens are silently converted to the empty string.
$ m4 -d defn(`defn') ⇒ define(defn(`divnum'), `cannot redefine a builtin token') error-->m4:stdin:2: Warning: define: invalid macro name ignored ⇒ divnum ⇒0 len(defn(`divnum')) ⇒0 |
Also note that defn
with multiple arguments can only join text
macros, not builtins, although a future version of GNU M4 may
lift this restriction.
$ m4 -d define(`a', `A')define(`AA', `b') ⇒ traceon(`defn', `define') ⇒ defn(`a', `divnum', `a') error-->m4:stdin:3: Warning: cannot concatenate builtin `divnum' error-->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A'' ⇒AA define(`mydivnum', defn(`divnum', `divnum'))mydivnum error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum' error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum' error-->m4trace: -2- defn(`divnum', `divnum') error-->m4trace: -1- define(`mydivnum', `') ⇒ traceoff(`defn', `define') ⇒ |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is possible to redefine a macro temporarily, reverting to the
previous definition at a later time. This is done with the builtins
pushdef
and popdef
:
Analogous to define
and undefine
.
These macros work in a stack-like fashion. A macro is temporarily
redefined with pushdef
, which replaces an existing definition of
name, while saving the previous definition, before the new one is
installed. If there is no previous definition, pushdef
behaves
exactly like define
.
If a macro has several definitions (of which only one is accessible),
the topmost definition can be removed with popdef
. If there is
no previous definition, popdef
behaves like undefine
.
The expansion of both pushdef
and popdef
is void.
The macros pushdef
and popdef
are recognized only with
parameters.
define(`foo', `Expansion one.') ⇒ foo ⇒Expansion one. pushdef(`foo', `Expansion two.') ⇒ foo ⇒Expansion two. pushdef(`foo', `Expansion three.') ⇒ pushdef(`foo', `Expansion four.') ⇒ popdef(`foo') ⇒ foo ⇒Expansion three. popdef(`foo', `foo') ⇒ foo ⇒Expansion one. popdef(`foo') ⇒ foo ⇒foo |
If a macro with several definitions is redefined with define
, the
topmost definition is replaced with the new definition. If it is
removed with undefine
, all the definitions are removed,
and not only the topmost one. However, POSIX allows other
implementations that treat define
as replacing an entire stack
of definitions with a single new definition, so to be portable to other
implementations, it may be worth explicitly using popdef
and
pushdef
rather than relying on the GNU behavior of
define
.
define(`foo', `Expansion one.') ⇒ foo ⇒Expansion one. pushdef(`foo', `Expansion two.') ⇒ foo ⇒Expansion two. define(`foo', `Second expansion two.') ⇒ foo ⇒Second expansion two. undefine(`foo') ⇒ foo ⇒foo |
Local variables within macros are made with pushdef
and
popdef
. At the start of the macro a new definition is pushed,
within the macro it is manipulated and at the end it is popped,
revealing the former definition.
It is possible to temporarily redefine a builtin with pushdef
and defn
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Any macro can be called indirectly with indir
:
Results in a call to the macro name, which is passed the rest of the arguments args. If name is not defined, an error message is printed, and the expansion is void.
The macro indir
is recognized only with parameters.
This can be used to call macros with computed or “invalid”
names (define
allows such names to be defined):
define(`$$internal$macro', `Internal macro (name `$0')') ⇒ $$internal$macro ⇒$$internal$macro indir(`$$internal$macro') ⇒Internal macro (name $$internal$macro) |
The point is, here, that larger macro packages can have private macros
defined, that will not be called by accident. They can only be
called through the builtin indir
.
One other point to observe is that argument collection occurs before
indir
invokes name, so if argument collection changes the
value of name, that will be reflected in the final expansion.
This is different than the behavior when invoking macros directly,
where the definition that was in effect before argument collection is
used.
$ m4 -d define(`f', `1') ⇒ f(define(`f', `2')) ⇒1 indir(`f', define(`f', `3')) ⇒3 indir(`f', undefine(`f')) error-->m4:stdin:4: undefined macro `f' ⇒ |
When handed the result of defn
(see section Renaming macros) as one of its
arguments, indir
defers to the invoked name for whether a
token representing a builtin is recognized or flattened to the empty
string.
$ m4 -d indir(defn(`defn'), `divnum') error-->m4:stdin:1: Warning: indir: invalid macro name ignored ⇒ indir(`define', defn(`defn'), `divnum') error-->m4:stdin:2: Warning: define: invalid macro name ignored ⇒ indir(`define', `foo', defn(`divnum')) ⇒ foo ⇒0 indir(`divert', defn(`foo')) error-->m4:stdin:5: empty string treated as 0 in builtin `divert' ⇒ |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Builtin macros can be called indirectly with builtin
:
Results in a call to the builtin name, which is passed the rest of the arguments args. If name does not name a builtin, an error message is printed, and the expansion is void.
The macro builtin
is recognized only with parameters.
This can be used even if name has been given another definition that has covered the original, or been undefined so that no macro maps to the builtin.
pushdef(`define', `hidden') ⇒ undefine(`undefine') ⇒ define(`foo', `bar') ⇒hidden foo ⇒foo builtin(`define', `foo', defn(`divnum')) ⇒ foo ⇒0 builtin(`define', `foo', `BAR') ⇒ foo ⇒BAR undefine(`foo') ⇒undefine(foo) foo ⇒BAR builtin(`undefine', `foo') ⇒ foo ⇒foo |
The name argument only matches the original name of the builtin,
even when the ‘--prefix-builtins’ option (or ‘-P’,
see section Invoking m4) is in effect. This is different
from indir
, which only tracks current macro names.
$ m4 -P m4_builtin(`divnum') ⇒0 m4_builtin(`m4_divnum') error-->m4:stdin:2: undefined builtin `m4_divnum' ⇒ m4_indir(`divnum') error-->m4:stdin:3: undefined macro `divnum' ⇒ m4_indir(`m4_divnum') ⇒0 |
Note that indir
and builtin
can be used to invoke builtins
without arguments, even when they normally require parameters to be
recognized; but it will provoke a warning, and result in a void expansion.
builtin ⇒builtin builtin() error-->m4:stdin:2: undefined builtin `' ⇒ builtin(`builtin') error-->m4:stdin:3: Warning: too few arguments to builtin `builtin' ⇒ builtin(`builtin',) error-->m4:stdin:4: undefined builtin `' ⇒ builtin(`builtin', ``' ') error-->m4:stdin:5: undefined builtin ``' error-->' ⇒ indir(`index') error-->m4:stdin:7: Warning: too few arguments to builtin `index' ⇒ |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on March 13, 2013 using texi2html 1.82.