docs/sphinx_docs/_build/html/stack.html

   1
   2 <!DOCTYPE html>
   3
   4 <html>
   5   <head>
   6     <meta charset="utf-8" />
   7     <title>Stack or Quote or Sequence or List… &#8212; Thun 0.3.0 documentation</title>
   8     <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
   9     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  10     <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
  11     <script src="_static/jquery.js"></script>
  12     <script src="_static/underscore.js"></script>
  13     <script src="_static/doctools.js"></script>
  14     <script src="_static/language_data.js"></script>
  15     <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
  16     <link rel="index" title="Index" href="genindex.html" />
  17     <link rel="search" title="Search" href="search.html" />
  18     <link rel="next" title="Parsing Text into Joy Expressions" href="parser.html" />
  19     <link rel="prev" title="Joy Interpreter" href="joy.html" />
  20
  21   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  22
  23
  24   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  25
  26   </head><body>
  27
  28
  29     <div class="document">
  30       <div class="documentwrapper">
  31         <div class="bodywrapper">
  32
  33
  34           <div class="body" role="main">
  35
  36   <div class="section" id="stack-or-quote-or-sequence-or-list">
  37 <h1>Stack or Quote or Sequence or List…<a class="headerlink" href="#stack-or-quote-or-sequence-or-list" title="Permalink to this headline">¶</a></h1>
  38 <div class="section" id="module-joy.utils.stack">
  39 <span id="joy-utils-stack"></span><h2><code class="docutils literal notranslate"><span class="pre">joy.utils.stack</span></code><a class="headerlink" href="#module-joy.utils.stack" title="Permalink to this headline">¶</a></h2>
  40 <p>When talking about Joy we use the terms “stack”, “quote”, “sequence”,
  41 “list”, and others to mean the same thing: a simple linear datatype that
  42 permits certain operations such as iterating and pushing and popping
  43 values from (at least) one end.</p>
  44 <p>There is no “Stack” Python class, instead we use the  <a class="reference external" href="https://en.wikipedia.org/wiki/Cons#Lists">cons list</a>, a
  45 venerable two-tuple recursive sequence datastructure, where the
  46 empty tuple <code class="docutils literal notranslate"><span class="pre">()</span></code> is the empty stack and <code class="docutils literal notranslate"><span class="pre">(head,</span> <span class="pre">rest)</span></code> gives the recursive
  47 form of a stack with one or more items on it:</p>
  48 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">stack</span> <span class="o">:=</span> <span class="p">()</span> <span class="o">|</span> <span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span>
  49 </pre></div>
  50 </div>
  51 <p>Putting some numbers onto a stack:</p>
  52 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">()</span>
  53 <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">())</span>
  54 <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">()))</span>
  55 <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">())))</span>
  56 <span class="o">...</span>
  57 </pre></div>
  58 </div>
  59 <p>Python has very nice “tuple packing and unpacking” in its syntax which
  60 means we can directly “unpack” the expected arguments to a Joy function.</p>
  61 <p>For example:</p>
  62 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dup</span><span class="p">((</span><span class="n">head</span><span class="p">,</span> <span class="n">tail</span><span class="p">)):</span>
  63         <span class="k">return</span> <span class="n">head</span><span class="p">,</span> <span class="p">(</span><span class="n">head</span><span class="p">,</span> <span class="n">tail</span><span class="p">)</span>
  64 </pre></div>
  65 </div>
  66 <p>We replace the argument “stack” by the expected structure of the stack,
  67 in this case “(head, tail)”, and Python takes care of unpacking the
  68 incoming tuple and assigning values to the names.  (Note that Python
  69 syntax doesn’t require parentheses around tuples used in expressions
  70 where they would be redundant.)</p>
  71 <p>Unfortunately, the Sphinx documentation generator, which is used to generate this
  72 web page, doesn’t handle tuples in the function parameters.  And in Python 3, this
  73 syntax was removed entirely.  Instead you would have to write:</p>
  74 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dup</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
  75         <span class="n">head</span><span class="p">,</span> <span class="n">tail</span> <span class="o">=</span> <span class="n">stack</span>
  76         <span class="k">return</span> <span class="n">head</span><span class="p">,</span> <span class="p">(</span><span class="n">head</span><span class="p">,</span> <span class="n">tail</span><span class="p">)</span>
  77 </pre></div>
  78 </div>
  79 <p>We have two very simple functions, one to build up a stack from a Python
  80 iterable and another to iterate through a stack and yield its items
  81 one-by-one in order.  There are also two functions to generate string representations
  82 of stacks.  They only differ in that one prints the terms in stack from left-to-right while the other prints from right-to-left.  In both functions <em>internal stacks</em> are
  83 printed left-to-right.  These functions are written to support <a class="reference internal" href="pretty.html"><span class="doc">Tracing Joy Execution</span></a>.</p>
  84 <dl class="py function">
  85 <dt id="joy.utils.stack.concat">
  86 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">concat</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">quote</span></em>, <em class="sig-param"><span class="n">expression</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#concat"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.concat" title="Permalink to this definition">¶</a></dt>
  87 <dd><p>Concatinate quote onto expression.</p>
  88 <p>In joy [1 2] [3 4] would become [1 2 3 4].</p>
  89 <dl class="field-list simple">
  90 <dt class="field-odd">Parameters</dt>
  91 <dd class="field-odd"><ul class="simple">
  92 <li><p><strong>quote</strong> (<em>stack</em>) – A stack.</p></li>
  93 <li><p><strong>expression</strong> (<em>stack</em>) – A stack.</p></li>
  94 </ul>
  95 </dd>
  96 <dt class="field-even">Raises</dt>
  97 <dd class="field-even"><p><strong>RuntimeError</strong> – if quote is larger than sys.getrecursionlimit().</p>
  98 </dd>
  99 <dt class="field-odd">Return type</dt>
 100 <dd class="field-odd"><p>stack</p>
 101 </dd>
 102 </dl>
 103 </dd></dl>
 104
 105 <dl class="py function">
 106 <dt id="joy.utils.stack.expression_to_string">
 107 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">expression_to_string</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">expression</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#expression_to_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.expression_to_string" title="Permalink to this definition">¶</a></dt>
 108 <dd><p>Return a “pretty print” string for a expression.</p>
 109 <p>The items are written left-to-right:</p>
 110 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">top</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="o">...</span><span class="p">))</span> <span class="o">-&gt;</span> <span class="s1">&#39;top second ...&#39;</span>
 111 </pre></div>
 112 </div>
 113 <dl class="field-list simple">
 114 <dt class="field-odd">Parameters</dt>
 115 <dd class="field-odd"><p><strong>expression</strong> (<em>stack</em>) – A stack.</p>
 116 </dd>
 117 <dt class="field-even">Return type</dt>
 118 <dd class="field-even"><p>str</p>
 119 </dd>
 120 </dl>
 121 </dd></dl>
 122
 123 <dl class="py function">
 124 <dt id="joy.utils.stack.iter_stack">
 125 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">iter_stack</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">stack</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#iter_stack"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.iter_stack" title="Permalink to this definition">¶</a></dt>
 126 <dd><p>Iterate through the items on the stack.</p>
 127 <dl class="field-list simple">
 128 <dt class="field-odd">Parameters</dt>
 129 <dd class="field-odd"><p><strong>stack</strong> (<em>stack</em>) – A stack.</p>
 130 </dd>
 131 <dt class="field-even">Return type</dt>
 132 <dd class="field-even"><p>iterator</p>
 133 </dd>
 134 </dl>
 135 </dd></dl>
 136
 137 <dl class="py function">
 138 <dt id="joy.utils.stack.list_to_stack">
 139 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">list_to_stack</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">el</span></em>, <em class="sig-param"><span class="n">stack</span><span class="o">=</span><span class="default_value">()</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#list_to_stack"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.list_to_stack" title="Permalink to this definition">¶</a></dt>
 140 <dd><p>Convert a Python list (or other sequence) to a Joy stack:</p>
 141 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="p">())))</span>
 142 </pre></div>
 143 </div>
 144 <dl class="field-list simple">
 145 <dt class="field-odd">Parameters</dt>
 146 <dd class="field-odd"><ul class="simple">
 147 <li><p><strong>el</strong> (<em>list</em>) – A Python list or other sequence (iterators and generators
 148 won’t work because <code class="docutils literal notranslate"><span class="pre">reverse()</span></code> is called on <code class="docutils literal notranslate"><span class="pre">el</span></code>.)</p></li>
 149 <li><p><strong>stack</strong> (<em>stack</em>) – A stack, optional, defaults to the empty stack.</p></li>
 150 </ul>
 151 </dd>
 152 <dt class="field-even">Return type</dt>
 153 <dd class="field-even"><p>stack</p>
 154 </dd>
 155 </dl>
 156 </dd></dl>
 157
 158 <dl class="py function">
 159 <dt id="joy.utils.stack.pick">
 160 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">pick</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">stack</span></em>, <em class="sig-param"><span class="n">n</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#pick"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.pick" title="Permalink to this definition">¶</a></dt>
 161 <dd><p>Return the nth item on the stack.</p>
 162 <dl class="field-list simple">
 163 <dt class="field-odd">Parameters</dt>
 164 <dd class="field-odd"><ul class="simple">
 165 <li><p><strong>stack</strong> (<em>stack</em>) – A stack.</p></li>
 166 <li><p><strong>n</strong> (<em>int</em>) – An index into the stack.</p></li>
 167 </ul>
 168 </dd>
 169 <dt class="field-even">Raises</dt>
 170 <dd class="field-even"><ul class="simple">
 171 <li><p><strong>ValueError</strong> – if <code class="docutils literal notranslate"><span class="pre">n</span></code> is less than zero.</p></li>
 172 <li><p><strong>IndexError</strong> – if <code class="docutils literal notranslate"><span class="pre">n</span></code> is equal to or greater than the length of <code class="docutils literal notranslate"><span class="pre">stack</span></code>.</p></li>
 173 </ul>
 174 </dd>
 175 <dt class="field-odd">Return type</dt>
 176 <dd class="field-odd"><p>whatever</p>
 177 </dd>
 178 </dl>
 179 </dd></dl>
 180
 181 <dl class="py function">
 182 <dt id="joy.utils.stack.stack_to_string">
 183 <code class="sig-prename descclassname">joy.utils.stack.</code><code class="sig-name descname">stack_to_string</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">stack</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#stack_to_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#joy.utils.stack.stack_to_string" title="Permalink to this definition">¶</a></dt>
 184 <dd><p>Return a “pretty print” string for a stack.</p>
 185 <p>The items are written right-to-left:</p>
 186 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">top</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="o">...</span><span class="p">))</span> <span class="o">-&gt;</span> <span class="s1">&#39;... second top&#39;</span>
 187 </pre></div>
 188 </div>
 189 <dl class="field-list simple">
 190 <dt class="field-odd">Parameters</dt>
 191 <dd class="field-odd"><p><strong>stack</strong> (<em>stack</em>) – A stack.</p>
 192 </dd>
 193 <dt class="field-even">Return type</dt>
 194 <dd class="field-even"><p>str</p>
 195 </dd>
 196 </dl>
 197 </dd></dl>
 198
 199 </div>
 200 </div>
 201
 202
 203           </div>
 204
 205         </div>
 206       </div>
 207       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 208         <div class="sphinxsidebarwrapper">
 209 <h1 class="logo"><a href="index.html">Thun</a></h1>
 210
 211
 212
 213
 214
 215
 216
 217
 218 <h3>Navigation</h3>
 219 <ul class="current">
 220 <li class="toctree-l1"><a class="reference internal" href="notebooks/Intro.html">Thun: Joy in Python</a></li>
 221 <li class="toctree-l1"><a class="reference internal" href="joy.html">Joy Interpreter</a></li>
 222 <li class="toctree-l1 current"><a class="current reference internal" href="#">Stack or Quote or Sequence or List…</a><ul>
 223 <li class="toctree-l2"><a class="reference internal" href="#module-joy.utils.stack"><code class="docutils literal notranslate"><span class="pre">joy.utils.stack</span></code></a></li>
 224 </ul>
 225 </li>
 226 <li class="toctree-l1"><a class="reference internal" href="parser.html">Parsing Text into Joy Expressions</a></li>
 227 <li class="toctree-l1"><a class="reference internal" href="pretty.html">Tracing Joy Execution</a></li>
 228 <li class="toctree-l1"><a class="reference internal" href="library.html">Function Reference</a></li>
 229 <li class="toctree-l1"><a class="reference internal" href="lib.html">Functions Grouped by, er, Function with Examples</a></li>
 230 <li class="toctree-l1"><a class="reference internal" href="types.html">Type Inference of Joy Expressions</a></li>
 231 <li class="toctree-l1"><a class="reference internal" href="notebooks/index.html">Essays about Programming in Joy</a></li>
 232 </ul>
 233
 234 <div class="relations">
 235 <h3>Related Topics</h3>
 236 <ul>
 237   <li><a href="index.html">Documentation overview</a><ul>
 238       <li>Previous: <a href="joy.html" title="previous chapter">Joy Interpreter</a></li>
 239       <li>Next: <a href="parser.html" title="next chapter">Parsing Text into Joy Expressions</a></li>
 240   </ul></li>
 241 </ul>
 242 </div>
 243 <div id="searchbox" style="display: none" role="search">
 244   <h3 id="searchlabel">Quick search</h3>
 245     <div class="searchformwrapper">
 246     <form class="search" action="search.html" method="get">
 247       <input type="text" name="q" aria-labelledby="searchlabel" />
 248       <input type="submit" value="Go" />
 249     </form>
 250     </div>
 251 </div>
 252 <script>$('#searchbox').show(0);</script>
 253
 254
 255
 256
 257
 258
 259
 260
 261         </div>
 262       </div>
 263       <div class="clearer"></div>
 264     </div>
 265     <div class="footer" role="contentinfo">
 266 <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
 267 <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" />
 268 </a>
 269 <br />
 270 <span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">Thun Documentation</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://joypy.osdn.io/" property="cc:attributionName" rel="cc:attributionURL">Simon Forman</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://osdn.net/projects/joypy/" rel="dct:source">https://osdn.net/projects/joypy/</a>.
 271       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.0.2.
 272     </div>
 273
 274   </body>
 275 </html>