sforman
/
Thun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Thun/docs/sphinx_docs/_build/html/stack.html

287 lines
19 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Stack or Quote or Sequence or List… &#8212; Thun 0.4.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Parsing Text into Joy Expressions" href="parser.html" />
<link rel="prev" title="Joy Interpreter" href="joy.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="stack-or-quote-or-sequence-or-list">
<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>
<section id="module-joy.utils.stack">
<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>
<p>When talking about Joy we use the terms “stack”, “quote”, “sequence”,
“list”, and others to mean the same thing: a simple linear datatype that
permits certain operations such as iterating and pushing and popping
values from (at least) one end.</p>
<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
venerable two-tuple recursive sequence datastructure, where the
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 form of a stack with one or more items on it:</p>
<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>
</pre></div>
</div>
<p>Putting some numbers onto a stack:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">()</span>
<span class="p">(</span><span class="mi">1</span><span class="p">,</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>
<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>
<span class="o">...</span>
</pre></div>
</div>
<p>Python has very nice “tuple packing and unpacking” in its syntax which
means we can directly “unpack” the expected arguments to a Joy function.</p>
<p>For example:</p>
<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>
<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>
</pre></div>
</div>
<p>We replace the argument “stack” by the expected structure of the stack,
in this case “(head, tail)”, and Python takes care of unpacking the
incoming tuple and assigning values to the names. (Note that Python
syntax doesn’t require parentheses around tuples used in expressions
where they would be redundant.)</p>
<p>Unfortunately, the Sphinx documentation generator, which is used to generate this
web page, doesn’t handle tuples in the function parameters. And in Python 3, this
syntax was removed entirely. Instead you would have to write:</p>
<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>
<span class="n">head</span><span class="p">,</span> <span class="n">tail</span> <span class="o">=</span> <span class="n">stack</span>
<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>
</pre></div>
</div>
<p>We have two very simple functions, one to build up a stack from a Python
iterable and another to iterate through a stack and yield its items
one-by-one in order. There are also two functions to generate string representations
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
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>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.concat">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">concat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">quote</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expression</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#concat"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.concat" title="Permalink to this definition"></a></dt>
<dd><p>Concatinate quote onto expression.</p>
<p>In joy [1 2] [3 4] would become [1 2 3 4].</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>quote</strong> (<em>stack</em>) – A stack.</p></li>
<li><p><strong>expression</strong> (<em>stack</em>) – A stack.</p></li>
</ul>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>RuntimeError</strong> – if quote is larger than sys.getrecursionlimit().</p>
</dd>
<dt class="field-odd">Return type</dt>
<dd class="field-odd"><p>stack</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.dnd">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">dnd</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_index</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">to_index</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#dnd"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.dnd" title="Permalink to this definition"></a></dt>
<dd><p>Given a stack and two indices return a rearranged stack.
First remove the item at from_index and then insert it at to_index,
the second index is relative to the stack after removal of the item
at from_index.</p>
<p>This function reuses all of the items and as much of the stack as it
can. It’s meant to be used by remote clients to support drag-n-drop
rearranging of the stack from e.g. the StackListbox.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.expression_to_string">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">expression_to_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">expression</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#expression_to_string"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.expression_to_string" title="Permalink to this definition"></a></dt>
<dd><p>Return a “pretty print” string for a expression.</p>
<p>The items are written left-to-right:</p>
<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>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>expression</strong> (<em>stack</em>) – A stack.</p>
</dd>
<dt class="field-even">Return type</dt>
<dd class="field-even"><p>str</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.iter_stack">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">iter_stack</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#iter_stack"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.iter_stack" title="Permalink to this definition"></a></dt>
<dd><p>Iterate through the items on the stack.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>stack</strong> (<em>stack</em>) – A stack.</p>
</dd>
<dt class="field-even">Return type</dt>
<dd class="field-even"><p>iterator</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.list_to_stack">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">list_to_stack</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">el</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stack</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#list_to_stack"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.list_to_stack" title="Permalink to this definition"></a></dt>
<dd><p>Convert a Python list (or other sequence) to a Joy stack:</p>
<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>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>el</strong> (<em>list</em>) – A Python list or other sequence (iterators and generators
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>
<li><p><strong>stack</strong> (<em>stack</em>) – A stack, optional, defaults to the empty stack.</p></li>
</ul>
</dd>
<dt class="field-even">Return type</dt>
<dd class="field-even"><p>stack</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.pick">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">pick</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">n</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#pick"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.pick" title="Permalink to this definition"></a></dt>
<dd><p>Return the nth item on the stack.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>stack</strong> (<em>stack</em>) – A stack.</p></li>
<li><p><strong>n</strong> (<em>int</em>) – An index into the stack.</p></li>
</ul>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>ValueError</strong> – if <code class="docutils literal notranslate"><span class="pre">n</span></code> is less than zero.</p></li>
<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>
</ul>
</dd>
<dt class="field-odd">Return type</dt>
<dd class="field-odd"><p>whatever</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="joy.utils.stack.stack_to_string">
<span class="sig-prename descclassname"><span class="pre">joy.utils.stack.</span></span><span class="sig-name descname"><span class="pre">stack_to_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/joy/utils/stack.html#stack_to_string"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#joy.utils.stack.stack_to_string" title="Permalink to this definition"></a></dt>
<dd><p>Return a “pretty print” string for a stack.</p>
<p>The items are written right-to-left:</p>
<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>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>stack</strong> (<em>stack</em>) – A stack.</p>
</dd>
<dt class="field-even">Return type</dt>
<dd class="field-even"><p>str</p>
</dd>
</dl>
</dd></dl>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Thun</a></h1>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="notebooks/Intro.html">Thun: Joy in Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="joy.html">Joy Interpreter</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Stack or Quote or Sequence or List…</a><ul>
<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>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="parser.html">Parsing Text into Joy Expressions</a></li>
<li class="toctree-l1"><a class="reference internal" href="pretty.html">Tracing Joy Execution</a></li>
<li class="toctree-l1"><a class="reference internal" href="library.html">Function Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="lib.html">Functions Grouped by, er, Function with Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Type Inference of Joy Expressions</a></li>
<li class="toctree-l1"><a class="reference internal" href="notebooks/index.html">Essays about Programming in Joy</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="joy.html" title="previous chapter">Joy Interpreter</a></li>
<li>Next: <a href="parser.html" title="next chapter">Parsing Text into Joy Expressions</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer" role="contentinfo">
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
<img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" />
</a>
<br />
<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>.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.4.0.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink