Macros can be defined, redefined and deleted in several different ways. Also, it is possible to redefine a macro, without losing a previous value, which can be brought back at a later time.
The normal way to define or redefine macros is to use the builtin
define(name [, expansion])
which defines name to expand to expansion. If expansion is not given, it is taken to be empty.
The expansion of
define is void.
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
See section Deleting whitespace in input, for details.
The first argument to
define does not have to be a simple word.
It can be any text string. A macro with a non standard name cannot be
invoked in the normal way, as the name is not recognised. It can only
be referenced by the builtins section Indirect call of macros and section Renaming macros.
Arrays and associative arrays can be simulated by using this trick.
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
%s and it is an associative array.
define is recognized only with parameters.
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. Here is a example of a macro with
two arguments. It simply exchanges the order of the two arguments.
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 Quoting macro arguments, for an explanation of the double quotes.
m4 allows the number following the `$' to consist of one
or more digits, allowing macros to have any number of arguments. This
is not so in UNIX implementations of
m4, which only recognize
As a special case, the zero'th 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.
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. Thus, a macro to display the number of arguments
given can be
define(`nargs', `$#') => nargs =>0 nargs() =>1 nargs(arg1, arg2, arg3) =>3
$* 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
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.. echo2(foo) =>This is macro foo.
See section Tracing macro calls, if you do not understand this.
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', put a pair
of quotes after the
$. This will prevent
$ sign as a reference to an argument.
A macro definition can be removed with
which removes the macro name. The macro name must necessarily be quoted, since it will be expanded otherwise.
The expansion of
undefine is void.
foo =>foo define(`foo', `expansion text') => foo =>expansion text undefine(`foo') => foo =>foo
It is not an error for name to have no macro definition. In that
undefine does nothing.
undefine is recognized only with parameters.
It is possible to rename an already defined macro. To do this, you need
which expands to the quoted definition of name. If the argument is not a defined macro, the expansion is void.
If name 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
and is ignored in any other context.
Its normal use is best understood through an example, which shows how to
define(`zap', defn(`undefine')) => zap(`undefine') => undefine(`zap') =>undefine(zap)
In this way,
defn can be used to copy definitions of builtin
macros. Even if the original macro is removed, the other name can still
be used to access the definition.
If, instead, name is a user-defined macro, the expansion is simply
the quoted text of the macro, and
defn can therefore be used to
copy user macro definitions as well.
Macros used as string variables should be referred through
to avoid unwanted expansion of the text:
define(`string', `The macro dnl is very useful ') => string =>The macro @comment defn(`string') =>The macro dnl is very useful =>
defn is recognized only with parameters.
It is possible to redefine a macro temporarily, reverting to the
previous definition at a later time.
This is done with the builtins
pushdef(name [, expansion]) popdef(name)
which are quite analogous to
These macros work in a stack-like fashion. A macro is temporarily
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,
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
define(`foo', `Expansion one.') => foo =>Expansion one. pushdef(`foo', `Expansion two.') => foo =>Expansion two. popdef(`foo') => foo =>Expansion one. popdef(`foo') => foo =>foo
If a macro with several definitions is redefined with
topmost definition is replaced with the new definition. If it is
undefine, all the definitions are removed,
and not only the topmost one.
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
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
popdef are recognized only with
Any macro can be called indirectly with
which results in a call to the macro name, which is passed the
rest of the arguments. This can be used to call macros with computed or
with"illegal" 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
Builtin macros can be called indirectly with
which results in a call to the builtin name, which is passed the rest of the arguments. This can be used, if name has been given another definition that has covered the original.
builtin is recognized only with parameters.
The name of the currently defined macro can be accessed by
which results in a sorted list of quoted strings. This contrasts with
dumpdef which output can not be accessed by
When given arguments,
symbols returns the sorted subset of the
symbols currently defined:
symbols(`ifndef', `ifdef', `define', `undef') =>define,ifdef
Go to the first, previous, next, last section, table of contents.