GNU macro processor - 4. How to define new macros

Go to the first, previous, next, last section, table of contents.

# 4. How to define new macros

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.

## 4.1 Defining a macro

The normal way to define or redefine macros is to use the builtin `define`:

    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 `dnl`. See section 7.1 Deleting whitespace in input, for details.

The macro `define` is recognized only with parameters.

## 4.2 Arguments to macros

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 3.4 Quoting macro arguments, for an explanation of the double quotes.

GNU `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 one digit.

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.

## 4.3 Special arguments to macros

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

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..
    echo2(foo)
    =>This is macro foo.

See section 6.2 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 `m4` from interpreting the `$` sign as a reference to an argument.

## 4.4 Deleting a macro

A macro definition can be removed with `undefine`:

    undefine(name)

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 case, `undefine` does nothing.

The macro `undefine` is recognized only with parameters.

## 4.5 Renaming macros

It is possible to rename an already defined macro. To do this, you need the builtin `defn`:

    defn(name)

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 `define` (and `pushdef`), and is ignored in any other context.

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 macro `defn` is recognized only with parameters.

## 4.6 Temporarily redefining macros

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`:

    pushdef(name [, expansion])
    popdef(name)

which are quite 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`.

    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`, 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.

    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 `pushdef` and `defn`.

The macros `pushdef` and `popdef` are recognized only with parameters.

## 4.7 Indirect call of macros

Any macro can be called indirectly with `indir`:

    indir(name, ...)

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" 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`.

## 4.8 Indirect call of builtins

Builtin macros can be called indirectly with `builtin`:

    builtin(name, ...)

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.

The macro `builtin` is recognized only with parameters.

Go to the first, previous, next, last section, table of contents.