ceph/src/boost/libs/vmd/doc/vmd_data_types.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_data_types Data types]
   9
  10 The VMD library has functionality for testing and parsing preprocessor data.
  11
  12 The C++ preprocessor defines preprocessor data as preprocessing tokens.
  13 The types of preprocessing tokens can be seen in section 2.5 of the C++ standard document.
  14
  15 The VMD library works with a subset of two of these types of preprocessor tokens
  16 as "data types". These are the "identifier" and "pp-number" preprocessor tokens.
  17 The preprocessor token types which VMD cannot parse are:
  18
  19 * header-name
  20 * character-literal
  21 * user-defined-characteral-literal
  22 * string-literal
  23 * user-defined-string-literal
  24 * preprocessing-op-or-punc
  25
  26 Even though VMD cannot parse these preprocessor token types, it is still
  27 a very useful library since a large part of macro programming works with
  28 'identifier' and 'pp-number' tokens.
  29
  30 VMD identifiers are preprocessing tokens consisting
  31 of alphanumeric characters and the underscore ( _ ) character. This is very similar to a
  32 preprocessor token "identifier" with the difference being that a VMD identifier can start with a
  33 numeric character, allowing VMD identifiers to also be positive integral literals. VMD offers
  34 functionality for parsing VMD identifiers both as a separate element or in a sequence of preprocessing
  35 tokens.
  36
  37 VMD numbers are Boost PP numbers, ie. preprocessing tokens of
  38 whole numbers between 0 and 256 inclusive. These are a small subset of preprocessor token
  39 "pp-number". VMD offers functionality for parsing numbers both as a separate element or
  40 in a sequence of preprocessing tokens. A VMD number is really a subset of VMD identifiers
  41 for which VMD offers specific functionality. The Boost PP library has it own extensive support
  42 for numbers, which VMD does not duplicate.
  43
  44 VMD v-types are, like numbers, a subset of VMD identifiers consisting of identifiers beginning with
  45 BOOST_VMD_TYPE_ followed by a data type mnemonic. Each v-type can be recognized by VMD functionality
  46 and therefore passed or returned by macros. Like any identifier a v-type can be parsed both as a
  47 separate element or in a sequence of preprocessing tokens.
  48
  49 VMD can also test for emptiness, or the absence of any preprocessing tokens when passed
  50 as macro input.
  51
  52 The Boost PP library supports four individual high-level data types. These are arrays,
  53 lists, seqs, and tuples. When using variadic macros arrays are really
  54 obsolete since tuples have all the functionality of arrays with a simpler syntax.
  55 Nonetheless arrays are fully supported by VMD. A further data type supported by
  56 Boost PP is variadic data, which is a comma separated grouping of preprocessor elements.
  57 VMD has no special support for variadic data outside of what is already in Boost PP.
  58
  59 VMD has functionality to work with the four Boost PP high-level data types. VMD can
  60 test the Boost PP data types and parse them in a sequence of preprocessor tokens.
  61
  62 VMD can also parse sequences. A sequence consists of zero or more other top-level
  63 data types already mentioned represented consecutively. As such a sequence represents
  64 any data type which VMD can parse since it can consist of emptiness, a single data type,
  65 or multiple data types represented consecutively.
  66
  67 Emptiness, the three identifier types, the four Boost PP composite data types, and
  68 VMD sequences are the data types which VMD understands. Other low-level preprocessor
  69 data types can of course be used in macro programming but VMD cannot parse such
  70 preprocessor data.
  71
  72 [endsect]