Chapter 1. The Variadic Macro Data Library 1.10

The Variadic Macro Data library, referred to hereafter as VMD for short, is a library of variadic macros which provide enhancements to the functionality in the Boost preprocessor library ( Boost PP ), especially as it relates to preprocessor data types.

In the Boost PP library the preprocessor data types which have specific functionality are numbers ( values between 0 and BOOST_PP_LIMIT_MAG) and the composite data types Boost PP arrays, Boost PP lists, Boost PP seqs, and Boost PP tuples.

The preprocessor data types with which VMD has specific functionality are the same data types as the Boost PP library as well as these other preprocessor data types: emptiness, VMD identifiers, VMD types ( a subset of identifiers ), and VMD sequences, which is another composite data type. A sequence is zero or more of any of the other preprocessor data types, other than emptiness, which have been previously mentioned and supported by the VMD library, sequentially following each other.

The VMD library does not replicate in any way the functionality of the Boost PP data types, but does extend some of that functionality in various ways, along with also providing specific functionality for emptiness, VMD identifiers, VMD types, and VMD sequences.

Data type examples

Table 1.1. Data types with examples

Type	Example
identifier	anyname
number	47
type	BOOST_VMD_TYPE_NUMBER
array	(4,(an_identifier,156,BOOST_VMD_TYPE_IDENTIFIER))
list	(78,(some_identifier,(BOOST_VMD_TYPE_TYPE,BOOST_PP_NIL)))
seq	(identifier)(89)(245)
tuple	(any_id,175,BOOST_VMD_TYPE_LIST,happy,21)
sequence	tree 59 (56,BOOST_VMD_TYPE_SEQ) (128)(fire)(clown) (47,(BOOST_VMD_TYPE_TUPLE,BOOST_PP_NIL))

Emptiness

Often we speak of a macro expanding to nothing or being passed nothing as an argument. Instead of the term "nothing", which can mean many things in general in C++ programming terms, we will call this facility of the preprocessor "emptiness".

Emptiness is the lack of any preprocessing tokens. A macro which expands to nothing, as in:

#define RETURN_NOTHING(x)

is said to return emptiness. Conversely a macro which could accept nothing when invoked, such as in:

RETURN_NOTHING()

is said to accept emptiness, or no preprocxessing tokens.

Finally emptiness can be part of any composite data type as in:

(45,,some_name)

where the second Boost PP tuple element is empty.

What is the advantage to using the VMD library ?

In the Boost PP library a good deal of functionality centers upon manipulating Boost PP numbers, and particularly the Boost PP numbers of 0 and 1 as a boolean value on which you can use Boost PP preprocessing logic to take different preprocessing paths when writing a macro. In other words when using Boost PP the logic of a macro is often based on the value of a Boost PP number. This is because Boost PP numbers can be compared to each other for equality or inequality, among other types of comparison, and Boost PP macros which use this ability to compare Boost PP numbers, such as the Boost PP macros BOOST_PP_IF or BOOST_PP_IIF, can choose different macro expansion paths based on the results of such a comparison.

The Boost VMD library adds to the comparison of Boost PP numbers the ability to compare any of its other data types for equality or inequality, therefore allowing the logic of a macro to depend on the value of any of the preprocessor data types it supports.

Even more signficantly the Boost VMD library has the ability to discover the type of preprocessing data if that data is one of the data types the VMD library supports, which gives the end-user not only the ability to change the macro expansion logic based on the value of a supported data type but also based on the actual type of preprocessing data.

The ability to determining macro expansion based on the type of a macro argument allows the macro programmer to create a single macro which expands differently based on the type of preprocessing data of one or more of its arguments, as well as the value of an argument of a particular type. This allows macro logic to be designed in a more flexible way, relying on the type of data and/or the value of the data. If this intrigues you, continue reading to understand how you can use VMD to do macro programming.

Functionality areas

The functionality of the library may be summed up as:

Provide a better way of testing for and using empty parameters and empty preprocessor data.
Provide ways for testing/parsing for VMD identifiers, Boost PP numbers, VMD types, Boost PP tuples, Boost PP arrays, Boost PP lists, and Boost PP seqs.
Provide ways for testing/parsing VMD sequences of VMD identifiers, Boost PP numbers, VMD types, Boost PP tuples, Boost PP arrays, Boost PP lists, and Boost PP seqs.
Provide some useful variadic only macros not in Boost PP.

The library is a header only library and all macros in the library are included by a single header, whose name is 'vmd.hpp'. Individual headers may be used for different functionality in the library and will be denoted when that functionality is explained.

All the macros in the library begin with the sequence 'BOOST_VMD_' to distinguish them from other macros the end-user might use. Therefore the end-user should not use any C++ identifiers, whether in macros or otherwise, which being with the sequence 'BOOST_VMD_'.

Use of the library is only dependent on Boost PP. The library also uses Boost detail lightweight_test.hpp for its own tests.

Boost C++ Libraries