123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100 |
- [/
- (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]
|