summaryrefslogtreecommitdiff
path: root/doc/html/metaparse/preface.html
blob: cd490f0d00504a9f3bb300738e133664a8e28f8f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Preface</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../metaparse.html" title="Chapter&#160;20.&#160;Boost.Metaparse">
<link rel="prev" href="related_publications_and_blogs.html" title="Related publications and blogs">
<link rel="next" href="getting_started_with_boost_metap.html" title="Getting started with Boost.Metaparse">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="related_publications_and_blogs.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../metaparse.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="getting_started_with_boost_metap.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="metaparse.preface"></a><a class="link" href="preface.html" title="Preface">Preface</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="preface.html#metaparse.preface.description">Description</a></span></dt>
<dt><span class="section"><a href="preface.html#metaparse.preface.scope">Scope</a></span></dt>
<dt><span class="section"><a href="preface.html#metaparse.preface.advantages_of_using_this_library">Advantages
      of using this library</a></span></dt>
<dt><span class="section"><a href="preface.html#metaparse.preface.cost_of_using_metaparse">Cost of using
      Metaparse</a></span></dt>
<dt><span class="section"><a href="preface.html#metaparse.preface.supported_platforms">Supported platforms</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="metaparse.preface.description"></a><a class="link" href="preface.html#metaparse.preface.description" title="Description">Description</a>
</h3></div></div></div>
<p>
        Metaparse is a compile-time parser generator library. Metaparse provides
        tools to write parsers parsing the content of string literals at compile-time,
        which makes it possible to embed domain specific languages (DSLs) into C++
        without altering their original syntax (Note that the DSL code snippets will
        be written in string literals, therefore they may need to be escaped).
      </p>
<p>
        Assuming that the following template class is available for representing
        rational numbers in template metaprogramming:
      </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Num</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Denom</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">rational</span><span class="special">;</span>
</pre>
<p>
        Metaparse can be used to construct such values (instantiate the <code class="computeroutput"><span class="identifier">rational</span></code> template class) from string literals.
        Instead of <code class="computeroutput"><span class="identifier">rational</span><span class="special">&lt;</span><span class="number">1</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span></code> one can write <code class="computeroutput"><span class="identifier">RATIONAL</span><span class="special">(</span><span class="string">"1/3"</span><span class="special">)</span></code> which can be processed by any standard-compliant
        C++11 compiler (and mean the same). This can be implemented using Metaparse
        the following way:
      </p>
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">metaparse</span><span class="special">;</span>

<span class="keyword">typedef</span>
  <span class="identifier">sequence_apply2</span><span class="special">&lt;</span>
    <span class="identifier">rational</span><span class="special">,</span>

    <span class="identifier">token</span><span class="special">&lt;</span><span class="identifier">int_</span><span class="special">&gt;,</span>
    <span class="identifier">last_of</span><span class="special">&lt;</span><span class="identifier">lit_c</span><span class="special">&lt;</span><span class="char">'/'</span><span class="special">&gt;,</span> <span class="identifier">token</span><span class="special">&lt;</span><span class="identifier">int_</span><span class="special">&gt;&gt;</span>
  <span class="special">&gt;</span>
  <span class="identifier">rational_grammar</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">build_parser</span><span class="special">&lt;</span><span class="identifier">entire_input</span><span class="special">&lt;</span><span class="identifier">rational_grammar</span><span class="special">&gt;&gt;</span> <span class="identifier">rational_parser</span><span class="special">;</span>

<span class="preprocessor">#define</span> <span class="identifier">RATIONAL</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span> <span class="special">\</span>
  <span class="special">(::</span><span class="identifier">rational_parser</span><span class="special">::</span><span class="identifier">apply</span><span class="special">&lt;</span><span class="identifier">BOOST_METAPARSE_STRING</span><span class="special">(</span><span class="identifier">s</span><span class="special">)&gt;::</span><span class="identifier">type</span><span class="special">::</span><span class="identifier">run</span><span class="special">())</span>
</pre>
<p>
        Note that this is the entire implementation. Also note that this implementation
        can be extended to improve the error reports in certain situations.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="metaparse.preface.scope"></a><a class="link" href="preface.html#metaparse.preface.scope" title="Scope">Scope</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="preface.html#metaparse.preface.scope.comparsion_to_boost_proto">Comparsion
        to Boost.Proto</a></span></dt>
<dt><span class="section"><a href="preface.html#metaparse.preface.scope.comparison_to_boost_spirit">Comparison
        to Boost.Spirit</a></span></dt>
</dl></div>
<p>
        Metaparse is intended to be used by library authors to make their APIs follow
        the usual notation of the library's problem domain.
      </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="metaparse.preface.scope.comparsion_to_boost_proto"></a><a class="link" href="preface.html#metaparse.preface.scope.comparsion_to_boost_proto" title="Comparsion to Boost.Proto">Comparsion
        to Boost.Proto</a>
</h4></div></div></div>
<p>
          Boost.Proto is a tool for building expression templates. Expression templates
          can be used for DSL embedding by reinterpreting valid C++ expressions as
          expressions written in the DSL to embed.
        </p>
<p>
          This technique has the advantages over parsing the content of string literals
          (which is Metaparse's approach) that:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
              is faster in most cases
            </li>
<li class="listitem">
              APIs using this technique can "emerge" as a process of advancing
              the API of a library step-by-step. Moving to a completely new DSL (with
              its own syntax) is a relatively big step.
            </li>
</ul></div>
<p>
          Using expression templates for DSL embedding has the following disadvantages:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
              the syntax of the embedded DSL is limited. It has to be a valid C++
              expression. For most libraries, people familiar with the original DSL
              usually need to learn the library's syntax to understand the embedded
              code snippets.
            </li></ul></div>
<p>
          Proto helps embedding DSLs based on expression templates, while Metaparse
          helps embedding DSLs based on parsing the content of string literals.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="metaparse.preface.scope.comparison_to_boost_spirit"></a><a class="link" href="preface.html#metaparse.preface.scope.comparison_to_boost_spirit" title="Comparison to Boost.Spirit">Comparison
        to Boost.Spirit</a>
</h4></div></div></div>
<p>
          Spirit is a tool that can be used to build parsers parsing (among others)
          the content of string literals at runtime, while Metaparse is a tool that
          can be used to parse the content of string literals at compile-time.
        </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="metaparse.preface.advantages_of_using_this_library"></a><a class="link" href="preface.html#metaparse.preface.advantages_of_using_this_library" title="Advantages of using this library">Advantages
      of using this library</a>
</h3></div></div></div>
<p>
        This library is useful to provide an API for C++ libraries dealing with a
        problem domain with its own notation. Interfaces built with Metaparse make
        it possible for the users of the interface to use the domain's own notation,
        which makes it easier to write and maintain the code. Users of the interface
        don't need to learn a new notation (trying to follow the problem domain's
        original one) library authors constrained by the C++ syntax can provide.
        Example problem domains are regular expressions and SQL queries.
      </p>
<p>
        Metaparse can also be useful to build libraries validating the content of
        string literals at compile time instead of doing it at runtime or not doing
        it at all. This can help finding (and fixing) bugs in the code early (during
        compilation). An example problem domain is <code class="computeroutput"><span class="identifier">printf</span></code>.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="metaparse.preface.cost_of_using_metaparse"></a><a class="link" href="preface.html#metaparse.preface.cost_of_using_metaparse" title="Cost of using Metaparse">Cost of using
      Metaparse</a>
</h3></div></div></div>
<p>
        The parsers built with Metaparse process the content of the string literals
        using template metaprograms. This impacts the library using Metaparse the
        following way:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
            The maintainer of the API built with Metaparse will need to understand
            template metaprogramming.
          </li>
<li class="listitem">
            The content of the string literals will be (re)parsed during every compilation.
            This will impact the compiler's memory consumption and the compilation
            speed.
          </li>
<li class="listitem">
            The users of the library will receive the error reports coming from the
            parsers as template error messages of their compiler. (Note that Metaparse
            actively tries improving their quality and provides <a class="link" href="getting_started_with_boost_metap.html#dealing_with_invalid_input">tools</a>
            for parser authors).
          </li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="metaparse.preface.supported_platforms"></a><a class="link" href="preface.html#metaparse.preface.supported_platforms" title="Supported platforms">Supported platforms</a>
</h3></div></div></div>
<p>
        Metaparse is based on C++98. The only exception is the <a class="link" href="reference.html#BOOST_METAPARSE_STRING">BOOST_METAPARSE_STRING</a>
        macro, which needs C++11 <code class="computeroutput"><span class="keyword">constexpr</span></code>.
      </p>
<p>
        Compilers Metaparse is actively (in a CI environment) tested on:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
            GCC 4.6, 4.7, 4.8, 4.9
          </li>
<li class="listitem">
            Clang 3.4, 3.5, 3.6
          </li>
<li class="listitem">
            Visual C++ 2015
          </li>
</ul></div>
<p>
        Metaparse is expected to work on Visual C++ 2012 and 2010.
      </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2015 Abel Sinkovics<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="related_publications_and_blogs.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../metaparse.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="getting_started_with_boost_metap.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>