]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |