ceph/src/boost/libs/vmd/doc/vmd_whyhow.qbk

   1 [/
   2   (C) Copyright Edward Diener 2011-2015
   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_whyhow Why and how to use]
   9
  10 The VMD library provides the ability to create a macro which takes
  11 different types of parameters and can therefore generate different output
  12 depending on the parameter types as well as their values.
  13
  14 This is equivalent to the way that overloaded
  15 functions provide the ability for a singularly named function
  16 to provide different functionality depending on the parameter
  17 types.
  18
  19 In the case of macros, where more than one macro of the same
  20 name but different macro expansion is not allowed, a single macro name
  21 can create different expansions.
  22
  23 As a simple example:
  24
  25  #include <boost/vmd/is_seq.hpp>
  26  #include <boost/vmd/is_tuple.hpp>
  27
  28  #define AMACRO(param)                 \
  29    BOOST_PP_IIF                        \
  30      (                                 \
  31      BOOST_VMD_IS_SEQ(param),          \
  32      Seq,                              \
  33      BOOST_PP_IIF                      \
  34        (                               \
  35        BOOST_VMD_IS_TUPLE(param),      \
  36        Tuple,                          \
  37        Unknown                         \
  38        )                               \
  39      )
  40
  41 If the param passed is a seq the output of
  42 the macro is 'Seq'. If the param passed is
  43 a tuple the output of the macro is 'Tuple'.
  44 Otherwise the output of the macro is 'Unknown'.
  45
  46 Obviously much more complicated cases can be created
  47 in which the types and values of various parameters
  48 are parsed in order to produce variable macro output
  49 depending on the input. Using variadic macros,
  50 macros with variable numbers and types of arguments
  51 give the macro programmer even greater freedom to
  52 design macros with flexibility.
  53
  54 Another feature of the VMD library is the ability to parse
  55 identifiers. A system of registering identifiers which VMD
  56 can recognize has been created. Once an identifier is registered
  57 VMD can recognize it as part of macro input as an identifier and
  58 return the identifier. Furthermore VMD can compare identifiers
  59 for equality or inequality once an identifier has been pre-detected
  60 using VMD's system for pre-detecting identifiers.
  61
  62 As another simple example:
  63
  64  #include <boost/vmd/is_identifier.hpp>
  65
  66  #define BOOST_VMD_REGISTER_NAME (NAME)
  67  #define BOOST_VMD_REGISTER_ADDRESS (ADDRESS)
  68
  69  #define AMACRO1(param)              \
  70    BOOST_PP_IIF                      \
  71      (                               \
  72      BOOST_VMD_IS_IDENTIFIER(param), \
  73      AMACRO1_IDENTIFIER,             \
  74      AMACRO1_NO_IDENTIFIER           \
  75      )                               \
  76    (param)
  77
  78  #define AMACRO1_IDENTIFIER(param) AMACRO1_ ## param
  79  #define AMACRO1_NO_IDENTIFIER(param) Parameter is not an identifier
  80  #define AMACRO1_NAME Identifier is a NAME
  81  #define AMACRO1_ADDRESS Identifier is an ADDRESS
  82
  83 Here we use VMD's identifier registration system to determine and
  84 handle a particular identifier we may be expecting as a macro parameter.
  85 If the input to 'AMACRO1' is 'NAME' the output is 'Identifier is a NAME'.
  86 If the input to 'AMACRO1' is 'ADDRESS' the output is 'Identifier is an ADDRESS'.
  87 Otherwise the output is 'Parameter is not an identifier'.
  88
  89 Identifier pre-detection makes things clearer, allowing us to
  90 detect within VMD whether macro input matches a particular identifier.
  91 Using the same setup as our previous example, but with identifier pre-detection:
  92
  93  #include <boost/vmd/is_identifier.hpp>
  94
  95  #define BOOST_VMD_REGISTER_NAME (NAME)
  96  #define BOOST_VMD_DETECT_NAME_NAME
  97
  98  #define BOOST_VMD_REGISTER_ADDRESS (ADDRESS)
  99  #define BOOST_VMD_DETECT_ADDRESS_ADDRESS
 100
 101  #define AMACRO2(param)                        \
 102    BOOST_PP_IIF                                \
 103      (                                         \
 104      BOOST_VMD_IS_IDENTIFIER(param,NAME),      \
 105      AMACRO2_NAME,                             \
 106      BOOST_PP_IIF                              \
 107        (                                       \
 108        BOOST_VMD_IS_IDENTIFIER(param,ADDRESS), \
 109        AMACRO2_ADDRESS,                        \
 110        AMACRO2_NO_IDENTIFIER                   \
 111        )                                       \
 112      )                                         \
 113    (param)
 114
 115  #define AMACRO2_NO_IDENTIFIER(param) Parameter is not a NAME or ADDRESS identifier
 116  #define AMACRO2_NAME(param) Identifier is a NAME
 117  #define AMACRO2_ADDRESS(param) Identifier is an ADDRESS
 118
 119 If the input to 'AMACRO2' is 'NAME' the output is 'Identifier is a NAME'.
 120 If the input to 'AMACRO2' is 'ADDRESS' the output is 'Identifier is an ADDRESS'.
 121 Otherwise the output is 'Parameter is not a NAME or ADDRESS identifier'.
 122
 123 The VMD library also has 2 different subtypes of identifiers which can always be
 124 recognized. The first are numbers, equivalent to the number in Boost PP, numeric
 125 values with a range of 0-256. The second are v-types, which are identifiers starting
 126 with BOOST_VMD_TYPE_ followed by a name for the type of data. As an example, the v-type
 127 of a Boost PP tuple is BOOST_VMD_TYPE_TUPLE and the v-type of a v-type itself is
 128 BOOST_VMD_TYPE_TYPE. All data types have their own v-type identifier; types are
 129 recognized by the VMD macros and may be passed as input data just like any other of
 130 the types of data VMD recognizes.
 131
 132 The VMD identifier system even has a way, to be explained later, for the end-user to
 133 create his own subtype identifiers.
 134
 135 Another reason to use VMD is that VMD understands 'sequences' of the VMD data types. You
 136 can have a sequence of data types and VMD can convert the sequence to any of the Boost
 137 PP data types, or access any individual data type in a sequence.
 138
 139  #include <boost/vmd/elem.hpp>
 140  #include <boost/vmd/to_tuple.hpp>
 141
 142  #define BOOST_VMD_REGISTER_NAME (NAME)
 143  #define ASEQUENCE (1,2) NAME 147 BOOST_VMD_TYPE_NUMBER (a)(b)
 144
 145  BOOST_VMD_TO_TUPLE(ASEQUENCE)
 146  BOOST_VMD_ELEM(2,ASEQUENCE)
 147
 148 Our first expansion returns the tuple:
 149
 150  ((1,2),NAME,147,BOOST_VMD_TYPE_NUMBER,(a)(b))
 151
 152 Our second expansion returns the sequence element:
 153
 154  147
 155
 156 Sequences give the macro programmer the ability to accept input
 157 data from the user which may more closely mimic C++ constructs.
 158
 159 Another reason to use VMD is that VMD understands data types.
 160 Besides specifically asking if a particular input is a particular
 161 data type, you can use the macro BOOST_VMD_GET_TYPE to retrieve
 162 the type of any VMD data.
 163
 164  #include <boost/vmd/get_type.hpp>
 165
 166  BOOST_VMD_GET_TYPE((1,2)) // expands to BOOST_VMD_TYPE_TUPLE
 167  BOOST_VMD_GET_TYPE(235)   // expands to BOOST_VMD_TYPE_NUMBER
 168
 169 etc.
 170
 171 There is still much more of VMD functionality but hopefully this brief
 172 introduction of what VMD can do will interest you so that you will read on
 173 to understand VMD's functionality for the macro programmer.
 174
 175 [endsect]