1[section Preface] 2 3[section Description] 4 5Metaparse is a compile-time parser generator library. Metaparse provides tools 6to write parsers parsing the content of string literals at compile-time, which 7makes it possible to embed domain specific languages (DSLs) into C++ without 8altering their original syntax (Note that the DSL code snippets will be written 9in string literals, therefore they may need to be escaped). 10 11Assuming that the following template class is available for representing 12rational numbers in template metaprogramming: 13 14 template <class Num, class Denom> 15 struct rational; 16 17Metaparse can be used to construct such values (instantiate the `rational` 18template class) from string literals. Instead of `rational<1, 3>` one can write 19`RATIONAL("1/3")` which can be processed by any standard-compliant C++11 20compiler (and mean the same). This can be implemented using Metaparse the 21following way: 22 23 using namespace boost::metaparse; 24 25 typedef 26 sequence_apply2< 27 rational, 28 29 token<int_>, 30 last_of<lit_c<'/'>, token<int_>> 31 > 32 rational_grammar; 33 34 typedef build_parser<entire_input<rational_grammar>> rational_parser; 35 36 #define RATIONAL(s) \ 37 (::rational_parser::apply<BOOST_METAPARSE_STRING(s)>::type::run()) 38 39Note that this is the entire implementation. Also note that this implementation 40can be extended to improve the error reports in certain situations. 41 42[endsect] 43 44 45 46[section Scope] 47 48Metaparse is intended to be used by library authors to make their APIs follow 49the usual notation of the library's problem domain. 50 51[section Comparsion to Boost.Proto] 52 53Boost.Proto is a tool for building expression templates. Expression templates 54can be used for DSL embedding by reinterpreting valid C++ expressions as 55expressions written in the DSL to embed. 56 57This technique has the advantages over parsing the content of string literals 58(which is Metaparse's approach) that: 59 60* is faster in most cases 61* APIs using this technique can "emerge" as a process of advancing the API of a 62 library step-by-step. Moving to a completely new DSL (with its own syntax) is 63 a relatively big step. 64 65Using expression templates for DSL embedding has the following disadvantages: 66 67* the syntax of the embedded DSL is limited. It has to be a valid C++ 68 expression. For most libraries, people familiar with the original DSL usually 69 need to learn the library's syntax to understand the embedded code snippets. 70 71Proto helps embedding DSLs based on expression templates, while Metaparse helps 72embedding DSLs based on parsing the content of string literals. 73 74[endsect] 75 76[section Comparison to Boost.Spirit] 77 78Spirit is a tool that can be used to build parsers parsing (among others) the 79content of string literals at runtime, while Metaparse is a tool that can be 80used to parse the content of string literals at compile-time. 81 82[endsect] 83 84[endsect] 85 86[section Advantages of using this library] 87 88This library is useful to provide an API for C++ libraries dealing with a 89problem domain with its own notation. Interfaces built with Metaparse make it 90possible for the users of the interface to use the domain's own notation, which 91makes it easier to write and maintain the code. Users of the interface don't 92need to learn a new notation (trying to follow the problem domain's original 93one) library authors constrained by the C++ syntax can provide. Example problem 94domains are regular expressions and SQL queries. 95 96Metaparse can also be useful to build libraries validating the content of string 97literals at compile time instead of doing it at runtime or not doing it at all. 98This can help finding (and fixing) bugs in the code early (during compilation). 99An example problem domain is `printf`. 100 101[endsect] 102 103[section Cost of using Metaparse] 104 105The parsers built with Metaparse process the content of the string literals 106using template metaprograms. This impacts the library using Metaparse the 107following way: 108 109* The maintainer of the API built with Metaparse will need to understand 110 template metaprogramming. 111* The content of the string literals will be (re)parsed during every 112 compilation. This will impact the compiler's memory consumption and the 113 compilation speed. 114* The users of the library will receive the error reports coming from the 115 parsers as template error messages of their compiler. (Note that Metaparse 116 actively tries improving their quality and provides 117 [link dealing_with_invalid_input tools] for parser authors). 118 119[endsect] 120 121 122[section Supported platforms] 123 124Metaparse is based on C++98. The only exception is the 125[link BOOST_METAPARSE_STRING] macro, which needs C++11 `constexpr`. 126 127Compilers Metaparse is actively (in a CI environment) tested on: 128 129* GCC 4.6, 4.7, 4.8, 4.9 130* Clang 3.4, 3.5, 3.6 131* Visual C++ 2015 132 133Metaparse is expected to work on Visual C++ 2012 and 2010. 134 135[endsect] 136 137[endsect] 138 139