ceph/src/boost/libs/vmd/doc/vmd_modifiers.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_modifiers Macros with modifiers]
   9
  10 The basic functionality for VMD macros parsing data types
  11 has been given using the required parameters of those
  12 macros. This basic functionality may be perfectly adequate for
  13 macro programmers to use VMD effectively in their programming efforts.
  14
  15 A number of those macros take optional parameters,
  16 called in general "modifiers", which enhance or change the
  17 functionality of those macros in various ways. All modifiers
  18 are VMD identifiers.
  19
  20 In all situations modifiers are optional parameters which are parsed
  21 by VMD to provide enhanced functionality for some of its macros.
  22 They are never required as part of the basic functionality of a macro.
  23
  24 When modifiers are used as optional arguments to a macro they
  25 can be input after the required parameters in any order and
  26 VMD will still handle the optional parameters correctly.
  27
  28 There are two general types of modifiers, 'specific modifiers' and
  29 'user-defined modifiers'. Specific modifers start with BOOST_VMD_
  30 and are both registered and pre-detected identifiers known to VMD.
  31 The specific modifiers change the expansion of particular macros
  32 in various ways which will be subsequently explained. User-defined
  33 modifiers are user-defined identifiers which the end-user of
  34 specific macros must register and pre-detect for himself. They also
  35 change the expansion of particular macros in various ways which
  36 will be subsequently explained.
  37
  38 For any particular macro if a specific modifier
  39 is not appropriate it is just ignored. This means that VMD never
  40 generates a preprocessing error or gives an incorrect result
  41 just because a specific modifier does not apply for a particular
  42 macro. Any modifier which is not recognized as a specific modifier
  43 is treated as a user-defined modifier. In cases where a user-defined
  44 modifier is not appropriate it is also just ignored.
  45
  46 The situations where modifiers can be used to enhance the basic
  47 functionality of VMD macros can be divided by particular types
  48 of specific modifiers. Each particular type of a specific modifier
  49 has a name given to it, functionality, and set of identifiers
  50 associated with that particular type.
  51 Each particular type of a specific modifier may be used as optional
  52 parameters in one or more designated macros depending on the specific
  53 modifier type.
  54
  55 When more than one mutually exclusive specific modifier from a particular type of modifier is
  56 specified as an optional parameter the last specified takes effect. This
  57 allows the programmer to override a specific modifier by adding the
  58 overridden identifier as an optional argument to the end of the
  59 macro's invocation.
  60
  61 Header files for specific modifiers are automatically included when
  62 the header files for macros taking those specific modifiers are
  63 included.
  64
  65 Header files for user-defined modifiers, which register and pre-detect
  66 those user-defined modifiers, must be included as needed by the programmer
  67 using those modifiers.
  68
  69 The following topics will explain each particular type of modifier
  70 and where it may be used.
  71
  72 [include vmd_modifiers_return_type.qbk]
  73 [include vmd_modifiers_filter.qbk]
  74 [include vmd_modifiers_identifier.qbk]
  75 [include vmd_modifiers_splitting.qbk]
  76 [include vmd_modifiers_index.qbk]
  77 [include vmd_modifiers_single_element.qbk]
  78
  79 [endsect]