1[/ 2 (C) Copyright Edward Diener 2011-2017,2020 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8[section:vmd_intro Introduction] 9 10Welcome to the Variadic Macro Data library. 11 12The Variadic Macro Data library, referred to hereafter as VMD for 13short, is a library of variadic macros which provide enhancements 14to the functionality in the Boost preprocessor library ( Boost PP ), 15especially as it relates to preprocessor data types. 16 17In the Boost PP library the preprocessor data types which have 18specific functionality are numbers ( values between 0 and 256) 19and the composite data types Boost PP arrays, Boost PP lists, 20Boost PP seqs, and Boost PP tuples. 21 22The preprocessor data types with which VMD has specific functionality 23are the same data types as the Boost PP library as well as these other 24preprocessor data types: emptiness, VMD identifiers, 25VMD types ( a subset of identifiers ), and VMD sequences, which is another 26composite data type. A sequence is zero or more of any of the other 27preprocessor data types, other than emptiness, which have been 28previously mentioned asd supported by the VMD library, sequentially 29following each other. 30 31The VMD library does not replicate in any way the functionality 32of the Boost PP data types, but does extend some of that functionality 33in various ways, along with also providing specific functionality for 34emptiness, VMD identifiers, VMD types, and VMD sequences. 35 36[heading Data type examples] 37 38[table:dwe Data types with examples 39[[Type] [Example]] 40[[identifier] [anyname]] 41[[number] [47]] 42[[type] [BOOST_VMD_TYPE_NUMBER]] 43[[array] [(4,(an_identifier,156,BOOST_VMD_TYPE_IDENTIFIER))]] 44[[list] [(78,(some_identifier,(BOOST_VMD_TYPE_TYPE,BOOST_PP_NIL)))]] 45[[seq] [(identifier)(89)(245)]] 46[[tuple] [(any_id,175,BOOST_VMD_TYPE_LIST,happy,21)]] 47[[sequence] [tree 59 (56,BOOST_VMD_TYPE_SEQ) (128)(fire)(clown) (47,(BOOST_VMD_TYPE_TUPLE,BOOST_PP_NIL))]] 48] 49 50[heading Emptiness] 51 52Often we speak of a macro expanding to nothing or being passed nothing 53as an argument. Instead of the term "nothing", which can mean 54many things in general in C++ programming terms, we will call 55this facility of the preprocessor "emptiness". 56 57Emptiness is the lack of any preprocessing tokens. A macro which 58expands to nothing, as in: 59 60 #define RETURN_NOTHING(x) 61 62is said to return emptiness. Conversely a macro which could accept 63nothing when invoked, such as in: 64 65 RETURN_NOTHING() 66 67is said to accept emptiness, or no preprocxessing tokens. 68 69Finally emptiness can be part of any composite data type as in: 70 71 (45,,some_name) 72 73where the second Boost PP tuple element is empty. 74 75[heading What is the advantage to using the VMD library ?] 76 77In the Boost PP library a good deal of functionality centers upon 78manipulating Boost PP numbers, and particularly the Boost PP numbers 79of 0 and 1 as a boolean value on which you can use Boost PP 80preprocessing logic to take different preprocessing paths when 81writing a macro. In other words when using Boost PP the logic of a macro 82is often based on the value of a Boost PP number. This is because 83Boost PP numbers can be compared to each other for equality or 84inequality, among other types of comparison, and Boost PP macros 85which use this ability to compare Boost PP numbers, such as the 86Boost PP macros BOOST_PP_IF or BOOST_PP_IIF, can choose different 87macro expansion paths based on the results of such a comparison. 88 89The Boost VMD library adds to the comparison of Boost PP numbers the 90ability to compare any of its other data types for equality or inequality, 91therefore allowing the logic of a macro to depend on the value of any of 92the preprocessor data types it supports. 93 94Even more signficantly the Boost VMD library has the ability to 95discover the type of preprocessing data if that data is one of the 96data types the VMD library supports, which gives the end-user not 97only the ability to change the macro expansion logic based on the value 98of a supported data type but also based on the actual type of preprocessing 99data. 100 101The ability to determining macro expansion based on the type of a macro 102argument allows the macro programmer to create a single macro which expands 103differently based on the type of preprocessing data of one or more of its 104arguments, as well as the value of an argument of a particular type. 105This allows macro logic to be designed in a more flexible way, 106relying on the type of data and/or the value of the data. If this intrigues 107you, continue reading to understand how you can use VMD to do macro programming. 108 109[heading Functionality areas] 110 111The functionality of the library may be summed up as: 112 113# Provide a better way of testing for and using empty parameters and empty preprocessor data. 114# 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. 115# 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. 116# Provide some useful variadic only macros not in Boost PP. 117 118The library is a header only library and all macros in the 119library are included by a single header, whose name is 'vmd.hpp'. 120Individual headers may be used for different functionality 121in the library and will be denoted when that functionality is 122explained. 123 124All the macros in the library begin with the sequence 'BOOST_VMD_' 125to distinguish them from other macros the end-user might use. Therefore 126the end-user should not use any C++ identifiers, whether in macros or 127otherwise, which being with the sequence 'BOOST_VMD_'. 128 129Use of the library is only dependent on Boost PP. The library also 130uses Boost detail lightweight_test.hpp for its own tests. 131 132[endsect] 133