X macro

X macros are an idiomatic usage of programming language macros for generating list-like structures of data or code. They are most useful when at least some of the lists cannot be composed by indexing, such as compile time. They provide reliable maintenance of parallel lists whose corresponding items must be declared or executed in the same order.

Examples of such lists particularly include initialization of arrays, in concert with declarations of enumeration constants and function prototypes; generation of statement sequences and switch arms; etc.

Usage of X macros dates back to the 1960s. It remains useful in modern-day C and C++ programming languages, but remains relatively unknown.

Implementation
An X macro application consists of two parts:


 * 1) The definition of the list's elements.
 * 2) Expansion(s) of the list to generate fragments of declarations or statements.

The list is defined by a macro or header file (named, ) which generates no code by itself, but merely consists of a sequence of invocations of a macro (classically named " ") with the elements' data. Each expansion of  is preceded by a definition of   with the syntax for a list element. The invocation of  expands   for each element in the list.

Example 1
This example defines a list of variables, and automatically generates their declarations and a function to print them out.

First the list definition. The list entries could contain multiple arguments, but here only the name of the variable is used.

Then we expand this list to generate the variable declarations:

In a similar way, we can generate a function that prints the variables and their values:

When run through the C preprocessor, the following code is generated. Line breaks and indentation have been added for ease of reading, even though they are not actually generated by the preprocessor:

Example 2 with X macro as argument
This example aims to improve the readability of the X macro usage by:


 * 1) Prefix the name of the macro that defines the list with "FOR_".
 * 2) Pass name of the worker macro into the list macro. This both avoids defining an obscurely named macro (X), and alleviates the need to undefine it.
 * 3) Use the syntax for variadic macro arguments "..." in the worker macros to be able to accept more arguments than needed. This enables the maintainer of the code to add columns to the list without having to update all the macro definitions.
 * 4) Use the name "DO" as the macro name, the argument to the list macro.

As above, execute this list to generate the variable declarations:

or declare an enumeration:

In a similar way, we can generate a function that prints the variables and their names: