21.3.3 Quoting

It is been shown how m4 expands macros when it encounters a name that matches a defined macro in the input. There are times, however, when you wish to defer expansion. Principally, there are three situations when this is so:

Free-form text

There may be free-form text that you wish to appear at the output--and as such, be unaltered by any macros that may be inadvertently invoked in the input. It is not always possible to know if some particular name is defined as a macro, so it should be quoted.

Overcoming syntax rules

Sometimes you may wish to form strings which would violate M4's syntax rules -- for example, you might wish to use leading whitespace or a comma in a macro argument. The solution is to quote the entire string.

Macro arguments

This is the most common situation for quoting: when arguments to macros are to be taken literally and not expanded as the arguments are collected. In the previous section, an example was given that demonstrates the effects of not quoting the first argument to define. Quoting macro arguments is considered a good practice that you should emulate.

Strings are quoted by surrounding the quoted text with the ``' and `'' characters. When m4 encounters a quoted string--as a type of token (21.3.1 Token scanning)--the quoted string is expanded to the string itself, with the outermost quote characters removed.

Here is an example of a string that is triple quoted:

```foo''' =>``foo''

A more concrete example uses quoting to demonstrate how to prevent unwanted expansion within macro definitions:

define(`foo', ``bar'')dnl define(`bar', `zog')dnl foo =>bar

When the macro `foo' is defined, m4 strips off the outermost quotes and registers the definition `bar'. The dnl text has a special purpose, too, which will be covered in 21.4.1 Discarding input.

As the macro `foo' is expanded, the next pair of quote characters are stripped off and the string is expanded to `bar'. Since the expansion of the quoted string is the string itself (minus the quote characters), we have prevented unwanted expansion from the string `bar' to `zog'.

As mentioned in 21.3.1 Token scanning, the default M4 quote characters are ``' and `''. Since these are two commonly used characters in Bourne shell programming (51), Autoconf reassigns these to the `[' and `]' characters--a symmetric looking pair of characters least likely to cause problems when writing GNU Autotools macros. From this point forward, we shall use `[' and `]' as the quote characters and you can forget about the default M4 quotes.

Autoconf uses M4's built-in changequote macro to perform this reassignment and, in fact, this built-in is still available to you. In recent years, the common practice when needing to use the quote characters `[' or `]' or to quote a string with an legitimately imbalanced number of the quote characters has been to invoke changequote and temporarily reassign them around the affected area:

dnl Uh-oh, we need to use the apostrophe! And even worse, we have two dnl opening quote marks and no closing quote marks. changequote(<<, >>)dnl perl -e 'print "$]\n";' changequote([, ])dnl

This leads to a few potential problems, the least of which is that it's easy to reassign the quote characters and then forget to reset them, leading to total chaos! Moreover, it is possible to entirely disable M4's quoting mechanism by blindly changing the quote characters to a pair of empty strings.

In hindsight, the overwhelming conclusion is that using changequote within the GNU Autotools framework is a bad idea. Instead, leave the quote characters assigned as `[' and `]' and use the special strings @<:@ and @:>@ anywhere you want real square brackets to appear in your output. This is an easy practice to adopt, because it's faster and less error prone than using changequote:

perl -e 'print "$@:>@\n";'

This, and other guidelines for using M4 in the GNU Autotools framework are covered in detail in 21.5 Writing macros within the GNU Autotools framework.