[section The design of the library]

The purpose of the library is to provide tools to build template metaprograms
being able to interpret the content of a string literal and generate code,
display error messages, etc based on the content of the string literal. Such
metaprograms are called [link parser parser]s. Metaparse is based on
[@https://en.wikipedia.org/wiki/Parser_combinator parser combinators].


The key components of the library:

* [link ref-string Compile-time string representation]. These are tools for
  representing the content of a string literal in a way that makes it possible
  for template metaprograms to work on them. For this the library provides the
  [link string `string`] template class, which is a drop-in replacement of
  Boost.MPL's `string` implementation, and the [link BOOST_METAPARSE_STRING
  `BOOST_METAPARSE_STRING`] macro.

* [link parsers Parsers]. These are template metafunction classes parsing a
  prefix of a string literal. These are simple [link parser parser]s providing
  the basic building blocks for more complicated ones doing some useful work.

* [link combinators Parser combinators]. These are
  [link metafunction template metafunction]s taking [link parser parser]s as
  argument and/or returning [link parser parser]s as their result. They can be
  used to build more and more complex [link parser parser]s out of the simple
  ones.

[section Design rationale]

* [*Why template metaprogramming?]

An alternative is using `constexpr` functions instead of template metaprograms.
There are certain things that are difficult (if possible) using `constexpr`
functions: building containers (at compile-time) the length of which depend on
the parsed text (eg. parsing a JSON list), generating and validating types (eg.
`printf`).

* [*Why are there so many folding parsers?]

Compilation speed and memory consumption is a critical part of template
metaprogramming-based libraries. Users of the library interfaces built with
Metaparse will have to pay for that every time they compile their code.
Therefore it is important to provide the parser authors the ability to use the
parser combinators with minimal overhead, while it is also important to provide
convenient combinators for beginners and for the cases where that is the best
option anyway.

[link repeated `repeated`] combined with [link sequence `sequence`],
[link accept_when `accept_when`] and [link transform `transform`] can replace
any of the folding parsers, however, for the cost of constructing intermediate
containers, that are (usually) processed sequentially after that.

* [*Why external code generator for `BOOST_METAPARSE_STRING`?]

To be able to support longer strings. It generates code using macros to reduce
the size of the header files (the reducion is multiples of MBs).

* [*Why defining a custom version of Boost.Preprocessor macros?]

There are two reasons for the library defining its own set of preprocessor
metaprogramming macros: to have control over the upper limit of iteration steps
and to be able to clean the macros up once they have done their job (and avoid
polluting the macros of the users).

Note that these macros live in the `impl` directory, which means that they are
an implementation detail of the library and should be used internally only.

[endsect]

[endsect]