[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. 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, and bring back the original value at a later time.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 Defining a macro

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

Builtin: define (name, [expansion])

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

Change the `%d` to `%s` and it is an associative array.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.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. 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. 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 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).

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.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
    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

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] | [ ? ]

## 5.4 Deleting a macro

A macro definition can be removed with `undefine`:

Builtin: undefine (name…)

  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] | [ ? ]

## 5.5 Renaming macros

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

Builtin: defn (name)

  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 silently converted to an empty string in most other contexts.

  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'

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.

    defn(`defn')
    ⇒
    define(defn(`divnum'), `cannot redefine a builtin token')
    error-->m4:stdin:2: Warning: define: invalid macro name ignored
    ⇒
    divnum
    ⇒0

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.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`:

Builtin: pushdef (name, [expansion])
Builtin: popdef (name…)

  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.

    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] | [ ? ]

## 5.7 Indirect call of macros

Any macro can be called indirectly with `indir`:

Builtin: indir (name, [args…])

  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.

    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.

    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] | [ ? ]

## 5.8 Indirect call of builtins

Builtin macros can be called indirectly with `builtin`:

Builtin: builtin (name, [args…])

  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.

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 `'
    ⇒

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by root on April, 16 2008 using texi2html 1.76.