sp
/
Tempest_in_Action
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5 Commits
1 Branch
0 Tags
24 MiB
Tree: a2b31f7d6b
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a2b31f7d6b'
${ noResults }
Tempest_in_Action/tempest-devel/resources/3rdparty/cpphoafparser-0.99.2/docs/cpphoafparser-library.html

183 lines
12 KiB
Raw Normal View History

initial commit
2 months ago
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
  1. <!DOCTYPE HTML>
  2. <html>
  3. <head>
  4. <meta http-equiv="content-type" content="text/html; charset=utf-8">
  5. <link href="cpphoafparser.css" rel="stylesheet">
  6. <link href="cpp2html.css" rel="stylesheet">
  7. <title>Using the cpphoafparser Library [cpphoafparser Library for the Hanoi Omega-Automata Format (HOAF), version 0.99.2]</title>
  8. </head>
  10. <body>
  11. <div class="nav"><a class="nav" href="index.html">^ Overview</a></div>
  13. <h1>
  14. Using the <span class="blue1">cpp</span><span class="blue2">hoaf</span><span class="blue3">parser</span> Library<br/>
  15. <span style="font-size:70%">The <span class="blue">cpphoafparser</span>
  16. Library for the Hanoi Omega-Automata Format (HOAF), version 0.99.2</span>
  17. </h1>
  19. <p>The cpphoafparser library can be used to parse and process &omega;-automata
  20. in the HOA format. We assume here that the reader is familiar with the basic concepts of
  21. the <a href="http://adl.github.io/hoaf/">Hanoi Omega-Automata Format (HOAF)</a>.
  22. </p>
  24. <h2><a name="general">General Structure</a></h2>
  26. <p>
  27. The two main building blocks of the parser library are the <em>parser</em> and
  28. classes implementing the <em>HOAConsumer</em> interface. A <em>HOAConsumer</em> has functions
  29. corresponding to the various elements that can occur in a HOA automaton. While parsing, the parser
  30. calls each of these functions to indicate that this particular element has just occurred.
  31. </p>
  33. <p>cpphoafparser is a <emph>header-only</emph> C++ library, i.e., it suffices to
  34. add the <span class="classname">include</span> directory to the include path of your compiler
  35. and include the corresponding header files. All cpphoafparser elements are contained in the
  36. <span class="classname">cpphoafparser</span> namespace. It uses C++11 features, so ensure that your
  37. compiler is configured to support this standard version.
  38. </p>
  41. <h3>A Basic Parser</h3>
  42. <p>The most basic use of the cpphoafparser library is shown in the following code snippet
  43. (<span class="classname">src/basic_parser_1.cc</span></span>):</p>
  45. <div class="code">
  46. <pre><span class="pre">#include "cpphoafparser/consumer/hoa_consumer_print.hh"
  47. #include "cpphoafparser/parser/hoa_parser.hh"
  48. </span><span class="keyword">
  49. using namespace</span> cpphoafparser<span class="operator">;</span><span class="comment">
  51. /** The most basic HOA parser: Read an automaton from input and print it to the output. */</span><span class="type">
  52. int</span><span class="keyword"> main</span><span class="operator">(</span><span class="type">int</span> argc<span class="operator">,</span><span class="keyword"> const</span><span class="type"> char</span><span class="operator">*</span> argv<span class="operator">[]) {</span>
  53. HOAConsumer<span class="operator">::</span>ptr consumer<span class="operator">(</span><span class="keyword">new</span> HOAConsumerPrint<span class="operator">(</span>std<span class="operator">::</span>cout<span class="operator">));</span><span class="flow">
  55. try</span><span class="operator"> {</span>
  57. HOAParser<span class="operator">::</span>parse<span class="operator">(</span>std<span class="operator">::</span>cin<span class="operator">,</span> consumer<span class="operator">);
  59. }</span><span class="flow"> catch</span><span class="operator"> (</span>std<span class="operator">::</span>exception<span class="operator">&amp;</span> e<span class="operator">) {</span>
  60. std<span class="operator">::</span>cerr<span class="operator"> &lt;&lt;</span> e<span class="operator">.</span>what<span class="operator">() &lt;&lt;</span> std<span class="operator">::</span>endl<span class="operator">;</span><span class="flow">
  61. return</span><span class="int"> 1</span><span class="operator">;
  62. }</span><span class="flow">
  63. return</span><span class="int"> 0</span><span class="operator">;
  64. }</span>
  65. </pre>
  66. </div>
  68. <p>
  69. Here, the parser reads from <span class="classname">std::cin</span>
  70. and calls into a <span class="classname">HOAConsumerPrint</span>
  71. object that just outputs the elements to <span class="classname">std::cout</span>.</p>
  73. <h3>Chaining Multiple HOAConsumers: HOAIntermediate</h3>
  75. <p>The <span class="classname">HOAIntermediate</span> class, which itself
  76. implements the <span class="classname">HOAConsumer</span> interface, provides the basis for chaining multiple
  77. <span class="classname">HOAConsumers</span>, one after another, each reading the output of the previous one.
  78. </p>
  80. <p>
  81. Consider the following example
  82. (<span class="classname">src/basic_parser_2.cc</span></span>):</p>
  84. <div class="code">
  85. <pre><span class="pre">#include "cpphoafparser/consumer/hoa_intermediate.hh"
  86. #include "cpphoafparser/consumer/hoa_consumer_null.hh"
  87. #include "cpphoafparser/parser/hoa_parser.hh"
  88. </span><span class="keyword">
  89. using namespace</span> cpphoafparser<span class="operator">;</span><span class="comment">
  91. /* An HOAIntermediate that counts invocations of addState */</span><span class="keyword">
  92. class</span> CountStates<span class="operator"> :</span><span class="keyword"> public</span> HOAIntermediate<span class="operator"> {</span><span class="keyword">
  93. public</span><span class="operator">:</span><span class="keyword">
  94. typedef</span> std<span class="operator">::</span>shared_ptr<span class="operator">&lt;</span>CountStates<span class="operator">&gt;</span> ptr<span class="operator">;</span><span class="type">
  95. unsigned int</span> count<span class="operator"> =</span><span class="int"> 0</span><span class="operator">;</span>
  97. CountStates<span class="operator">(</span>HOAConsumer<span class="operator">::</span>ptr next<span class="operator">) :</span> HOAIntermediate<span class="operator">(</span>next<span class="operator">) {
  98. }</span><span class="keyword">
  100. virtual</span><span class="type"> void</span> addState<span class="operator">(</span><span class="type">unsigned int</span> id<span class="operator">,</span>
  101. std<span class="operator">::</span>shared_ptr<span class="operator">&lt;</span>std<span class="operator">::</span>string<span class="operator">&gt;</span> info<span class="operator">,</span>
  102. label_expr<span class="operator">::</span>ptr labelExpr<span class="operator">,</span>
  103. std<span class="operator">::</span>shared_ptr<span class="operator">&lt;</span>int_list<span class="operator">&gt;</span> accSignature<span class="operator">)</span> override<span class="operator"> {</span>
  104. count<span class="operator">++;</span>
  105. next<span class="operator">-&gt;</span>addState<span class="operator">(</span>id<span class="operator">,</span> info<span class="operator">,</span> labelExpr<span class="operator">,</span> accSignature<span class="operator">);
  106. }
  107. };</span><span class="comment">
  109. /** Demonstrating the use of HOAIntermediates */</span><span class="type">
  110. int</span><span class="keyword"> main</span><span class="operator">(</span><span class="type">int</span> argc<span class="operator">,</span><span class="keyword"> const</span><span class="type"> char</span><span class="operator">*</span> argv<span class="operator">[]) {</span>
  111. HOAConsumer<span class="operator">::</span>ptr hoaNull<span class="operator">(</span><span class="keyword">new</span> HOAConsumerNull<span class="operator">());</span>
  112. CountStates<span class="operator">::</span>ptr counter<span class="operator">(</span><span class="keyword">new</span> CountStates<span class="operator">(</span>hoaNull<span class="operator">));</span><span class="flow">
  114. try</span><span class="operator"> {</span>
  116. HOAParser<span class="operator">::</span>parse<span class="operator">(</span>std<span class="operator">::</span>cin<span class="operator">,</span> counter<span class="operator">);</span>
  117. std<span class="operator">::</span>cout<span class="operator"> &lt;&lt;</span><span class="string"> "Number of state definitions = "</span><span class="operator"> &lt;&lt;</span> counter<span class="operator">-&gt;</span>count<span class="operator"> &lt;&lt;</span> std<span class="operator">::</span>endl<span class="operator">;
  119. }</span><span class="flow"> catch</span><span class="operator"> (</span>std<span class="operator">::</span>exception<span class="operator">&amp;</span> e<span class="operator">) {</span>
  120. std<span class="operator">::</span>cerr<span class="operator"> &lt;&lt;</span> e<span class="operator">.</span>what<span class="operator">() &lt;&lt;</span> std<span class="operator">::</span>endl<span class="operator">;</span><span class="flow">
  121. return</span><span class="int"> 1</span><span class="operator">;
  122. }</span><span class="flow">
  123. return</span><span class="int"> 0</span><span class="operator">;
  124. }</span>
  125. </pre>
  126. </div>
  128. <p>We derive <span class="classname">CountStates</span> from <span class="classname">HOAIntermediate</span>.
  129. Its constructor takes the next <span class="classname">HOAConsumer</span> in the chain, which can
  130. again be a <span class="classname">HOAIntermediate</span>. Here, we are passing a
  131. <span class="classname">HOAConsumerNull</span> object, which does nothing when called, acting as a "no-operation"
  132. end of the consumer chain. Inside the <span class="classname">CountStates</span>, we override the
  133. <span class="classname">addState</span> method, which is called for each <em>State:</em>
  134. definition in the automaton.
  135. We count the number of definitions and pass along the arguments to the next consumer.
  136. In the end, we just output the count of the definitions.
  137. </p>
  140. <h2>The HOAConsumer API</h2>
  142. <p>
  143. A good starting point for learning about the HOAConsumer API is the
  144. <a
  145. href="http://automata.tools/hoa/cpphoafparser/docs/api-html/classcpphoafparser_1_1_h_o_a_consumer.html">documentation of the HOAConsumer interface</a>
  146. as well as the rest of the <a href="http://automata.tools/hoa/cpphoafparser/docs/api-html/index.html">API documentation</a>.
  148. <p>Another good introduction is the source code of the <span class="classname">HOAConsumerPrint</span> class,
  149. as it translates back from the method calls in the <span class="classname">HOAConsumer</span> interface to the
  150. textual representation of the HOA format.
  151. </p>
  153. <p>Some further tidbits that might be useful:</p>
  154. <ul>
  155. <li>The boolean expressions for the explicit transition labels and the acceptance condition
  156. are represented by
  157. <a href="http://automata.tools/hoa/cpphoafparser/docs/api-html/classcpphoafparser_1_1_boolean_expression.html"><span class="classname">BooleanExpression</span></a>,
  158. with appropriate <span class="classname">Atoms</span> for the leaf nodes in the abstract syntax tree.
  159. The <span class="classname">BooleanExpressions</span> are designed to
  160. be <em>immutable</em>. Therefore, subtrees can be safely shared between expressions.
  161. </li>
  162. <li>
  163. If you encounter an error inside one of the <span class="classname">HOAConsumer</span> method calls, throw an
  164. <a href="http://automata.tools/hoa/cpphoafparser/docs/api-html/classcpphoafparser_1_1_h_o_a_consumer_exception.html">HOAConsumerException</a>.
  165. </li>
  166. <li>Memory managment is generally handled via <span class="classname">shared_ptr</span> pointers.</li>
  167. <li>
  168. To trace the method calls into a <span class="classname">HOAConsumer</span> or <span class="classname">HOAIntermediate</span>,
  169. wrap it into a <a href="http://automata.tools//hoa/cpphoafparser/docs/api-html/classcpphoafparser_1_1_h_o_a_intermediate_trace.html"><span class="classname">HOAIntermediateTrace</span></a>
  170. object. This will print all the function invocations to the standard output, including the parameters.
  171. </li>
  172. </ul>
  174. <hr>
  175. <p>If you have further questions, find bugs or want to tell
  176. us about your use of the cpphoafparser library, please feel free to contact us!</p>
  178. <p>(c) 2015-2016
  179. Joachim Klein &lt;klein&#064;tcs.inf.tu-dresden.de&gt;,
  180. David M&uuml;ller &lt;david.mueller&#064;tcs.inf.tu-dresden.de&gt;
  182. </body>
  183. </html>