Autoconf, Automake, and Libtool: Quoting

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

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html