ceph/src/boost/libs/metaparse/doc/design.qbk

   1 [section The design of the library]
   2
   3 The purpose of the library is to provide tools to build template metaprograms
   4 being able to interpret the content of a string literal and generate code,
   5 display error messages, etc based on the content of the string literal. Such
   6 metaprograms are called [link parser parser]s. Metaparse is based on
   7 [@https://en.wikipedia.org/wiki/Parser_combinator parser combinators].
   8
   9
  10 The key components of the library:
  11
  12 * [link ref-string Compile-time string representation]. These are tools for
  13   representing the content of a string literal in a way that makes it possible
  14   for template metaprograms to work on them. For this the library provides the
  15   [link string `string`] template class, which is a drop-in replacement of
  16   Boost.MPL's `string` implementation, and the [link BOOST_METAPARSE_STRING
  17   `BOOST_METAPARSE_STRING`] macro.
  18
  19 * [link parsers Parsers]. These are template metafunction classes parsing a
  20   prefix of a string literal. These are simple [link parser parser]s providing
  21   the basic building blocks for more complicated ones doing some useful work.
  22
  23 * [link combinators Parser combinators]. These are
  24   [link metafunction template metafunction]s taking [link parser parser]s as
  25   argument and/or returning [link parser parser]s as their result. They can be
  26   used to build more and more complex [link parser parser]s out of the simple
  27   ones.
  28
  29 [section Design rationale]
  30
  31 * [*Why template metaprogramming?]
  32
  33 An alternative is using `constexpr` functions instead of template metaprograms.
  34 There are certain things that are difficult (if possible) using `constexpr`
  35 functions: building containers (at compile-time) the length of which depend on
  36 the parsed text (eg. parsing a JSON list), generating and validating types (eg.
  37 `printf`).
  38
  39 * [*Why are there so many folding parsers?]
  40
  41 Compilation speed and memory consumption is a critical part of template
  42 metaprogramming-based libraries. Users of the library interfaces built with
  43 Metaparse will have to pay for that every time they compile their code.
  44 Therefore it is important to provide the parser authors the ability to use the
  45 parser combinators with minimal overhead, while it is also important to provide
  46 convenient combinators for beginners and for the cases where that is the best
  47 option anyway.
  48
  49 [link repeated `repeated`] combined with [link sequence `sequence`],
  50 [link accept_when `accept_when`] and [link transform `transform`] can replace
  51 any of the folding parsers, however, for the cost of constructing intermediate
  52 containers, that are (usually) processed sequentially after that.
  53
  54 * [*Why external code generator for `BOOST_METAPARSE_STRING`?]
  55
  56 To be able to support longer strings. It generates code using macros to reduce
  57 the size of the header files (the reducion is multiples of MBs).
  58
  59 * [*Why defining a custom version of Boost.Preprocessor macros?]
  60
  61 There are two reasons for the library defining its own set of preprocessor
  62 metaprogramming macros: to have control over the upper limit of iteration steps
  63 and to be able to clean the macros up once they have done their job (and avoid
  64 polluting the macros of the users).
  65
  66 Note that these macros live in the `impl` directory, which means that they are
  67 an implementation detail of the library and should be used internally only.
  68
  69 [endsect]
  70
  71 [endsect]
  72