EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/vmd/doc/vmd_introduction.qbk

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