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

8. Programming in M4

Autoconf is written on top of two layers: M4sugar, which provides convenient macros for pure M4 programming, and M4sh, which provides macros dedicated to shell script generation.

As of this version of Autoconf, these two layers still contain experimental macros, whose interface might change in the future. As a matter of fact, anything that is not documented must not be used.


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

8.1 M4 Quotation

The most common problem with existing macros is an improper quotation. This section, which users of Autoconf can skip, but which macro writers must read, first justifies the quotation scheme that was chosen for Autoconf and then ends with a rule of thumb. Understanding the former helps one to follow the latter.


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

8.1.1 Active Characters

To fully understand where proper quotation is important, you first need to know what the special characters are in Autoconf: `#' introduces a comment inside which no macro expansion is performed, `,' separates arguments, `[' and `]' are the quotes themselves, `(' and `)' (which M4 tries to match by pairs), and finally `$' inside a macro definition.

In order to understand the delicate case of macro calls, we first have to present some obvious failures. Below they are "obvious-ified", but when you find them in real life, they are usually in disguise.

Comments, introduced by a hash and running up to the newline, are opaque tokens to the top level: active characters are turned off, and there is no macro expansion:

 
# define([def], ine)
⇒# define([def], ine)

Each time there can be a macro expansion, there is a quotation expansion, i.e., one level of quotes is stripped:

 
int tab[10];
⇒int tab10;
[int tab[10];]
⇒int tab[10];

Without this in mind, the reader might try hopelessly to use her macro array:

 
define([array], [int tab[10];])
array
⇒int tab10;
[array]
⇒array

How can you correctly output the intended results(3)?


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

8.1.2 One Macro Call

Let's proceed on the interaction between active characters and macros with this small macro, which just returns its first argument:

 
define([car], [$1])

The two pairs of quotes above are not part of the arguments of define; rather, they are understood by the top level when it tries to find the arguments of define. Therefore, assuming car is not already defined, it is equivalent to write:

 
define(car, $1)

But, while it is acceptable for a `configure.ac' to avoid unnecessary quotes, it is bad practice for Autoconf macros which must both be more robust and also advocate perfect style.

At the top level, there are only two possibilities: either you quote or you don't:

 
car(foo, bar, baz)
⇒foo
[car(foo, bar, baz)]
⇒car(foo, bar, baz)

Let's pay attention to the special characters:

 
car(#)
error-->EOF in argument list

The closing parenthesis is hidden in the comment; with a hypothetical quoting, the top level understood it this way:

 
car([#)]

Proper quotation, of course, fixes the problem:

 
car([#])
⇒#

Here are more examples:

 
car(foo, bar)
⇒foo
car([foo, bar])
⇒foo, bar
car((foo, bar))
⇒(foo, bar)
car([(foo], [bar)])
⇒(foo
define([a], [b])
⇒
car(a)
⇒b
car([a])
⇒b
car([[a]])
⇒a
car([[[a]]])
⇒[a]

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

8.1.3 Quoting and Parameters

When M4 encounters `$' within a macro definition, followed immediately by a character it recognizes (`0'`9', `#', `@', or `*'), it will perform M4 parameter expansion. This happens regardless of how many layers of quotes the parameter expansion is nested within, or even if it occurs in text that will be rescanned as a comment.

 
define([none], [$1])
⇒
define([one], [[$1]])
⇒
define([two], [[[$1]]])
⇒
define([comment], [# $1])
⇒
define([active], [ACTIVE])
⇒
none([active])
⇒ACTIVE
one([active])
⇒active
two([active])
⇒[active]
comment([active])
⇒# active

On the other hand, since autoconf generates shell code, you often want to output shell variable expansion, rather than performing M4 parameter expansion. To do this, you must use M4 quoting to separate the `$' from the next character in the definition of your macro. If the macro definition occurs in single-quoted text, then insert another level of quoting; if the usage is already inside a double-quoted string, then split it into concatenated strings.

 
define([single], [a single-quoted $[]1 definition])
⇒
define([double], [[a double-quoted $][1 definition]])
⇒
single
⇒a single-quoted $1 definition
double
⇒a double-quoted $1 definition

Posix states that M4 implementations are free to provide implementation extensions when `${' is encountered in a macro definition. Autoconf reserves the longer sequence `${{' for use with planned extensions that will be available in the future GNU M4 2.0, but guarantees that all other instances of `${' will be output literally. Therefore, this idiom can also be used to output shell code parameter references:

 
define([first], [${1}])first
⇒${1}

Posix also states that `$11' should expand to the first parameter concatenated with a literal `1', although some versions of GNU M4 expand the eleventh parameter instead. For portability, you should only use single-digit M4 parameter expansion.

With this in mind, we can explore the cases where macros invoke macros....


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

8.1.4 Quotation and Nested Macros

The examples below use the following macros:

 
define([car], [$1])
define([active], [ACT, IVE])
define([array], [int tab[10]])

Each additional embedded macro call introduces other possible interesting quotations:

 
car(active)
⇒ACT
car([active])
⇒ACT, IVE
car([[active]])
⇒active

In the first case, the top level looks for the arguments of car, and finds `active'. Because M4 evaluates its arguments before applying the macro, `active' is expanded, which results in:

 
car(ACT, IVE)
⇒ACT

In the second case, the top level gives `active' as first and only argument of car, which results in:

 
active
⇒ACT, IVE

i.e., the argument is evaluated after the macro that invokes it. In the third case, car receives `[active]', which results in:

 
[active]
⇒active

exactly as we already saw above.

The example above, applied to a more realistic example, gives:

 
car(int tab[10];)
⇒int tab10;
car([int tab[10];])
⇒int tab10;
car([[int tab[10];]])
⇒int tab[10];

Huh? The first case is easily understood, but why is the second wrong, and the third right? To understand that, you must know that after M4 expands a macro, the resulting text is immediately subjected to macro expansion and quote removal. This means that the quote removal occurs twice--first before the argument is passed to the car macro, and second after the car macro expands to the first argument.

As the author of the Autoconf macro car, you then consider it to be incorrect that your users have to double-quote the arguments of car, so you "fix" your macro. Let's call it qar for quoted car:

 
define([qar], [[$1]])

and check that qar is properly fixed:

 
qar([int tab[10];])
⇒int tab[10];

Ahhh! That's much better.

But note what you've done: now that the result of qar is always a literal string, the only time a user can use nested macros is if she relies on an unquoted macro call:

 
qar(active)
⇒ACT
qar([active])
⇒active

leaving no way for her to reproduce what she used to do with car:

 
car([active])
⇒ACT, IVE

Worse yet: she wants to use a macro that produces a set of cpp macros:

 
define([my_includes], [#include <stdio.h>])
car([my_includes])
⇒#include <stdio.h>
qar(my_includes)
error-->EOF in argument list

This macro, qar, because it double quotes its arguments, forces its users to leave their macro calls unquoted, which is dangerous. Commas and other active symbols are interpreted by M4 before they are given to the macro, often not in the way the users expect. Also, because qar behaves differently from the other macros, it's an exception that should be avoided in Autoconf.


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

8.1.5 changequote is Evil

The temptation is often high to bypass proper quotation, in particular when it's late at night. Then, many experienced Autoconf hackers finally surrender to the dark side of the force and use the ultimate weapon: changequote.

The M4 builtin changequote belongs to a set of primitives that allow one to adjust the syntax of the language to adjust it to one's needs. For instance, by default M4 uses ``' and `'' as quotes, but in the context of shell programming (and actually of most programming languages), that's about the worst choice one can make: because of strings and back-quoted expressions in shell code (such as `'this'' and ``that`'), and because of literal characters in usual programming languages (as in `'0''), there are many unbalanced ``' and `''. Proper M4 quotation then becomes a nightmare, if not impossible. In order to make M4 useful in such a context, its designers have equipped it with changequote, which makes it possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and Autotest all have chosen to use `[' and `]'. Not especially because they are unlikely characters, but because they are characters unlikely to be unbalanced.

There are other magic primitives, such as changecom to specify what syntactic forms are comments (it is common to see `changecom(<!--, -->)' when M4 is used to produce HTML pages), changeword and changesyntax to change other syntactic details (such as the character to denote the nth argument, `$' by default, the parentheses around arguments, etc.).

These primitives are really meant to make M4 more useful for specific domains: they should be considered like command line options: `--quotes', `--comments', `--words', and `--syntax'. Nevertheless, they are implemented as M4 builtins, as it makes M4 libraries self contained (no need for additional options).

There lies the problem....


The problem is that it is then tempting to use them in the middle of an M4 script, as opposed to its initialization. This, if not carefully thought out, can lead to disastrous effects: you are changing the language in the middle of the execution. Changing and restoring the syntax is often not enough: if you happened to invoke macros in between, these macros are lost, as the current syntax is probably not the one they were implemented with.


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

8.1.6 Quadrigraphs

When writing an Autoconf macro you may occasionally need to generate special characters that are difficult to express with the standard Autoconf quoting rules. For example, you may need to output the regular expression `[^[]', which matches any character other than `['. This expression contains unbalanced brackets so it cannot be put easily into an M4 macro.

Additionally, there are a few m4sugar macros (such as m4_split and m4_expand) which internally use special markers in addition to the regular quoting characters. If the arguments to these macros contain the literal strings `-=<{(' or `)}>=-', the macros might behave incorrectly.

You can work around these problems by using one of the following quadrigraphs:

`@<:@'

`['

`@:>@'

`]'

`@S|@'

`$'

`@%:@'

`#'

`@{:@'

`('

`@:}@'

`)'

`@&t@'

Expands to nothing.

Quadrigraphs are replaced at a late stage of the translation process, after m4 is run, so they do not get in the way of M4 quoting. For example, the string `^@<:@', independently of its quotation, appears as `^[' in the output.

The empty quadrigraph can be used:

The name `@&t@' was suggested by Paul Eggert:

I should give some credit to the `@&t@' pun. The `&' is my own invention, but the `t' came from the source code of the ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame), and which used `mt' to denote the empty string. In C, it would have looked like something like:

 
char const mt[] = "";

but of course the source code was written in Algol 68.

I don't know where he got `mt' from: it could have been his own invention, and I suppose it could have been a common pun around the Cambridge University computer lab at the time.


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

8.1.7 Dealing with unbalanced parentheses

One of the pitfalls of portable shell programming is that case statements require unbalanced parentheses (see Limitations of Shell Builtins). With syntax highlighting editors, the presence of unbalanced `)' can interfere with editors that perform syntax highlighting of macro contents based on finding the matching `('. Another concern is how much editing must be done when transferring code snippets between shell scripts and macro definitions. But most importantly, the presence of unbalanced parentheses can introduce expansion bugs.

For an example, here is an underquoted attempt to use the macro my_case, which happens to expand to a portable case statement:

 
AC_DEFUN([my_case],
[case $file_name in
  *.c) echo "C source code";;
esac])
AS_IF(:, my_case)

In the above example, the AS_IF call underquotes its arguments. As a result, the unbalanced `)' generated by the premature expansion of my_case results in expanding AS_IF with a truncated parameter, and the expansion is syntactically invalid:

 
if :; then
  case $file_name in
  *.c
fi echo "C source code";;
esac)

If nothing else, this should emphasize the importance of the quoting arguments to macro calls. On the other hand, there are several variations for defining my_case to be more robust, even when used without proper quoting, each with some benefits and some drawbacks.


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

8.1.8 Quotation Rule Of Thumb

To conclude, the quotation rule of thumb is:

One pair of quotes per pair of parentheses.

Never over-quote, never under-quote, in particular in the definition of macros. In the few places where the macros need to use brackets (usually in C program text or regular expressions), properly quote the arguments!

It is common to read Autoconf programs with snippets like:

 
AC_TRY_LINK(
changequote(<<, >>)dnl
<<#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif>>,
changequote([, ])dnl
[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)

which is incredibly useless since AC_TRY_LINK is already double quoting, so you just need:

 
AC_TRY_LINK(
[#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif],
            [atoi (*tzname);],
            [ac_cv_var_tzname=yes],
            [ac_cv_var_tzname=no])

The M4-fluent reader might note that these two examples are rigorously equivalent, since M4 swallows both the `changequote(<<, >>)' and `<<' `>>' when it collects the arguments: these quotes are not part of the arguments!

Simplified, the example above is just doing this:

 
changequote(<<, >>)dnl
<<[]>>
changequote([, ])dnl

instead of simply:

 
[[]]

With macros that do not double quote their arguments (which is the rule), double-quote the (risky) literals:

 
AC_LINK_IFELSE([AC_LANG_PROGRAM(
[[#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif]],
                                [atoi (*tzname);])],
               [ac_cv_var_tzname=yes],
               [ac_cv_var_tzname=no])

Please note that the macro AC_TRY_LINK is obsolete, so you really should be using AC_LINK_IFELSE instead.

See section Quadrigraphs, for what to do if you run into a hopeless case where quoting does not suffice.

When you create a configure script using newly written macros, examine it carefully to check whether you need to add more quotes in your macros. If one or more words have disappeared in the M4 output, you need more quotes. When in doubt, quote.

However, it's also possible to put on too many layers of quotes. If this happens, the resulting configure script may contain unexpanded macros. The autoconf program checks for this problem by looking for the string `AC_' in `configure'. However, this heuristic does not work in general: for example, it does not catch overquoting in AC_DEFINE descriptions.


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

8.2 Using autom4te

The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition to Autoconf per se, heavily rely on M4. All these different uses revealed common needs factored into a layer over M4: autom4te(4).

autom4te is a preprocessor that is like m4. It supports M4 extensions designed for use in tools like Autoconf.


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

8.2.1 Invoking autom4te

The command line arguments are modeled after M4's:

 
autom4te options files

where the files are directly passed to m4. By default, GNU M4 is found during configuration, but the environment variable M4 can be set to tell autom4te where to look. In addition to the regular expansion, it handles the replacement of the quadrigraphs (see section Quadrigraphs), and of `__oline__', the current line in the output. It supports an extended syntax for the files:

`file.m4f'

This file is an M4 frozen file. Note that all the previous files are ignored. See the option `--melt' for the rationale.

`file?'

If found in the library path, the file is included for expansion, otherwise it is ignored instead of triggering a failure.


Of course, it supports the Autoconf common subset of options:

`--help'
`-h'

Print a summary of the command line options and exit.

`--version'
`-V'

Print the version number of Autoconf and exit.

`--verbose'
`-v'

Report processing steps.

`--debug'
`-d'

Don't remove the temporary files and be even more verbose.

`--include=dir'
`-I dir'

Also look for input files in dir. Multiple invocations accumulate.

`--output=file'
`-o file'

Save output (script or trace) to file. The file `-' stands for the standard output.


As an extension of m4, it includes the following options:

`--warnings=category'
`-W category'

Report the warnings related to category (which can actually be a comma separated list). See section Reporting Messages, macro AC_DIAGNOSE, for a comprehensive list of categories. Special values include:

`all'

report all the warnings

`none'

report none

`error'

treats warnings as errors

`no-category'

disable warnings falling into category

Warnings about `syntax' are enabled by default, and the environment variable WARNINGS, a comma separated list of categories, is honored. `autom4te -W category' actually behaves as if you had run:

 
autom4te --warnings=syntax,$WARNINGS,category

For example, if you want to disable defaults and WARNINGS of autom4te, but enable the warnings about obsolete constructs, you would use `-W none,obsolete'.

autom4te displays a back trace for errors, but not for warnings; if you want them, just pass `-W error'.

`--melt'
`-M'

Do not use frozen files. Any argument file.m4f is replaced by file.m4. This helps tracing the macros which are executed only when the files are frozen, typically m4_define. For instance, running:

 
autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4

is roughly equivalent to running:

 
m4 1.m4 2.m4 3.m4 4.m4 input.m4

while

 
autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4

is equivalent to:

 
m4 --reload-state=4.m4f input.m4
`--freeze'
`-F'

Produce a frozen state file. autom4te freezing is stricter than M4's: it must produce no warnings, and no output other than empty lines (a line with white space is not empty) and comments (starting with `#'). Unlike m4's similarly-named option, this option takes no argument:

 
autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f

corresponds to

 
m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
`--mode=octal-mode'
`-m octal-mode'

Set the mode of the non-traces output to octal-mode; by default `0666'.


As another additional feature over m4, autom4te caches its results. GNU M4 is able to produce a regular output and traces at the same time. Traces are heavily used in the GNU Build System: autoheader uses them to build `config.h.in', autoreconf to determine what GNU Build System components are used, automake to "parse" `configure.ac' etc. To avoid recomputation, traces are cached while performing regular expansion, and conversely. This cache is (actually, the caches are) stored in the directory `autom4te.cache'. It can safely be removed at any moment (especially if for some reason autom4te considers it trashed).

`--cache=directory'
`-C directory'

Specify the name of the directory where the result should be cached. Passing an empty value disables caching. Be sure to pass a relative file name, as for the time being, global caches are not supported.

`--no-cache'

Don't cache the results.

`--force'
`-f'

If a cache is used, consider it obsolete (but update it anyway).


Because traces are so important to the GNU Build System, autom4te provides high level tracing features as compared to M4, and helps exploiting the cache:

`--trace=macro[:format]'
`-t macro[:format]'

Trace the invocations of macro according to the format. Multiple `--trace' arguments can be used to list several macros. Multiple `--trace' arguments for a single macro are not cumulative; instead, you should just make format as long as needed.

The format is a regular string, with newlines if desired, and several special escape codes. It defaults to `$f:$l:$n:$%'. It can use the following special escapes:

`$$'

The character `$'.

`$f'

The file name from which macro is called.

`$l'

The line number from which macro is called.

`$d'

The depth of the macro call. This is an M4 technical detail that you probably don't want to know about.

`$n'

The name of the macro.

`$num'

The numth argument of the call to macro.

`$@'
`$sep@'
`${separator}@'

All the arguments passed to macro, separated by the character sep or the string separator (`,' by default). Each argument is quoted, i.e., enclosed in a pair of square brackets.

`$*'
`$sep*'
`${separator}*'

As above, but the arguments are not quoted.

`$%'
`$sep%'
`${separator}%'

As above, but the arguments are not quoted, all new line characters in the arguments are smashed, and the default separator is `:'.

The escape `$%' produces single-line trace outputs (unless you put newlines in the `separator'), while `$@' and `$*' do not.

See section Using autoconf to Create configure, for examples of trace uses.

`--preselect=macro'
`-p macro'

Cache the traces of macro, but do not enable traces. This is especially important to save CPU cycles in the future. For instance, when invoked, autoconf preselects all the macros that autoheader, automake, autoreconf, etc., trace, so that running m4 is not needed to trace them: the cache suffices. This results in a huge speed-up.


Finally, autom4te introduces the concept of Autom4te libraries. They consists in a powerful yet extremely simple feature: sets of combined command line arguments:

`--language=language'
`-l language'

Use the language Autom4te library. Current languages include:

M4sugar

create M4sugar output.

M4sh

create M4sh executable shell scripts.

Autotest

create Autotest executable test suites.

Autoconf-without-aclocal-m4

create Autoconf executable configure scripts without reading `aclocal.m4'.

Autoconf

create Autoconf executable configure scripts. This language inherits all the characteristics of Autoconf-without-aclocal-m4 and additionally reads `aclocal.m4'.

`--prepend-include=dir'
`-B dir'

Prepend directory dir to the search path. This is used to include the language-specific files before any third-party macros.

As an example, if Autoconf is installed in its default location, `/usr/local', the command `autom4te -l m4sugar foo.m4' is strictly equivalent to the command:

 
autom4te --prepend-include /usr/local/share/autoconf \
  m4sugar/m4sugar.m4f --warnings syntax foo.m4

Recursive expansion applies here: the command `autom4te -l m4sh foo.m4' is the same as `autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4', i.e.:

 
autom4te --prepend-include /usr/local/share/autoconf \
  m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4

The definition of the languages is stored in `autom4te.cfg'.


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

8.2.2 Customizing autom4te

One can customize autom4te via `~/.autom4te.cfg' (i.e., as found in the user home directory), and `./.autom4te.cfg' (i.e., as found in the directory from which autom4te is run). The order is first reading `autom4te.cfg', then `~/.autom4te.cfg', then `./.autom4te.cfg', and finally the command line arguments.

In these text files, comments are introduced with #, and empty lines are ignored. Customization is performed on a per-language basis, wrapped in between a `begin-language: "language"', `end-language: "language"' pair.

Customizing a language stands for appending options (see section Invoking autom4te) to the current definition of the language. Options, and more generally arguments, are introduced by `args: arguments'. You may use the traditional shell syntax to quote the arguments.

As an example, to disable Autoconf caches (`autom4te.cache') globally, include the following lines in `~/.autom4te.cfg':

## ------------------ ##
## User Preferences.  ##
## ------------------ ##

begin-language: "Autoconf-without-aclocal-m4"
args: --no-cache
end-language: "Autoconf-without-aclocal-m4"

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

8.3 Programming in M4sugar

M4 by itself provides only a small, but sufficient, set of all-purpose macros. M4sugar introduces additional generic macros. Its name was coined by Lars J. Aas: "Readability And Greater Understanding Stands 4 M4sugar".

M4sugar reserves the macro namespace `^_m4_' for internal use, and the macro namespace `^m4_' for M4sugar macros. You should not define your own macros into these namespaces.


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

8.3.1 Redefined M4 Macros

With a few exceptions, all the M4 native macros are moved in the `m4_' pseudo-namespace, e.g., M4sugar renames define as m4_define etc.

The list of macros unchanged from M4, except for their name, is:

Some M4 macros are redefined, and are slightly incompatible with their native equivalent.

Macro: __file__
Macro: __line__

All M4 macros starting with `__' retain their original name: for example, no m4__file__ is defined.

Macro: __oline__

This is not technically a macro, but a feature of Autom4te. The sequence __oline__ can be used similarly to the other m4sugar location macros, but rather than expanding to the location of the input file, it is translated to the line number where it appears in the output file after all other M4 expansions.

Macro: dnl

This macro kept its original name: no m4_dnl is defined.

Macro: m4_bpatsubst (string, regexp, [replacement]@c)

This macro corresponds to patsubst. The name m4_patsubst is kept for future versions of M4sugar, once GNU M4 2.0 is released and supports extended regular expression syntax.

Macro: m4_bregexp (string, regexp, [replacement]@c)

This macro corresponds to regexp. The name m4_regexp is kept for future versions of M4sugar, once GNU M4 2.0 is released and supports extended regular expression syntax.

Macro: m4_copy (source, dest)
Macro: m4_copy_force (source, dest)
Macro: m4_rename (source, dest)
Macro: m4_rename_force (source, dest)

These macros aren't directly builtins, but are closely related to m4_pushdef and m4_defn. m4_copy and m4_rename ensure that dest is undefined, while m4_copy_force and m4_rename_force overwrite any existing definition. All four macros then proceed to copy the entire pushdef stack of definitions of source over to dest. m4_copy and m4_copy_force preserve the source (including in the special case where source is undefined), while m4_rename and m4_rename_force undefine the original macro name (making it an error to rename an undefined source).

Note that attempting to invoke a renamed macro might not work, since the macro may have a dependence on helper macros accessed via composition of `$0' but that were not also renamed; likewise, other macros may have a hard-coded dependence on source and could break if source has been deleted. On the other hand, it is always safe to rename a macro to temporarily move it out of the way, then rename it back later to restore original semantics.

Macro: m4_defn (macro…)

This macro fails if macro is not defined, even when using older versions of M4 that did not warn. See m4_undefine. Unfortunately, in order to support these older versions of M4, there are some situations involving unbalanced quotes where concatenating multiple macros together will work in newer M4 but not in m4sugar; use quadrigraphs to work around this.

Macro: m4_divert (diversion)

M4sugar relies heavily on diversions, so rather than behaving as a primitive, m4_divert behaves like:

 
m4_divert_pop()m4_divert_push([diversion])

See section Diversion support, for more details about the use of the diversion stack.

Macro: m4_dumpdef (name…)
Macro: m4_dumpdefs (name…)

m4_dumpdef is like the M4 builtin, except that this version requires at least one argument, output always goes to standard error rather than the current debug file, no sorting is done on multiple arguments, and an error is issued if any name is undefined. m4_dumpdefs is a convenience macro that calls m4_dumpdef for all of the m4_pushdef stack of definitions, starting with the current, and silently does nothing if name is undefined.

Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a builtin is output as the empty string. This behavior is rectified by using M4 1.6 or newer. However, this behavior difference means that m4_dumpdef should only be used while developing m4sugar macros, and never in the final published form of a macro.

Macro: m4_esyscmd_s (command)

Like m4_esyscmd, this macro expands to the result of running command in a shell. The difference is that any trailing newlines are removed, so that the output behaves more like shell command substitution.

Macro: m4_exit (exit-status)

This macro corresponds to m4exit.

Macro: m4_if (comment)
Macro: m4_if (string-1, string-2, equal, [not-equal]@c)
Macro: m4_if (string-1, string-2, equal-1,   string-3, string-4, equal-2, …, [not-equal]@c)

This macro corresponds to ifelse. string-1 and string-2 are compared literally, so usually one of the two arguments is passed unquoted. See section Conditional constructs, for more conditional idioms.

Macro: m4_include (file)
Macro: m4_sinclude (file)

Like the M4 builtins, but warn against multiple inclusions of file.

Macro: m4_mkstemp (template)
Macro: m4_maketemp (template)

Posix requires maketemp to replace the trailing `X' characters in template with the process id, without regards to the existence of a file by that name, but this a security hole. When this was pointed out to the Posix folks, they agreed to invent a new macro mkstemp that always creates a uniquely named file, but not all versions of GNU M4 support the new macro. In M4sugar, m4_maketemp and m4_mkstemp are synonyms for each other, and both have the secure semantics regardless of which macro the underlying M4 provides.

Macro: m4_popdef (macro…)

This macro fails if macro is not defined, even when using older versions of M4 that did not warn. See m4_undefine.

Macro: m4_undefine (macro…)

This macro fails if macro is not defined, even when using older versions of M4 that did not warn. Use

 
m4_ifdef([macro], [m4_undefine([macro])])

if you are not sure whether macro is defined.

Macro: m4_undivert (diversion…)

Unlike the M4 builtin, at least one diversion must be specified. Also, since the M4sugar diversion stack prefers named diversions, the use of m4_undivert to include files is risky. See section Diversion support, for more details about the use of the diversion stack.

Macro: m4_wrap (text)
Macro: m4_wrap_lifo (text)

These macros correspond to m4wrap. Posix requires arguments of multiple wrap calls to be reprocessed at EOF in the same order as the original calls (first-in, first-out). GNU M4 versions through 1.4.10, however, reprocess them in reverse order (last-in, first-out). Both orders are useful, therefore, you can rely on m4_wrap to provide FIFO semantics and m4_wrap_lifo for LIFO semantics, regardless of the underlying GNU M4 version.

Unlike the GNU M4 builtin, these macros only recognize one argument, and avoid token pasting between consecutive invocations. On the other hand, nested calls to m4_wrap from within wrapped text work just as in the builtin.


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

8.3.2 Diagnostic messages from M4sugar

When macros statically diagnose abnormal situations, benign or fatal, they should report them using these macros. For issuing dynamic issues, i.e., when configure is run, see Printing Messages.

Macro: m4_assert (expression, [exit-status = `1']@c)

Assert that the arithmetic expression evaluates to non-zero. Otherwise, issue a fatal error, and exit autom4te with exit-status.

Macro: m4_errprintn (message)

Similar to the builtin m4_errprint, except that a newline is guaranteed after message.

Macro: m4_fatal (message)

Report a severe error message prefixed with the current location, and have autom4te die.

Macro: m4_location

Useful as a prefix in a message line. Short for:

 
__file__:__line__

Macro: m4_warn (category, message)

Report message as a warning (or as an error if requested by the user) if warnings of the category are turned on. If the message is emitted, it is prefixed with the current location, and followed by a call trace of all macros defined via AC_DEFUN used to get to the current expansion. You are encouraged to use standard categories, which currently include:

`all'

messages that don't fall into one of the following categories. Use of an empty category is equivalent.

`cross'

related to cross compilation issues.

`obsolete'

use of an obsolete construct.

`syntax'

dubious syntactic constructs, incorrectly ordered macro calls.


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

8.3.3 Diversion support

M4sugar makes heavy use of diversions, because it is often the case that text that must appear early in the output is not discovered until late in the input. Additionally, some of the topological sorting algorithms used in resolving macro dependencies use diversions. However, most macros should not need to change diversions directly, but rather rely on higher-level M4sugar macros to manage diversions transparently.

In the rare case that it is necessary to write a macro that explicitly outputs text to a different diversion, it is important to be aware of an M4 limitation regarding diversions: text only goes to a diversion if it is not part of argument collection. Therefore, any macro that changes the current diversion cannot be used as an unquoted argument to another macro, but must be expanded at the top level. The macro m4_expand will diagnose any attempt to change diversions, since it is generally useful only as an argument to another macro. The following example shows what happens when diversion manipulation is attempted within macro arguments:

 
m4_do([normal text]
m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL])
[m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl
⇒normal text
⇒unwanted

Notice that the unquoted text unwanted is output, even though it was processed while the current diversion was KILL, because it was collected as part of the argument to m4_do. However, the text discarded disappeared as desired, because the diversion changes were single-quoted, and were not expanded until the top-level rescan of the output of m4_do.

To make diversion management easier, M4sugar uses the concept of named diversions. Rather than using diversion numbers directly, it is nicer to associate a name with each diversion; the diversion number associated with a particular diversion name is an implementation detail, so you should only use diversion names. In general, you should not output text to a named diversion until after calling the appropriate initialization routine for your language (m4_init, AS_INIT, AT_INIT, …), although there are some exceptions documented below.

M4sugar defines two named diversions.

KILL

Text written to this diversion is discarded. This is the default diversion once M4sugar is initialized.

GROW

This diversion is used behind the scenes by topological sorting macros, such as AC_REQUIRE.

M4sh adds several more named diversions.

BINSH

This diversion is reserved for the `#!' interpreter line.

HEADER-REVISION

This diversion holds text from AC_REVISION.

HEADER-COMMENT

This diversion holds comments about the purpose of a file.

HEADER-COPYRIGHT

This diversion is managed by AC_COPYRIGHT.

M4SH-SANITIZE

This diversion contains M4sh sanitization code, used to ensure M4sh is executing in a reasonable shell environment.

M4SH-INIT

This diversion contains M4sh initialization code, initializing variables that are required by other M4sh macros.

BODY

This diversion contains the body of the shell code, and is the default diversion once M4sh is initialized.

Autotest inherits diversions from M4sh, and changes the default diversion from BODY back to KILL. It also adds several more named diversions, with the following subset designed for developer use.

PREPARE_TESTS

This diversion contains initialization sequences which are executed after `atconfig' and `atlocal', and after all command line arguments have been parsed, but prior to running any tests. It can be used to set up state that is required across all tests. This diversion will work even before AT_INIT.

For now, the named diversions of Autoconf and Autoheader, and the remaining diversions of Autotest, are not documented. In other words, intentionally outputting text into an undocumented diversion is subject to breakage in a future release of Autoconf.

Macro: m4_cleardivert (diversion…)

Permanently discard any text that has been diverted into diversion.

Macro: m4_divert_once (diversion, [content]@c)

Similar to m4_divert_text, except that content is only output to diversion if this is the first time that m4_divert_once has been called with its particular arguments.

Macro: m4_divert_pop ([diversion]@c)

If provided, check that the current diversion is indeed diversion. Then change to the diversion located earlier on the stack, giving an error if an attempt is made to pop beyond the initial m4sugar diversion of KILL.

Macro: m4_divert_push (diversion)

Remember the former diversion on the diversion stack, and output subsequent text into diversion. M4sugar maintains a diversion stack, and issues an error if there is not a matching pop for every push.

Macro: m4_divert_text (diversion, [content]@c)

Output content and a newline into diversion, without affecting the current diversion. Shorthand for:

 
m4_divert_push([diversion])content
m4_divert_pop([diversion])dnl
Macro: m4_init

Initialize the M4sugar environment, setting up the default named diversion to be KILL.


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

8.3.4 Conditional constructs

The following macros provide additional conditional constructs as convenience wrappers around m4_if.

Macro: m4_bmatch (string, regex-1, value-1,   [regex-2]@c, [value-2]@c, …, [default]@c)

The string string is repeatedly compared against a series of regex arguments; if a match is found, the expansion is the corresponding value, otherwise, the macro moves on to the next regex. If no regex match, then the result is the optional default, or nothing.

Macro: m4_bpatsubsts (string, regex-1, subst-1,   [regex-2]@c, [subst-2]@c, …)

The string string is altered by regex-1 and subst-1, as if by:

 
m4_bpatsubst([[string]], [regex], [subst])

The result of the substitution is then passed through the next set of regex and subst, and so forth. An empty subst implies deletion of any matched portions in the current string. Note that this macro over-quotes string; this behavior is intentional, so that the result of each step of the recursion remains as a quoted string. However, it means that anchors (`^' and `$' in the regex will line up with the extra quotations, and not the characters of the original string. The overquoting is removed after the final substitution.

Macro: m4_case (string, value-1, if-value-1,   [value-2]@c, [if-value-2]@c, …, [default]@c)

Test string against multiple value possibilities, resulting in the first if-value for a match, or in the optional default. This is shorthand for:

 
m4_if([string], [value-1], [if-value-1],
      [string], [value-2], [if-value-2], …,
      [default])
Macro: m4_cond (test-1, value-1, if-value-1,   [test-2]@c, [value-2]@c, [if-value-2]@c, …, [default]@c)

This macro was introduced in Autoconf 2.62. Similar to m4_if, except that each test is expanded only when it is encountered. This is useful for short-circuiting expensive tests; while m4_if requires all its strings to be expanded up front before doing comparisons, m4_cond only expands a test when all earlier tests have failed.

For an example, these two sequences give the same result, but in the case where `$1' does not contain a backslash, the m4_cond version only expands m4_index once, instead of five times, for faster computation if this is a common case for `$1'. Notice that every third argument is unquoted for m4_if, and quoted for m4_cond:

 
m4_if(m4_index([$1], [\]), [-1], [$2],
      m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
      m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
      m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
      m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
      [$2])
m4_cond([m4_index([$1], [\])], [-1], [$2],
        [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
        [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
        [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
        [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
        [$2])
Macro: m4_default (expr-1, expr-2)
Macro: m4_default_quoted (expr-1, expr-2)
Macro: m4_default_nblank (expr-1, [expr-2]@c)
Macro: m4_default_nblank_quoted (expr-1, [expr-2]@c)

If expr-1 contains text, use it. Otherwise, select expr-2. m4_default expands the result, while m4_default_quoted does not. Useful for providing a fixed default if the expression that results in expr-1 would otherwise be empty. The difference between m4_default and m4_default_nblank is whether an argument consisting of just blanks (space, tab, newline) is significant. When using the expanding versions, note that an argument may contain text but still expand to an empty string.

 
m4_define([active], [ACTIVE])dnl
m4_define([empty], [])dnl
m4_define([demo1], [m4_default([$1], [$2])])dnl
m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl
m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl
m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl
demo1([active], [default])
⇒ACTIVE
demo1([], [active])
⇒ACTIVE
demo1([empty], [text])
⇒
-demo1([ ], [active])-
⇒- -
demo2([active], [default])
⇒active
demo2([], [active])
⇒active
demo2([empty], [text])
⇒empty
-demo2([ ], [active])-
⇒- -
demo3([active], [default])
⇒ACTIVE
demo3([], [active])
⇒ACTIVE
demo3([empty], [text])
⇒
-demo3([ ], [active])-
⇒-ACTIVE-
demo4([active], [default])
⇒active
demo4([], [active])
⇒active
demo4([empty], [text])
⇒empty
-demo4([ ], [active])-
⇒-active-
Macro: m4_ifblank (cond, [if-blank]@c, [if-text]@c)
Macro: m4_ifnblank (cond, [if-text]@c, [if-blank]@c)

If cond is empty or consists only of blanks (space, tab, newline), then expand if-blank; otherwise, expand if-text. Two variants exist, in order to make it easier to select the correct logical sense when using only two parameters. Note that this is more efficient than the equivalent behavior of:

 
m4_ifval(m4_normalize([cond]), if-text, if-cond)
Macro: m4_ifndef (macro, if-not-defined, [if-defined]@c)

This is shorthand for:

 
m4_ifdef([macro], [if-defined], [if-not-defined])
Macro: m4_ifset (macro, [if-true]@c, [if-false]@c)

If macro is undefined, or is defined as the empty string, expand to if-false. Otherwise, expands to if-true. Similar to:

 
m4_ifval(m4_defn([macro]), [if-true], [if-false])

except that it is not an error if macro is undefined.

Macro: m4_ifval (cond, [if-true]@c, [if-false]@c)

Expands to if-true if cond is not empty, otherwise to if-false. This is shorthand for:

 
m4_if([cond], [], [if-true], [if-false])
Macro: m4_ifvaln (cond, [if-true]@c, [if-false]@c)

Similar to m4_ifval, except guarantee that a newline is present after any non-empty expansion. Often followed by dnl.

Macro: m4_n (text)

Expand to text, and add a newline if text is not empty. Often followed by dnl.


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

8.3.5 Looping constructs

The following macros are useful in implementing recursive algorithms in M4, including loop operations. An M4 list is formed by quoting a list of quoted elements; generally the lists are comma-separated, although m4_foreach_w is whitespace-separated. For example, the list `[[a], [b,c]]' contains two elements: `[a]' and `[b,c]'. It is common to see lists with unquoted elements when those elements are not likely to be macro names, as in `[fputc_unlocked, fgetc_unlocked]'.

Although not generally recommended, it is possible for quoted lists to have side effects; all side effects are expanded only once, and prior to visiting any list element. On the other hand, the fact that unquoted macros are expanded exactly once means that macros without side effects can be used to generate lists. For example,

 
m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i])
error-->hi
⇒123
m4_define([list], [[1], [2], [3]])
⇒
m4_foreach([i], [list], [i])
⇒123
Macro: m4_argn (n, [arg]

Extracts argument n (larger than 0) from the remaining arguments. If there are too few arguments, the empty string is used. For any n besides 1, this is more efficient than the similar `m4_car(m4_shiftn([n], [], [arg…]))'.

Macro: m4_car (arg…)

Expands to the quoted first arg. Can be used with m4_cdr to recursively iterate through a list. Generally, when using quoted lists of quoted elements, m4_car should be called without any extra quotes.

Macro: m4_cdr (arg…)

Expands to a quoted list of all but the first arg, or the empty string if there was only one argument. Generally, when using quoted lists of quoted elements, m4_cdr should be called without any extra quotes.

For example, this is a simple implementation of m4_map; note how each iteration checks for the end of recursion, then merely applies the first argument to the first element of the list, then repeats with the rest of the list. (The actual implementation in M4sugar is a bit more involved, to gain some speed and share code with m4_map_sep, and also to avoid expanding side effects in `$2' twice).

 
m4_define([m4_map], [m4_ifval([$2],
  [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl
m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]])
⇒ 1 2 a
Macro: m4_for (var, first, last, [step]@c,   expression)

Loop over the numeric values between first and last including bounds by increments of step. For each iteration, expand expression with the numeric value assigned to var. If step is omitted, it defaults to `1' or `-1' depending on the order of the limits. If given, step has to match this order. The number of iterations is determined independently from definition of var; iteration cannot be short-circuited or lengthened by modifying var from within expression.

Macro: m4_foreach (var, list, expression)

Loop over the comma-separated M4 list list, assigning each value to var, and expand expression. The following example outputs two lines:

 
m4_foreach([myvar], [[foo], [bar, baz]],
           [echo myvar
])dnl
⇒echo foo
⇒echo bar, baz

Note that for some forms of expression, it may be faster to use m4_map_args.

Macro: m4_foreach_w (var, list, expression)

Loop over the white-space-separated list list, assigning each value to var, and expand expression. If var is only referenced once in expression, it is more efficient to use m4_map_args_w.

The deprecated macro AC_FOREACH is an alias of m4_foreach_w.

Macro: m4_map (macro, list)
Macro: m4_mapall (macro, list)
Macro: m4_map_sep (macro, separator, list)
Macro: m4_mapall_sep (macro, separator, list)

Loop over the comma separated quoted list of argument descriptions in list, and invoke macro with the arguments. An argument description is in turn a comma-separated quoted list of quoted elements, suitable for m4_apply. The macros m4_map and m4_map_sep ignore empty argument descriptions, while m4_mapall and m4_mapall_sep invoke macro with no arguments. The macros m4_map_sep and m4_mapall_sep additionally expand separator between invocations of macro.

Note that separator is expanded, unlike in m4_join. When separating output with commas, this means that the map result can be used as a series of arguments, by using a single-quoted comma as separator, or as a single string, by using a double-quoted comma.

 
m4_map([m4_count], [])
⇒
m4_map([ m4_count], [[],
                     [[1]],
                     [[1], [2]]])
⇒ 1 2
m4_mapall([ m4_count], [[],
                        [[1]],
                        [[1], [2]]])
⇒ 0 1 2
m4_map_sep([m4_eval], [,], [[[1+2]],
                            [[10], [16]]])
⇒3,a
m4_map_sep([m4_echo], [,], [[[a]], [[b]]])
⇒a,b
m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]]))
⇒2
m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])
⇒a,b
m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]))
⇒1
Macro: m4_map_args (macro, arg…)

Repeatedly invoke macro with each successive arg as its only argument. In the following example, three solutions are presented with the same expansion; the solution using m4_map_args is the most efficient.

 
m4_define([active], [ACTIVE])dnl
m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))])
⇒ plain active
m4_map([ m4_echo], [[[plain]], [[active]]])
⇒ plain active
m4_map_args([ m4_echo], [plain], [active])
⇒ plain active

In cases where it is useful to operate on additional parameters besides the list elements, the macro m4_curry can be used in macro to supply the argument currying necessary to generate the desired argument list. In the following example, list_add_n is more efficient than list_add_x. On the other hand, using m4_map_args_sep can be even more efficient.

 
m4_define([list], [[1], [2], [3]])dnl
m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl
dnl list_add_n(N, ARG...)
dnl Output a list consisting of each ARG added to N
m4_define([list_add_n],
[m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@)))])dnl
list_add_n([1], list)
⇒2,3,4
list_add_n([2], list)
⇒3,4,5
m4_define([list_add_x],
[m4_shift(m4_foreach([var], m4_dquote(m4_shift($@)),
  [,add([$1],m4_defn([var]))]))])dnl
list_add_x([1], list)
⇒2,3,4
Macro: m4_map_args_pair (macro, [macro-end = `macro']@c,   arg…)

For every pair of arguments arg, invoke macro with two arguments. If there is an odd number of arguments, invoke macro-end, which defaults to macro, with the remaining argument.

 
m4_map_args_pair([, m4_reverse], [], [1], [2], [3])
⇒, 2, 1, 3
m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3])
⇒, 2, 1, [3]
m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4])
⇒, 2, 1, 4, 3
Macro: m4_map_args_sep ([pre]@c, [post]@c, [sep]@c, arg…)

Expand the sequence pre[arg]post for each argument, additionally expanding sep between arguments. One common use of this macro is constructing a macro call, where the opening and closing parentheses are split between pre and post; in particular, m4_map_args([macro], [arg]) is equivalent to m4_map_args_sep([macro(], [)], [], [arg]). This macro provides the most efficient means for iterating over an arbitrary list of arguments, particularly when repeatedly constructing a macro call with more arguments than arg.

Macro: m4_map_args_w (string, [pre]@c, [post]@c, [sep]@c)

Expand the sequence pre[word]post for each word in the whitespace-separated string, additionally expanding sep between words. This macro provides the most efficient means for iterating over a whitespace-separated string. In particular, m4_map_args_w([string], [action(], [)]) is more efficient than m4_foreach_w([var], [string], [action(m4_defn([var]))]).

Macro: m4_shiftn (count, …)
Macro: m4_shift2 (…)
Macro: m4_shift3 (…)

m4_shiftn performs count iterations of m4_shift, along with validation that enough arguments were passed in to match the shift count, and that the count is positive. m4_shift2 and m4_shift3 are specializations of m4_shiftn, introduced in Autoconf 2.62, and are more efficient for two and three shifts, respectively.

Macro: m4_stack_foreach (macro, action)
Macro: m4_stack_foreach_lifo (macro, action)

For each of the m4_pushdef definitions of macro, expand action with the single argument of a definition of macro. m4_stack_foreach starts with the oldest definition, while m4_stack_foreach_lifo starts with the current definition. action should not push or pop definitions of macro, nor is there any guarantee that the current definition of macro matches the argument that was passed to action. The macro m4_curry can be used if action needs more than one argument, although in that case it is more efficient to use m4_stack_foreach_sep.

Due to technical limitations, there are a few low-level m4sugar functions, such as m4_pushdef, that cannot be used as the macro argument.

 
m4_pushdef([a], [1])m4_pushdef([a], [2])dnl
m4_stack_foreach([a], [ m4_incr])
⇒ 2 3
m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])])
⇒ cd bcd
Macro: m4_stack_foreach_sep (macro, [pre]@c, [post]@c, [sep]@c)
Macro: m4_stack_foreach_sep_lifo (macro, [pre]@c, [post]@c,   [sep]@c)

Expand the sequence pre[definition]post for each m4_pushdef definition of macro, additionally expanding sep between definitions. m4_stack_foreach_sep visits the oldest definition first, while m4_stack_foreach_sep_lifo visits the current definition first. This macro provides the most efficient means for iterating over a pushdef stack. In particular, m4_stack_foreach([macro], [action]) is short for m4_stack_foreach_sep([macro], [action(], [)]).


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

8.3.6 Evaluation Macros

The following macros give some control over the order of the evaluation by adding or removing levels of quotes.

Macro: m4_apply (macro, list)

Apply the elements of the quoted, comma-separated list as the arguments to macro. If list is empty, invoke macro without arguments. Note the difference between m4_indir, which expects its first argument to be a macro name but can use names that are otherwise invalid, and m4_apply, where macro can contain other text, but must end in a valid macro name.

 
m4_apply([m4_count], [])
⇒0
m4_apply([m4_count], [[]])
⇒1
m4_apply([m4_count], [[1], [2]])
⇒2
m4_apply([m4_join], [[|], [1], [2]])
⇒1|2
Macro: m4_count (arg, …)

This macro returns the decimal count of the number of arguments it was passed.

Macro: m4_curry (macro, arg…)

This macro performs argument currying. The expansion of this macro is another macro name that expects exactly one argument; that argument is then appended to the arg list, and then macro is expanded with the resulting argument list.

 
m4_curry([m4_curry], [m4_reverse], [1])([2])([3])
⇒3, 2, 1

Unfortunately, due to a limitation in M4 1.4.x, it is not possible to pass the definition of a builtin macro as the argument to the output of m4_curry; the empty string is used instead of the builtin token. This behavior is rectified by using M4 1.6 or newer.

Macro: m4_do (arg, …)

This macro loops over its arguments and expands each arg in sequence. Its main use is for readability; it allows the use of indentation and fewer dnl to result in the same expansion. This macro guarantees that no expansion will be concatenated with subsequent text; to achieve full concatenation, use m4_unquote(m4_join([], arg…)).

 
m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl
m4_do([a],[b])c
⇒abc
m4_unquote(m4_join([],[a],[b]))c
⇒3
m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl
m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl
m4_do([a],[b])c
⇒ABC
m4_unquote(m4_join([],[a],[b]))c
⇒3
Macro: m4_dquote (arg, …)

Return the arguments as a quoted list of quoted arguments. Conveniently, if there is just one arg, this effectively adds a level of quoting.

Macro: m4_dquote_elt (arg, …)

Return the arguments as a series of double-quoted arguments. Whereas m4_dquote returns a single argument, m4_dquote_elt returns as many arguments as it was passed.

Macro: m4_echo (arg, …)

Return the arguments, with the same level of quoting. Other than discarding whitespace after unquoted commas, this macro is a no-op.

Macro: m4_expand (arg)

Return the expansion of arg as a quoted string. Whereas m4_quote is designed to collect expanded text into a single argument, m4_expand is designed to perform one level of expansion on quoted text. One distinction is in the treatment of whitespace following a comma in the original arg. Any time multiple arguments are collected into one with m4_quote, the M4 argument collection rules discard the whitespace. However, with m4_expand, whitespace is preserved, even after the expansion of macros contained in arg. Additionally, m4_expand is able to expand text that would involve an unterminated comment, whereas expanding that same text as the argument to m4_quote runs into difficulty in finding the end of the argument. Since manipulating diversions during argument collection is inherently unsafe, m4_expand issues an error if arg attempts to change the current diversion (see section Diversion support).

 
m4_define([active], [ACT, IVE])dnl
m4_define([active2], [[ACT, IVE]])dnl
m4_quote(active, active)
⇒ACT,IVE,ACT,IVE
m4_expand([active, active])
⇒ACT, IVE, ACT, IVE
m4_quote(active2, active2)
⇒ACT, IVE,ACT, IVE
m4_expand([active2, active2])
⇒ACT, IVE, ACT, IVE
m4_expand([# m4_echo])
⇒# m4_echo
m4_quote(# m4_echo)
)
⇒# m4_echo)
⇒

Note that m4_expand cannot handle an arg that expands to literal unbalanced quotes, but that quadrigraphs can be used when unbalanced output is necessary. Likewise, unbalanced parentheses should be supplied with double quoting or a quadrigraph.

 
m4_define([pattern], [[!@<:@]])dnl
m4_define([bar], [BAR])dnl
m4_expand([case $foo in
  m4_defn([pattern])@:}@ bar ;;
  *[)] blah ;;
esac])
⇒case $foo in
⇒  [![]) BAR ;;
⇒  *) blah ;;
⇒esac
Macro: m4_ignore (…)

This macro was introduced in Autoconf 2.62. Expands to nothing, ignoring all of its arguments. By itself, this isn't very useful. However, it can be used to conditionally ignore an arbitrary number of arguments, by deciding which macro name to apply to a list of arguments.

 
dnl foo outputs a message only if [debug] is defined.
m4_define([foo],
[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])

Note that for earlier versions of Autoconf, the macro __gnu__ can serve the same purpose, although it is less readable.

Macro: m4_make_list (arg, …)

This macro exists to aid debugging of M4sugar algorithms. Its net effect is similar to m4_dquote--it produces a quoted list of quoted arguments, for each arg. The difference is that this version uses a comma-newline separator instead of just comma, to improve readability of the list; with the result that it is less efficient than m4_dquote.

 
m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl
m4_dquote(zero, [one], [[two]])
⇒[0],[one],[[two]]
m4_make_list(zero, [one], [[two]])
⇒[0],
⇒[one],
⇒[[two]]
m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number])
⇒ 0 1 two
m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number])
⇒ 0 1 two
Macro: m4_quote (arg, …)

Return the arguments as a single entity, i.e., wrap them into a pair of quotes. This effectively collapses multiple arguments into one, although it loses whitespace after unquoted commas in the process.

Macro: m4_reverse (arg, …)

Outputs each argument with the same level of quoting, but in reverse order, and with space following each comma for readability.

 
m4_define([active], [ACT,IVE])
⇒
m4_reverse(active, [active])
⇒active, IVE, ACT
Macro: m4_unquote (arg, …)

This macro was introduced in Autoconf 2.62. Expand each argument, separated by commas. For a single arg, this effectively removes a layer of quoting, and m4_unquote([arg]) is more efficient than the equivalent m4_do([arg]). For multiple arguments, this results in an unquoted list of expansions. This is commonly used with m4_split, in order to convert a single quoted list into a series of quoted elements.

The following example aims at emphasizing the difference between several scenarios: not using these macros, using m4_defn, using m4_quote, using m4_dquote, and using m4_expand.

 
$ cat example.m4
dnl Overquote, so that quotes are visible.
m4_define([show], [$[]1 = [$1], $[]@ = [$@]])
m4_define([a], [A])
m4_define([mkargs], [1, 2[,] 3])
m4_define([arg1], [[$1]])
m4_divert([0])dnl
show(a, b)
show([a, b])
show(m4_quote(a, b))
show(m4_dquote(a, b))
show(m4_expand([a, b]))

arg1(mkargs)
arg1([mkargs])
arg1(m4_defn([mkargs]))
arg1(m4_quote(mkargs))
arg1(m4_dquote(mkargs))
arg1(m4_expand([mkargs]))
$ autom4te -l m4sugar example.m4
$1 = A, $@ = [A],[b]
$1 = a, b, $@ = [a, b]
$1 = A,b, $@ = [A,b]
$1 = [A],[b], $@ = [[A],[b]]
$1 = A, b, $@ = [A, b]

1
mkargs
1, 2[,] 3
1,2, 3
[1],[2, 3]
1, 2, 3

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

8.3.7 String manipulation in M4

The following macros may be used to manipulate strings in M4. Many of the macros in this section intentionally result in quoted strings as output, rather than subjecting the arguments to further expansions. As a result, if you are manipulating text that contains active M4 characters, the arguments are passed with single quoting rather than double.

Macro: m4_append (macro-name, string, [separator]@c)
Macro: m4_append_uniq (macro-name, string, [separator]

[if-uniq]@c, [if-duplicate]@c) Redefine macro-name to its former contents with separator and string added at the end. If macro-name was undefined before (but not if it was defined but empty), then no separator is added. As of Autoconf 2.62, neither string nor separator are expanded during this macro; instead, they are expanded when macro-name is invoked.

m4_append can be used to grow strings, and m4_append_uniq to grow strings without duplicating substrings. Additionally, m4_append_uniq takes two optional parameters as of Autoconf 2.62; if-uniq is expanded if string was appended, and if-duplicate is expanded if string was already present. Also, m4_append_uniq warns if separator is not empty, but occurs within string, since that can lead to duplicates.

Note that m4_append can scale linearly in the length of the final string, depending on the quality of the underlying M4 implementation, while m4_append_uniq has an inherent quadratic scaling factor. If an algorithm can tolerate duplicates in the final string, use the former for speed. If duplicates must be avoided, consider using m4_set_add instead (see section Set manipulation in M4).

 
m4_define([active], [ACTIVE])dnl
m4_append([sentence], [This is an])dnl
m4_append([sentence], [ active ])dnl
m4_append([sentence], [symbol.])dnl
sentence
⇒This is an ACTIVE symbol.
m4_undefine([active])dnl
⇒This is an active symbol.
m4_append_uniq([list], [one], [, ], [new], [existing])
⇒new
m4_append_uniq([list], [one], [, ], [new], [existing])
⇒existing
m4_append_uniq([list], [two], [, ], [new], [existing])
⇒new
m4_append_uniq([list], [three], [, ], [new], [existing])
⇒new
m4_append_uniq([list], [two], [, ], [new], [existing])
⇒existing
list
⇒one, two, three
m4_dquote(list)
⇒[one],[two],[three]
m4_append([list2], [one], [[, ]])dnl
m4_append_uniq([list2], [two], [[, ]])dnl
m4_append([list2], [three], [[, ]])dnl
list2
⇒one, two, three
m4_dquote(list2)
⇒[one, two, three]
Macro: m4_append_uniq_w (macro-name, strings)

This macro was introduced in Autoconf 2.62. It is similar to m4_append_uniq, but treats strings as a whitespace separated list of words to append, and only appends unique words. macro-name is updated with a single space between new words.

 
m4_append_uniq_w([numbers], [1 1 2])dnl
m4_append_uniq_w([numbers], [ 2 3 ])dnl
numbers
⇒1 2 3
Macro: m4_chomp (string)
Macro: m4_chomp_all (string)

Output string in quotes, but without a trailing newline. The macro m4_chomp is slightly faster, and removes at most one newline; the macro m4_chomp_all removes all consecutive trailing newlines. Unlike m4_flatten, embedded newlines are left intact, and backslash does not influence the result.

Macro: m4_combine ([separator]@c, prefix-list, [infix]@c,   suffix-1, [suffix-2]@c, …)

This macro produces a quoted string containing the pairwise combination of every element of the quoted, comma-separated prefix-list, and every element from the suffix arguments. Each pairwise combination is joined with infix in the middle, and successive pairs are joined by separator. No expansion occurs on any of the arguments. No output occurs if either the prefix or suffix list is empty, but the lists can contain empty elements.

 
m4_define([a], [oops])dnl
m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
⇒a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
m4_combine([, ], [[a], [b]], [-])
⇒
m4_combine([, ], [[a], [b]], [-], [])
⇒a-, b-
m4_combine([, ], [], [-], [1], [2])
⇒
m4_combine([, ], [[]], [-], [1], [2])
⇒-1, -2
Macro: m4_escape (string)

Convert all instances of `[', `]', `#', and `$' within string into their respective quadrigraphs. The result is still a quoted string.

Macro: m4_flatten (string)

Flatten string into a single line. Delete all backslash-newline pairs, and replace all remaining newlines with a space. The result is still a quoted string.

Macro: m4_join ([separator]@c, args…)
Macro: m4_joinall ([separator]@c, args…)

Concatenate each arg, separated by separator. joinall uses every argument, while join omits empty arguments so that there are no back-to-back separators in the output. The result is a quoted string.

 
m4_define([active], [ACTIVE])dnl
m4_join([|], [one], [], [active], [two])
⇒one|active|two
m4_joinall([|], [one], [], [active], [two])
⇒one||active|two

Note that if all you intend to do is join args with commas between them, to form a quoted list suitable for m4_foreach, it is more efficient to use m4_dquote.

Macro: m4_newline ([text]@c)

This macro was introduced in Autoconf 2.62, and expands to a newline, followed by any text. It is primarily useful for maintaining macro formatting, and ensuring that M4 does not discard leading whitespace during argument collection.

Macro: m4_normalize (string)

Remove leading and trailing spaces and tabs, sequences of backslash-then-newline, and replace multiple spaces, tabs, and newlines with a single space. This is a combination of m4_flatten and m4_strip. To determine if string consists only of bytes that would be removed by m4_normalize, you can use m4_ifblank.

Macro: m4_re_escape (string)

Backslash-escape all characters in string that are active in regexps.

Macro: m4_split (string, [regexp = `[t ]+']@c)

Split string into an M4 list of elements quoted by `[' and `]', while keeping white space at the beginning and at the end. If regexp is given, use it instead of `[\t ]+' for splitting. If string is empty, the result is an empty list.

Macro: m4_strip (string)

Strip whitespace from string. Sequences of spaces and tabs are reduced to a single space, then leading and trailing spaces are removed. The result is still a quoted string. Note that this does not interfere with newlines; if you want newlines stripped as well, consider m4_flatten, or do it all at once with m4_normalize. To quickly test if string has only whitespace, use m4_ifblank.

Macro: m4_text_box (message, [frame = `-']@c)

Add a text box around message, using frame as the border character above and below the message. The frame correctly accounts for the subsequent expansion of message. For example:

 
m4_define([macro], [abc])dnl
m4_text_box([macro])
⇒## --- ##
⇒## abc ##
⇒## --- ##

The message must contain balanced quotes and parentheses, although quadrigraphs can be used to work around this.

Macro: m4_text_wrap (string, [prefix]@c,   [prefix1 = `prefix']@c, [width = `79']@c)

Break string into a series of whitespace-separated words, then output those words separated by spaces, and wrapping lines any time the output would exceed width columns. If given, prefix1 begins the first line, and prefix begins all wrapped lines. If prefix1 is longer than prefix, then the first line consists of just prefix1. If prefix is longer than prefix1, padding is inserted so that the first word of string begins at the same indentation as all wrapped lines. Note that using literal tab characters in any of the arguments will interfere with the calculation of width. No expansions occur on prefix, prefix1, or the words of string, although quadrigraphs are recognized.

For some examples:

 
m4_text_wrap([Short string */], [   ], [/* ], [20])
⇒/* Short string */
m4_text_wrap([Much longer string */], [   ], [/* ], [20])
⇒/* Much longer
⇒   string */
m4_text_wrap([Short doc.], [          ], [  --short ], [30])
⇒  --short Short doc.
m4_text_wrap([Short doc.], [          ], [  --too-wide ], [30])
⇒  --too-wide
⇒          Short doc.
m4_text_wrap([Super long documentation.], [     ],
             [  --too-wide ], 30)
⇒  --too-wide
⇒     Super long
⇒     documentation.
Macro: m4_tolower (string)
Macro: m4_toupper (string)

Return string with letters converted to upper or lower case, respectively.


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

8.3.8 Arithmetic computation in M4

The following macros facilitate integer arithmetic operations. Where a parameter is documented as taking an arithmetic expression, you can use anything that can be parsed by m4_eval.

Macro: m4_cmp (expr-1, expr-2)

Compare the arithmetic expressions expr-1 and expr-2, and expand to `-1' if expr-1 is smaller, `0' if they are equal, and `1' if expr-1 is larger.

Macro: m4_list_cmp (list-1, list-2)

Compare the two M4 lists consisting of comma-separated arithmetic expressions, left to right. Expand to `-1' for the first element pairing where the value from list-1 is smaller, `1' where the value from list-2 is smaller, or `0' if both lists have the same values. If one list is shorter than the other, the remaining elements of the longer list are compared against zero.

 
m4_list_cmp([1, 0],       [1])
⇒0
m4_list_cmp([1, [1 * 0]], [1, 0])
⇒0
m4_list_cmp([1, 2],       [1, 0])
⇒1
m4_list_cmp([1, [1+1], 3],[1, 2])
⇒1
m4_list_cmp([1, 2, -3],   [1, 2])
⇒-1
m4_list_cmp([1, 0],       [1, 2])
⇒-1
m4_list_cmp([1],          [1, 2])
⇒-1
Macro: m4_max (arg, …)

This macro was introduced in Autoconf 2.62. Expand to the decimal value of the maximum arithmetic expression among all the arguments.

Macro: m4_min (arg, …)

This macro was introduced in Autoconf 2.62. Expand to the decimal value of the minimum arithmetic expression among all the arguments.

Macro: m4_sign (expr)

Expand to `-1' if the arithmetic expression expr is negative, `1' if it is positive, and `0' if it is zero.

Macro: m4_version_compare (version-1, version-2)

This macro was introduced in Autoconf 2.53, but had a number of usability limitations that were not lifted until Autoconf 2.62. Compare the version strings version-1 and version-2, and expand to `-1' if version-1 is smaller, `0' if they are the same, or `1' version-2 is smaller. Version strings must be a list of elements separated by `.', `,' or `-', where each element is a number along with optional case-insensitive letters designating beta releases. The comparison stops at the leftmost element that contains a difference, although a 0 element compares equal to a missing element.

It is permissible to include commit identifiers in version, such as an abbreviated SHA1 of the commit, provided there is still a monotonically increasing prefix to allow for accurate version-based comparisons. For example, this paragraph was written when the development snapshot of autoconf claimed to be at version `2.61a-248-dc51', or 248 commits after the 2.61a release, with an abbreviated commit identification of `dc51'.

 
m4_version_compare([1.1], [2.0])
⇒-1
m4_version_compare([2.0b], [2.0a])
⇒1
m4_version_compare([1.1.1], [1.1.1a])
⇒-1
m4_version_compare([1.2], [1.1.1a])
⇒1
m4_version_compare([1.0], [1])
⇒0
m4_version_compare([1.1pre], [1.1PRE])
⇒0
m4_version_compare([1.1a], [1,10])
⇒-1
m4_version_compare([2.61a], [2.61a-248-dc51])
⇒-1
m4_version_compare([2.61b], [2.61a-248-dc51])
⇒1
Macro: m4_version_prereq (version, [if-new-enough]@c,   [if-old = `m4_fatal']@c)

Compares version against the version of Autoconf currently running. If the running version is at version or newer, expand if-new-enough, but if version is larger than the version currently executing, expand if-old, which defaults to printing an error message and exiting m4sugar with status 63. When given only one argument, this behaves like AC_PREREQ (see section Dealing with Autoconf versions). Remember that the autoconf philosophy favors feature checks over version checks.


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

8.3.9 Set manipulation in M4

Sometimes, it is necessary to track a set of data, where the order does not matter and where there are no duplicates in the set. The following macros facilitate set manipulations. Each set is an opaque object, which can only be accessed via these basic operations. The underlying implementation guarantees linear scaling for set creation, which is more efficient than using the quadratic m4_append_uniq. Both set names and values can be arbitrary strings, except for unbalanced quotes. This implementation ties up memory for removed elements until the next operation that must traverse all the elements of a set; and although that may slow down some operations until the memory for removed elements is pruned, it still guarantees linear performance.

Macro: m4_set_add (set, value, [if-uniq]@c, [if-dup]@c)

Adds the string value as a member of set set. Expand if-uniq if the element was added, or if-dup if it was previously in the set. Operates in amortized constant time, so that set creation scales linearly.

Macro: m4_set_add_all (set, value…)

Adds each value to the set set. This is slightly more efficient than repeatedly invoking m4_set_add.

Macro: m4_set_contains (set, value, [if-present]@c,   [if-absent]@c)

Expands if-present if the string value is a member of set, otherwise if-absent.

 
m4_set_contains([a], [1], [yes], [no])
⇒no
m4_set_add([a], [1], [added], [dup])
⇒added
m4_set_add([a], [1], [added], [dup])
⇒dup
m4_set_contains([a], [1], [yes], [no])
⇒yes
m4_set_remove([a], [1], [removed], [missing])
⇒removed
m4_set_contains([a], [1], [yes], [no])
⇒no
m4_set_remove([a], [1], [removed], [missing])
⇒missing
Macro: m4_set_contents (set, [sep]@c)
Macro: m4_set_dump (set, [sep]@c)

Expands to a single string consisting of all the members of the set set, each separated by sep, which is not expanded. m4_set_contents leaves the elements in set but reclaims any memory occupied by removed elements, while m4_set_dump is a faster one-shot action that also deletes the set. No provision is made for disambiguating members that contain a non-empty sep as a substring; use m4_set_empty to distinguish between an empty set and the set containing only the empty string. The order of the output is unspecified; in the current implementation, part of the speed of m4_set_dump results from using a different output order than m4_set_contents. These macros scale linearly in the size of the set before memory pruning, and m4_set_contents([set], [sep]) is faster than m4_joinall([sep]m4_set_listc([set])).

 
m4_set_add_all([a], [1], [2], [3])
⇒
m4_set_contents([a], [-])
⇒1-2-3
m4_joinall([-]m4_set_listc([a]))
⇒1-2-3
m4_set_dump([a], [-])
⇒3-2-1
m4_set_contents([a])
⇒
m4_set_add([a], [])
⇒
m4_set_contents([a], [-])
⇒
Macro: m4_set_delete (set)

Delete all elements and memory associated with set. This is linear in the set size, and faster than removing one element at a time.

Macro: m4_set_difference (seta, setb)
Macro: m4_set_intersection (seta, setb)
Macro: m4_set_union (seta, setb)

Compute the relation between seta and setb, and output the result as a list of quoted arguments without duplicates and with a leading comma. Set difference selects the elements in seta but not setb, intersection selects only elements in both sets, and union selects elements in either set. These actions are linear in the sum of the set sizes. The leading comma is necessary to distinguish between no elements and the empty string as the only element.

 
m4_set_add_all([a], [1], [2], [3])
⇒
m4_set_add_all([b], [3], [], [4])
⇒
m4_set_difference([a], [b])
⇒,1,2
m4_set_difference([b], [a])
⇒,,4
m4_set_intersection([a], [b])
⇒,3
m4_set_union([a], [b])
⇒,1,2,3,,4
Macro: m4_set_empty (set, [if-empty]@c, [if-elements]@c)

Expand if-empty if the set set has no elements, otherwise expand if-elements. This macro operates in constant time. Using this macro can help disambiguate output from m4_set_contents or m4_set_list.

Macro: m4_set_foreach (set, variable, action)

For each element in the set set, expand action with the macro variable defined as the set element. Behavior is unspecified if action recursively lists the contents of set (although listing other sets is acceptable), or if it modifies the set in any way other than removing the element currently contained in variable. This macro is faster than the corresponding m4_foreach([variable], m4_indir([m4_dquote]m4_set_listc([set])), [action]), although m4_set_map might be faster still.

 
m4_set_add_all([a]m4_for([i], [1], [5], [], [,i]))
⇒
m4_set_contents([a])
⇒12345
m4_set_foreach([a], [i],
  [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])])
⇒24
m4_set_contents([a])
⇒135
Macro: m4_set_list (set)
Macro: m4_set_listc (set)

Produce a list of arguments, where each argument is a quoted element from the set set. The variant m4_set_listc is unambiguous, by adding a leading comma if there are any set elements, whereas the variant m4_set_list cannot distinguish between an empty set and a set containing only the empty string. These can be directly used in macros that take multiple arguments, such as m4_join or m4_set_add_all, or wrapped by m4_dquote for macros that take a quoted list, such as m4_map or m4_foreach. Any memory occupied by removed elements is reclaimed during these macros.

 
m4_set_add_all([a], [1], [2], [3])
⇒
m4_set_list([a])
⇒1,2,3
m4_set_list([b])
⇒
m4_set_listc([b])
⇒
m4_count(m4_set_list([b]))
⇒1
m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
⇒0
m4_set_add([b], [])
⇒
m4_set_list([b])
⇒
m4_set_listc([b])
⇒,
m4_count(m4_set_list([b]))
⇒1
m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
⇒1
Macro: m4_set_map (set, action)

For each element in the set set, expand action with a single argument of the set element. Behavior is unspecified if action recursively lists the contents of set (although listing other sets is acceptable), or if it modifies the set in any way other than removing the element passed as an argument. This macro is faster than either corresponding counterpart of m4_map_args([action]m4_set_listc([set])) or m4_set_foreach([set], [var], [action(m4_defn([var]))]). It is possible to use m4_curry if more than one argument is needed for action, although it is more efficient to use m4_set_map_sep in that case.

Macro: m4_set_map_sep (set, [pre]@c, [post]@c, [sep]@c)

For each element in the set set, expand pre[element]post, additionally expanding sep between elements. Behavior is unspecified if the expansion recursively lists the contents of set (although listing other sets is acceptable), or if it modifies the set in any way other than removing the element visited by the expansion. This macro provides the most efficient means for non-destructively visiting the elements of a set; in particular, m4_set_map([set], [action]) is equivalent to m4_set_map_sep([set], [action(], [)]).

Macro: m4_set_remove (set, value, [if-present]@c,   [if-absent]@c)

If value is an element in the set set, then remove it and expand if-present. Otherwise expand if-absent. This macro operates in constant time so that multiple removals will scale linearly rather than quadratically; but when used outside of m4_set_foreach or m4_set_map, it leaves memory occupied until the set is later compacted by m4_set_contents or m4_set_list. Several other set operations are then less efficient between the time of element removal and subsequent memory compaction, but still maintain their guaranteed scaling performance.

Macro: m4_set_size (set)

Expand to the size of the set set. This implementation operates in constant time, and is thus more efficient than m4_eval(m4_count(m4_set_listc([set])) - 1).


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

8.3.10 Forbidden Patterns

M4sugar provides a means to define suspicious patterns, patterns describing tokens which should not be found in the output. For instance, if an Autoconf `configure' script includes tokens such as `AC_DEFINE', or `dnl', then most probably something went wrong (typically a macro was not evaluated because of overquotation).

M4sugar forbids all the tokens matching `^_?m4_' and `^dnl$'. Additional layers, such as M4sh and Autoconf, add additional forbidden patterns to the list.

Macro: m4_pattern_forbid (pattern)

Declare that no token matching pattern must be found in the output. Comments are not checked; this can be a problem if, for instance, you have some macro left unexpanded after an `#include'. No consensus is currently found in the Autoconf community, as some people consider it should be valid to name macros in comments (which doesn't make sense to the authors of this documentation: input, such as macros, should be documented by `dnl' comments; reserving `#'-comments to document the output).

Of course, you might encounter exceptions to these generic rules, for instance you might have to refer to `$m4_flags'.

Macro: m4_pattern_allow (pattern)

Any token matching pattern is allowed, including if it matches an m4_pattern_forbid pattern.


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

8.4 Debugging via autom4te

At times, it is desirable to see what was happening inside m4, to see why output was not matching expectations. However, post-processing done by autom4te means that directly using the m4 builtin m4_traceon is likely to interfere with operation. Also, frequent diversion changes and the concept of forbidden tokens make it difficult to use m4_defn to generate inline comments in the final output.

There are a couple of tools to help with this. One is the use of the `--trace' option provided by autom4te (as well as each of the programs that wrap autom4te, such as autoconf), in order to inspect when a macro is called and with which arguments. For example, when this paragraph was written, the autoconf version could be found by:

 
$ autoconf --trace=AC_INIT
configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@gnu.org
$ autoconf --trace='AC_INIT:version is $2'
version is 2.63b.95-3963

Another trick is to print out the expansion of various m4 expressions to standard error or to an independent file, with no further m4 expansion, and without interfering with diversion changes or the post-processing done to standard output. m4_errprintn shows a given expression on standard error. For example, if you want to see the expansion of an autoconf primitive or of one of your autoconf macros, you can do it like this:

 
$ cat <<\EOF > configure.ac
AC_INIT
m4_errprintn([The definition of AC_DEFINE_UNQUOTED:])
m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED]))
AC_OUTPUT
EOF
$ autoconf
error-->The definition of AC_DEFINE_UNQUOTED:
error-->_AC_DEFINE_Q([], $@)

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

This document was generated on January, 20 2010 using texi2html 1.76.