The design of the library

Design rationale

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 parsers. Metaparse is based on parser combinators.

The key components of the library:

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 string template class, which is a drop-in replacement of Boost.MPL's string implementation, and the BOOST_METAPARSE_STRING macro.
Parsers. These are template metafunction classes parsing a prefix of a string literal. These are simple parsers providing the basic building blocks for more complicated ones doing some useful work.
Parser combinators. These are template metafunctions taking parsers as argument and/or returning parsers as their result. They can be used to build more and more complex parsers out of the simple ones.

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.

repeated combined with sequence, accept_when and 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.