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