1<?xml version="1.0" encoding="utf-8"?>
2<!--
3  Copyright 2012 Eric Niebler
4
5  Distributed under the Boost
6  Software License, Version 1.0. (See accompanying
7  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8  -->
9<header name="boost/proto/debug.hpp">
10  <para>Utilities for debugging Proto expression trees </para>
11  <namespace name="boost">
12    <namespace name="proto">
13      <namespace name="functional">
14
15        <!-- proto::functional::display_expr -->
16        <struct name="display_expr">
17          <purpose>Pretty-print a Proto expression tree. </purpose>
18          <description>
19            <para>
20              A <conceptname>PolymorphicFunctionObject</conceptname> which accepts a Proto expression tree and pretty-prints it to an <computeroutput>ostream</computeroutput> for debugging purposes.
21            </para>
22          </description>
23
24          <typedef name="result_type">
25            <type>void</type>
26          </typedef>
27
28          <method-group name="public member functions">
29            <method name="operator()" cv="const">
30              <type>void</type>
31              <template>
32                <template-type-parameter name="Expr"/>
33              </template>
34              <parameter name="expr">
35                <paramtype>Expr const &amp;</paramtype>
36              </parameter>
37            </method>
38          </method-group>
39
40          <constructor>
41            <parameter name="sout"><paramtype>std::ostream &amp;</paramtype><default>std::cout</default>
42              <description>
43                <para>
44                  The <computeroutput>ostream</computeroutput> to which the expression tree will be written.
45                </para>
46              </description>
47            </parameter>
48            <parameter name="depth">
49              <paramtype>int</paramtype>
50              <default>0</default>
51              <description>
52                <para>
53                  The starting indentation depth for this node. Children nodes will be displayed at a starting depth of <computeroutput>depth+4</computeroutput>.
54                </para>
55              </description>
56            </parameter>
57          </constructor>
58        </struct>
59
60      </namespace>
61
62      <!-- proto::display_expr -->
63      <overloaded-function name="display_expr">
64
65        <signature>
66          <type>void</type>
67          <template>
68            <template-type-parameter name="Expr"/>
69          </template>
70          <parameter name="expr">
71            <paramtype>Expr const &amp;</paramtype>
72            <description>
73              <para>The Proto expression tree to pretty-print </para>
74            </description>
75          </parameter>
76          <parameter name="sout">
77            <paramtype>std::ostream &amp;</paramtype>
78            <description>
79              <para>
80                The <computeroutput>ostream</computeroutput> to which the output should be written. If not specified, defaults to <computeroutput>std::cout</computeroutput>.
81              </para>
82            </description>
83          </parameter>
84        </signature>
85
86        <signature>
87          <type>void</type>
88          <template>
89            <template-type-parameter name="Expr"/>
90          </template>
91          <parameter name="expr">
92            <paramtype>Expr const &amp;</paramtype>
93          </parameter>
94        </signature>
95        <purpose>Pretty-print a Proto expression tree. </purpose>
96        <notes>
97          <para>
98            Equivalent to <computeroutput><classname alt="boost::proto::functional::display_expr">proto::functional::display_expr</classname>(0, sout)(expr)</computeroutput>.
99          </para>
100        </notes>
101      </overloaded-function>
102
103      <!-- proto::assert_matches -->
104      <function name="assert_matches">
105        <type>void</type>
106        <template>
107          <template-type-parameter name="Grammar"/>
108          <template-type-parameter name="Expr"/>
109        </template>
110        <parameter name="expr">
111          <paramtype>Expr const &amp;</paramtype>
112          <purpose>
113            The Proto expression to check againts <code>Grammar</code>.
114          </purpose>
115        </parameter>
116        <purpose>
117          Assert at compile time that a particular expression
118          matches the specified grammar.
119        </purpose>
120        <notes>
121          <para>
122            Equivalent to <code>BOOST_MPL_ASSERT((<classname alt="proto::matches">proto::matches</classname>&lt;Expr, Grammar&gt;))</code>.
123          </para>
124        </notes>
125        <description>
126          <para>
127            Use <code>proto::assert_matches()</code> to assert at compile-time that
128            an expression matches a grammar.
129          </para>
130          <para>
131            <emphasis role="bold">Example:</emphasis><programlisting>typedef proto::plus&lt; proto::terminal&lt; int &gt;, proto::terminal&lt; int &gt; &gt; PlusInts;
132
133proto::assert_matches&lt;PlusInts&gt;( <functionname>proto::lit</functionname>(1) + 42 );</programlisting>
134          </para>
135          <para>
136            See also:
137            <itemizedlist>
138              <listitem>
139                <code><functionname>proto::assert_matches_not</functionname>()</code>
140              </listitem>
141              <listitem>
142                <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
143              </listitem>
144              <listitem>
145                <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
146              </listitem>
147            </itemizedlist>
148          </para>
149        </description>
150      </function>
151
152      <!-- proto::assert_matches_not -->
153      <function name="assert_matches_not">
154        <type>void</type>
155        <template>
156          <template-type-parameter name="Grammar"/>
157          <template-type-parameter name="Expr"/>
158        </template>
159        <parameter name="expr">
160          <paramtype>Expr const &amp;</paramtype>
161          <purpose>
162            The Proto expression to check againts <code>Grammar</code>.
163          </purpose>
164        </parameter>
165        <purpose>
166          Assert at compile time that a particular expression
167          does not match the specified grammar.
168        </purpose>
169        <notes>
170          <para>
171            Equivalent to <code>BOOST_MPL_ASSERT_NOT((<classname alt="proto::matches">proto::matches</classname>&lt;Expr, Grammar&gt;))</code>.
172          </para>
173        </notes>
174        <description>
175          <para>
176            Use <code>proto::assert_matches_not()</code> to assert at compile-time that
177            an expression does not match a grammar.
178          </para>
179          <para>
180            <emphasis role="bold">Example:</emphasis><programlisting>typedef proto::plus&lt; proto::terminal&lt; int &gt;, proto::terminal&lt; int &gt; &gt; PlusInts;
181
182proto::assert_matches_not&lt;PlusInts&gt;( <functionname>proto::lit</functionname>("a string") + 42 );</programlisting>
183          </para>
184          <para>
185            See also:
186            <itemizedlist>
187              <listitem>
188                <code><functionname>proto::assert_matches</functionname>()</code>
189              </listitem>
190              <listitem>
191                <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
192              </listitem>
193              <listitem>
194                <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
195              </listitem>
196            </itemizedlist>
197          </para>
198        </description>
199      </function>
200    </namespace>
201  </namespace>
202
203  <macro name="BOOST_PROTO_ASSERT_MATCHES" kind="functionlike">
204    <macro-parameter name="expr"/>
205    <macro-parameter name="Grammar"/>
206    <purpose>
207      Assert at compile time that a particular expression
208      matches the specified grammar.
209    </purpose>
210    <notes>
211      <para>
212        Equivalent to <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>&lt;Grammar&gt;(expr)</code>.
213      </para>
214    </notes>
215    <description>
216      <para>
217        Use <code>BOOST_PROTO_ASSERT_MATCHES()</code> to assert at compile-time that
218        an expression matches a grammar.
219      </para>
220      <para>
221        <emphasis role="bold">Example:</emphasis><programlisting>typedef <classname alt="boost::proto::plus">proto::plus</classname>&lt; <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt;, <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt; &gt; PlusInts;
222
223BOOST_PROTO_ASSERT_MATCHES( <functionname alt="boost::proto::lit">proto::lit</functionname>(1) + 42, PlusInts );</programlisting>
224      </para>
225      <para>
226        See also:
227        <itemizedlist>
228          <listitem>
229            <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>()</code>
230          </listitem>
231          <listitem>
232            <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>()</code>
233          </listitem>
234          <listitem>
235            <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
236          </listitem>
237        </itemizedlist>
238      </para>
239    </description>
240  </macro>
241
242  <macro name="BOOST_PROTO_ASSERT_MATCHES_NOT" kind="functionlike">
243    <macro-parameter name="expr"/>
244    <macro-parameter name="Grammar"/>
245    <purpose>
246      Assert at compile time that a particular expression
247      does not match the specified grammar.
248    </purpose>
249    <notes>
250      <para>
251        Equivalent to <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>&lt;Grammar&gt;(expr)</code>.
252      </para>
253    </notes>
254    <description>
255      <para>
256        Use <code>BOOST_PROTO_ASSERT_MATCHES_NOT()</code> to assert at compile-time that
257        an expression does not match a grammar.
258      </para>
259      <para>
260        <emphasis role="bold">Example:</emphasis><programlisting>typedef <classname alt="boost::proto::plus">proto::plus</classname>&lt; <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt;, <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt; &gt; PlusInts;
261
262BOOST_PROTO_ASSERT_MATCHES_NOT( <functionname alt="boost::proto::lit">proto::lit</functionname>("a string") + 42, PlusInts );</programlisting>
263      </para>
264      <para>
265        See also:
266        <itemizedlist>
267          <listitem>
268            <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>()</code>
269          </listitem>
270          <listitem>
271            <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>()</code>
272          </listitem>
273          <listitem>
274            <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
275          </listitem>
276        </itemizedlist>
277      </para>
278    </description>
279  </macro>
280</header>
281