Whole document tree
define(name [, expansion])
which defines name to expand to expansion. If expansion is not given, it is taken to be empty.
The expansion of
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
Macros can have arguments. The nth argument is denoted by
define(`exch', `$2, $1') => exch(arg1, arg2) =>arg2, arg1
This can be used, for example, if you like the arguments to
define(`exch', `$2, $1') => define(exch(``expansion text'', ``macro'')) => macro =>expansion text
See section Quoting macro arguments, for an explanation of the double quotes.
As a special case, the zero'th argument,
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.
The number of actual arguments in a macro call is denoted by
define(`nargs', `$#') => nargs =>0 nargs() =>1 nargs(arg1, arg2, arg3) =>3
define(`echo', `$*') => echo(arg1, arg2, arg3 , arg4) =>arg1,arg2,arg3 ,arg4
Often each argument should be quoted, and the notation
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
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
define(`foo', `$$$ hello $$$') => foo =>$$$ hello $$$
If you want a macro to expand to something like `$12', put a pair
of quotes after the
which removes the macro name. The macro name must necessarily be quoted, since it will be expanded otherwise.
The expansion of
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
which expands to the quoted definition of name. If the argument is not a defined macro, the expansion is void.
If name is a user-defined macro, the quoted definition is simply
the quoted expansion text. If, instead, 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
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,
pushdef(name [, expansion]) popdef(name)
which are quite analogous to
These macros work in a stack-like fashion. A macro is temporarily
If a macro has several definitions (of which only one is accessible),
the topmost definition can be removed with
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
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
It is possible to temporarily redefine a builtin 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 "illegal"
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
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.