sphinx/cli.html

   1
   2 <!DOCTYPE html>
   3
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5   <head>
   6     <meta charset="utf-8" />
   7     <title>The cli module &#8212; πyacc  documentation</title>
   8     <link rel="stylesheet" href="_static/classic.css" type="text/css" />
   9     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  10
  11     <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
  12     <script src="_static/jquery.js"></script>
  13     <script src="_static/underscore.js"></script>
  14     <script src="_static/doctools.js"></script>
  15     <script src="_static/language_data.js"></script>
  16
  17     <link rel="index" title="Index" href="genindex.html" />
  18     <link rel="search" title="Search" href="search.html" />
  19     <link rel="next" title="The element module" href="element.html" />
  20     <link rel="prev" title="The bison_lr1dfa module" href="bison_lr1dfa.html" />
  21   </head><body>
  22     <div class="related" role="navigation" aria-label="related navigation">
  23       <h3>Navigation</h3>
  24       <ul>
  25         <li class="right" style="margin-right: 10px">
  26           <a href="genindex.html" title="General Index"
  27              accesskey="I">index</a></li>
  28         <li class="right" >
  29           <a href="py-modindex.html" title="Python Module Index"
  30              >modules</a> |</li>
  31         <li class="right" >
  32           <a href="element.html" title="The element module"
  33              accesskey="N">next</a> |</li>
  34         <li class="right" >
  35           <a href="bison_lr1dfa.html" title="The bison_lr1dfa module"
  36              accesskey="P">previous</a> |</li>
  37         <li class="nav-item nav-item-0"><a href="index.html">πyacc  documentation</a> &#187;</li>
  38       </ul>
  39     </div>
  40
  41     <div class="document">
  42       <div class="documentwrapper">
  43         <div class="bodywrapper">
  44           <div class="body" role="main">
  45
  46   <div class="section" id="module-ndcode.piyacc.cli">
  47 <span id="the-cli-module"></span><h1>The <code class="docutils literal notranslate"><span class="pre">cli</span></code> module<a class="headerlink" href="#module-ndcode.piyacc.cli" title="Permalink to this headline">�</a></h1>
  48 <p>Main module for the <code class="docutils literal notranslate"><span class="pre">piyacc</span></code> command-line utility.</p>
  49 <p>Contains the <code class="docutils literal notranslate"><span class="pre">main()</span></code> function as required by <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>, so that when
  50 the package is installed, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> can put a wrapper in <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code> or
  51 similar place. Can also be executed directly and will call <code class="docutils literal notranslate"><span class="pre">main()</span></code> itself.</p>
  52 <dl class="function">
  53 <dt id="ndcode.piyacc.cli.main">
  54 <code class="sig-prename descclassname">ndcode.piyacc.cli.</code><code class="sig-name descname">main</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#ndcode.piyacc.cli.main" title="Permalink to this definition">�</a></dt>
  55 <dd><p>Runs the following steps:</p>
  56 <ol class="arabic simple">
  57 <li><p>Processing the command line</p></li>
  58 <li><p>Parsing and analyzing the YACC/Bison-compatible input file</p></li>
  59 <li><p>Generating a parser definition and corresponding automaton</p></li>
  60 <li><p>Writing C or Python code to implement the requested parser</p></li>
  61 </ol>
  62 </dd></dl>
  63
  64 <div class="section" id="design-of-the-module">
  65 <h2>Design of the module<a class="headerlink" href="#design-of-the-module" title="Permalink to this headline">�</a></h2>
  66 <p>Step 1 is fairly straightforward Python code using <code class="docutils literal notranslate"><span class="pre">getopt.getopt()</span></code>.</p>
  67 <p>Step 2 is more complicated, it uses a πlex/πyacc/πtree generated parser which
  68 automatically creates an abstract syntax tree representing the input, and then
  69 it performs several passes over the tree to extract the needed information such
  70 as lists of terminals and non-terminals, the rules, the alternatives of each
  71 rule, and the symbols and/or actions and other directives of each alternative.
  72 How it does this is somewhat beyond the scope of this documentation, as we
  73 would first have to refer you to tutorials in how to use πlex/πyacc/πtree.</p>
  74 <p>Step 3 is the focus of this document. Internally it uses a Python class library
  75 that we have developed for dealing with LR1 grammars and automata. See the
  76 classes <code class="docutils literal notranslate"><span class="pre">ndcode.piyacc.lr1.LR1</span></code> and <code class="docutils literal notranslate"><span class="pre">ndcode.piyacc.lr1dfa.LR1DFA</span></code>. These
  77 classes are general-purpose and there is nothing to stop you pulling them out
  78 and using them in your project (subject to the license which is GPLv2). At the
  79 moment the classes are only used for generating automata to be used later, but
  80 there are commented functions in each class that can perform parsing directly.</p>
  81 <p>Step 4 is fairly straightforward Python code using <code class="docutils literal notranslate"><span class="pre">str.format()</span></code>. Basically
  82 it reads a skeleton file line-by-line looking for special lines similar to:</p>
  83 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># GENERATE SECTION1</span>
  84 </pre></div>
  85 </div>
  86 <p>and then expands these into a sequence like:</p>
  87 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># GENERATE SECTION1 BEGIN</span>
  88 <span class="o">...</span>
  89 <span class="c1"># GENERATE SECTION1 END</span>
  90 </pre></div>
  91 </div>
  92 <p>where the middle part (denoted <code class="docutils literal notranslate"><span class="pre">...</span></code>) is printed with a <code class="docutils literal notranslate"><span class="pre">str.format()</span></code>
  93 format string containing the C or Python code to be inserted into the skeleton.</p>
  94 <p>Often this C or Python code will contain repetitive material (e.g. switch cases
  95 or action handler functions or similar) and these are sent into the format
  96 string as an string argument, which is a <code class="docutils literal notranslate"><span class="pre">str.join()</span></code> of a list of items,
  97 each formatted in turn with <code class="docutils literal notranslate"><span class="pre">str.format()</span></code>. These may also contain repetitive
  98 material embedded in a similar manner, up to several levels deep. To illustrate
  99 how this works, here’s an example where we are given a list of strings in the
 100 variable <code class="docutils literal notranslate"><span class="pre">lines</span></code> and we generate C code to write them out with <code class="docutils literal notranslate"><span class="pre">fwrite()</span></code>:</p>
 101 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span>
 102   <span class="sd">&#39;&#39;&#39;#include &lt;stdio.h&gt;</span>
 103
 104 <span class="sd">int main(void) {{</span>
 105 <span class="sd">{0:s}}}</span>
 106 <span class="sd">&#39;&#39;&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
 107     <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
 108       <span class="p">[</span>
 109         <span class="s1">&#39;  fwrite(stdout, 1, </span><span class="si">{0:d}</span><span class="s1">, &quot;</span><span class="si">{1:s}</span><span class="s1">&quot;);</span><span class="se">\n</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
 110           <span class="nb">len</span><span class="p">(</span><span class="n">line</span><span class="p">),</span>
 111           <span class="n">line</span>
 112         <span class="p">)</span>
 113         <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span>
 114       <span class="p">]</span>
 115     <span class="p">)</span>
 116   <span class="p">)</span>
 117 <span class="p">)</span>
 118 </pre></div>
 119 </div>
 120 </div>
 121 </div>
 122
 123
 124           </div>
 125         </div>
 126       </div>
 127       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 128         <div class="sphinxsidebarwrapper">
 129   <h3><a href="index.html">Table of Contents</a></h3>
 130   <ul>
 131 <li><a class="reference internal" href="#">The <code class="docutils literal notranslate"><span class="pre">cli</span></code> module</a><ul>
 132 <li><a class="reference internal" href="#design-of-the-module">Design of the module</a></li>
 133 </ul>
 134 </li>
 135 </ul>
 136
 137   <h4>Previous topic</h4>
 138   <p class="topless"><a href="bison_lr1dfa.html"
 139                         title="previous chapter">The <code class="docutils literal notranslate"><span class="pre">bison_lr1dfa</span></code> module</a></p>
 140   <h4>Next topic</h4>
 141   <p class="topless"><a href="element.html"
 142                         title="next chapter">The <code class="docutils literal notranslate"><span class="pre">element</span></code> module</a></p>
 143   <div role="note" aria-label="source link">
 144     <h3>This Page</h3>
 145     <ul class="this-page-menu">
 146       <li><a href="_sources/cli.rst.txt"
 147             rel="nofollow">Show Source</a></li>
 148     </ul>
 149    </div>
 150 <div id="searchbox" style="display: none" role="search">
 151   <h3 id="searchlabel">Quick search</h3>
 152     <div class="searchformwrapper">
 153     <form class="search" action="search.html" method="get">
 154       <input type="text" name="q" aria-labelledby="searchlabel" />
 155       <input type="submit" value="Go" />
 156     </form>
 157     </div>
 158 </div>
 159 <script>$('#searchbox').show(0);</script>
 160         </div>
 161       </div>
 162       <div class="clearer"></div>
 163     </div>
 164     <div class="related" role="navigation" aria-label="related navigation">
 165       <h3>Navigation</h3>
 166       <ul>
 167         <li class="right" style="margin-right: 10px">
 168           <a href="genindex.html" title="General Index"
 169              >index</a></li>
 170         <li class="right" >
 171           <a href="py-modindex.html" title="Python Module Index"
 172              >modules</a> |</li>
 173         <li class="right" >
 174           <a href="element.html" title="The element module"
 175              >next</a> |</li>
 176         <li class="right" >
 177           <a href="bison_lr1dfa.html" title="The bison_lr1dfa module"
 178              >previous</a> |</li>
 179         <li class="nav-item nav-item-0"><a href="index.html">πyacc  documentation</a> &#187;</li>
 180       </ul>
 181     </div>
 182     <div class="footer" role="contentinfo">
 183         &#169; Copyright 2020, NDCODE project.
 184       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.1.
 185     </div>
 186   </body>
 187 </html>