101 lines
4.0 KiB
Plaintext
101 lines
4.0 KiB
Plaintext
[/
|
|
(C) Copyright Edward Diener 2011-2017
|
|
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.
|
|
|
|
The preprocessor data types with which VMD has specific functionality
|
|
are emptiness, identifiers, numbers ( a subset of identifiers ),
|
|
types ( a subset of identifiers ), Boost PP arrays,
|
|
Boost PP lists, Boost PP seqs, Boost PP tuples,
|
|
and sequences. The first four are basic preprocessor data types
|
|
while the latter five are composite preprocessor data types. A
|
|
sequence is zero or more of the other preprocessor data types
|
|
following each other.
|
|
|
|
[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))]]
|
|
]
|
|
|
|
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 could accept
|
|
nothing when invoked, such as in:
|
|
|
|
RETURN_NOTHING()
|
|
|
|
Finally emptiness can be part of any composite data type as in:
|
|
|
|
(45,,some_name)
|
|
|
|
where the second tuple element is empty.
|
|
|
|
[heading What is the advantage ?]
|
|
|
|
VMD can identify any of the preprocessor data types previously mentioned,
|
|
and can parse sequences into their individual preprocessor data types.
|
|
You may well ask why that is important.
|
|
|
|
In Boost PP macro programming a great deal of the control logic of
|
|
designing a macro is based on the support Boost PP has for numbers
|
|
and testing for the value of a number, in particular 0 and 1 to represent
|
|
boolean choices. Essentially Boost PP often uses the value of a number to
|
|
control the logic in a macro's design.
|
|
|
|
VMD does not attempt, in any way, to duplicate Boost PP's support for
|
|
testing the value of numbers or of the boolean 0 or 1 values, but just
|
|
reuses that functionality. What VMD offers, which goes beyond Boost PP,
|
|
is a system for deciphering the preprocessor data types, as well as
|
|
comparing any of the preprocessor data types for equality to any given
|
|
value. 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 identifiers, numbers, types, tuples, arrays, lists, and seqs.
|
|
# Provide ways for testing/parsing sequences of identifiers, numbers, types, tuples, arrays, lists. and seqs.
|
|
# Provide some useful variadic 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]
|