133 lines
5.7 KiB
Plaintext
133 lines
5.7 KiB
Plaintext
[/
|
|
(C) Copyright Edward Diener 2011-2017,2020
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt).
|
|
]
|
|
|
|
[section:vmd_intro Introduction]
|
|
|
|
Welcome to the Variadic Macro Data library.
|
|
|
|
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.
|
|
|
|
[heading Data type examples]
|
|
|
|
[table:dwe 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))]]
|
|
]
|
|
|
|
[heading 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.
|
|
|
|
[heading 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.
|
|
|
|
[heading 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.
|
|
|
|
[endsect]
|