1[section The design of the library] 2 3The purpose of the library is to provide tools to build template metaprograms 4being able to interpret the content of a string literal and generate code, 5display error messages, etc based on the content of the string literal. Such 6metaprograms are called [link parser parser]s. Metaparse is based on 7[@https://en.wikipedia.org/wiki/Parser_combinator parser combinators]. 8 9 10The 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 33An alternative is using `constexpr` functions instead of template metaprograms. 34There are certain things that are difficult (if possible) using `constexpr` 35functions: building containers (at compile-time) the length of which depend on 36the parsed text (eg. parsing a JSON list), generating and validating types (eg. 37`printf`). 38 39* [*Why are there so many folding parsers?] 40 41Compilation speed and memory consumption is a critical part of template 42metaprogramming-based libraries. Users of the library interfaces built with 43Metaparse will have to pay for that every time they compile their code. 44Therefore it is important to provide the parser authors the ability to use the 45parser combinators with minimal overhead, while it is also important to provide 46convenient combinators for beginners and for the cases where that is the best 47option anyway. 48 49[link repeated `repeated`] combined with [link sequence `sequence`], 50[link accept_when `accept_when`] and [link transform `transform`] can replace 51any of the folding parsers, however, for the cost of constructing intermediate 52containers, that are (usually) processed sequentially after that. 53 54* [*Why external code generator for `BOOST_METAPARSE_STRING`?] 55 56To be able to support longer strings. It generates code using macros to reduce 57the size of the header files (the reducion is multiples of MBs). 58 59* [*Why defining a custom version of Boost.Preprocessor macros?] 60 61There are two reasons for the library defining its own set of preprocessor 62metaprogramming macros: to have control over the upper limit of iteration steps 63and to be able to clean the macros up once they have done their job (and avoid 64polluting the macros of the users). 65 66Note that these macros live in the `impl` directory, which means that they are 67an implementation detail of the library and should be used internally only. 68 69[endsect] 70 71[endsect] 72 73