More docs changes.

2018-04-30 10:12:56 -07:00
parent f3b72b1938
commit 04e8f70dd2
17 changed files with 513 additions and 627 deletions
@@ -75,11 +75,11 @@
 <span class="sd">  or functions.  Literals are put onto the stack and functions are</span>
 <span class="sd">  executed.</span>

-
-<span class="sd">  :param quote stack: The stack.</span>
-<span class="sd">  :param quote expression: The expression to evaluate.</span>
-<span class="sd">  :param dict dictionary: A `dict` mapping names to Joy functions.</span>
+<span class="sd">  :param stack stack: The stack.</span>
+<span class="sd">  :param stack expression: The expression to evaluate.</span>
+<span class="sd">  :param dict dictionary: A ``dict`` mapping names to Joy functions.</span>
 <span class="sd">  :param function viewer: Optional viewer function.</span>
+<span class="sd">  :rtype: (stack, (), dictionary)</span>

 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">while</span> <span class="n">expression</span><span class="p">:</span>
@@ -100,6 +100,13 @@
 <div class="viewcode-block" id="run"><a class="viewcode-back" href="../../joy.html#joy.joy.run">[docs]</a><span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="n">stack</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">viewer</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
  <span class="sd">&#39;&#39;&#39;</span>
 <span class="sd">  Return the stack resulting from running the Joy code text on the stack.</span>
+
+<span class="sd">  :param str text: Joy code.</span>
+<span class="sd">  :param stack stack: The stack.</span>
+<span class="sd">  :param dict dictionary: A ``dict`` mapping names to Joy functions.</span>
+<span class="sd">  :param function viewer: Optional viewer function.</span>
+<span class="sd">  :rtype: (stack, (), dictionary)</span>
+
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="n">expression</span> <span class="o">=</span> <span class="n">text_to_expression</span><span class="p">(</span><span class="n">text</span><span class="p">)</span>
  <span class="k">return</span> <span class="n">joy</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">viewer</span><span class="p">)</span></div>
@@ -110,6 +117,11 @@
 <span class="sd">  Read-Evaluate-Print Loop</span>

 <span class="sd">  Accept input and run it on the stack, loop.</span>
+
+<span class="sd">  :param stack stack: The stack.</span>
+<span class="sd">  :param dict dictionary: A ``dict`` mapping names to Joy functions.</span>
+<span class="sd">  :rtype: stack</span>
+
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">if</span> <span class="n">dictionary</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
    <span class="n">dictionary</span> <span class="o">=</span> <span class="p">{}</span>
@@ -157,6 +157,13 @@
 <span class="s1">dudipd == dup dipd</span>
 <span class="s1">primrec == [i] genrec</span>
 <span class="s1">step_zero == 0 roll&gt; step</span>
+<span class="s1">direco == dip rest cons</span>
+<span class="s1">make_generator == [direco] cons [swap] swoncat cons</span>
+<span class="s1">gsra == 1 swap [over / + 2 /] cons [dup] swoncat make_generator</span>
+<span class="s1">_within_P == [first - abs] dip &lt;=</span>
+<span class="s1">_within_B == roll&lt; popop first</span>
+<span class="s1">_within_R == [popd x] dip</span>
+<span class="s1">within == x 0.000001 [_within_P] [_within_B] [_within_R] primrec</span>
 <span class="s1">&#39;&#39;&#39;</span>

 <span class="c1">##Zipper</span>
@@ -84,7 +84,7 @@
 <span class="sd">  Any unbalanced square brackets will raise a ParseError.</span>

 <span class="sd">  :param str text: Text to convert.</span>
-<span class="sd">  :rtype: quote</span>
+<span class="sd">  :rtype: stack</span>
 <span class="sd">  :raises ParseError: if the parse fails.</span>
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">return</span> <span class="n">_parse</span><span class="p">(</span><span class="n">_tokenize</span><span class="p">(</span><span class="n">text</span><span class="p">))</span></div>
@@ -51,7 +51,24 @@
 <span class="c1">#    along with Thun.  If not see &lt;http://www.gnu.org/licenses/&gt;.</span>
 <span class="c1">#</span>
 <span class="sd">&#39;&#39;&#39;</span>
-<span class="sd">Pretty printing support.</span>
+<span class="sd">Pretty printing support, e.g.::</span>
+
+<span class="sd">    Joy? 23 18 * 99 +</span>
+<span class="sd">           . 23 18 mul 99 add</span>
+<span class="sd">        23 . 18 mul 99 add</span>
+<span class="sd">     23 18 . mul 99 add</span>
+<span class="sd">       414 . 99 add</span>
+<span class="sd">    414 99 . add</span>
+<span class="sd">       513 . </span>
+
+<span class="sd">    513 &lt;-top</span>
+
+<span class="sd">    joy? </span>
+
+<span class="sd">On each line the stack is printed with the top to the right, then a ``.`` to</span>
+<span class="sd">represent the current locus of processing, then the pending expression to the</span>
+<span class="sd">left.</span>
+
 <span class="sd">&#39;&#39;&#39;</span>
 <span class="c1"># (Kinda clunky and hacky.  This should be swapped out in favor of much</span>
 <span class="c1"># smarter stuff.)</span>
@@ -62,29 +79,36 @@

 <div class="viewcode-block" id="TracePrinter"><a class="viewcode-back" href="../../../pretty.html#joy.utils.pretty_print.TracePrinter">[docs]</a><span class="k">class</span> <span class="nc">TracePrinter</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
  <span class="sd">&#39;&#39;&#39;</span>
-<span class="sd">  This is what does the formatting, e.g.::</span>
-
-<span class="sd">    Joy? 23 18 * 99 +</span>
-<span class="sd">           . 23 18 mul 99 add</span>
-<span class="sd">        23 . 18 mul 99 add</span>
-<span class="sd">     23 18 . mul 99 add</span>
-<span class="sd">       414 . 99 add</span>
-<span class="sd">    414 99 . add</span>
-<span class="sd">       513 . </span>
-
+<span class="sd">  This is what does the formatting.  You instantiate it and pass the ``viewer()``</span>
+<span class="sd">  method to the :py:func:`joy.joy.joy` function, then print it to see the</span>
+<span class="sd">  trace.</span>
 <span class="sd">  &#39;&#39;&#39;</span>

  <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">history</span> <span class="o">=</span> <span class="p">[]</span>

 <div class="viewcode-block" id="TracePrinter.viewer"><a class="viewcode-back" href="../../../pretty.html#joy.utils.pretty_print.TracePrinter.viewer">[docs]</a>  <span class="k">def</span> <span class="nf">viewer</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">):</span>
-    <span class="sd">&#39;&#39;&#39;Pass this method as the viewer to joy() function.&#39;&#39;&#39;</span>
+    <span class="sd">&#39;&#39;&#39;</span>
+<span class="sd">    Record the current stack and expression in the TracePrinter&#39;s history.</span>
+<span class="sd">    Pass this method as the ``viewer`` argument to the :py:func:`joy.joy.joy` function.</span>
+
+<span class="sd">    :param stack quote: A stack.</span>
+<span class="sd">    :param stack expression: A stack.</span>
+<span class="sd">    &#39;&#39;&#39;</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">history</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">))</span></div>

  <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">go</span><span class="p">())</span>

-  <span class="k">def</span> <span class="nf">go</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<div class="viewcode-block" id="TracePrinter.go"><a class="viewcode-back" href="../../../pretty.html#joy.utils.pretty_print.TracePrinter.go">[docs]</a>  <span class="k">def</span> <span class="nf">go</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+    <span class="sd">&#39;&#39;&#39;</span>
+<span class="sd">    Return a list of strings, one for each entry in the history, prefixed</span>
+<span class="sd">    with enough spaces to align all the interpreter dots.</span>
+
+<span class="sd">    This method is called internally by the ``__str__()`` method.</span>
+
+<span class="sd">    :rtype: list(str)</span>
+<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">max_stack_length</span> <span class="o">=</span> <span class="mi">0</span>
    <span class="n">lines</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">history</span><span class="p">:</span>
@@ -97,7 +121,7 @@
    <span class="k">return</span> <span class="p">[</span>  <span class="c1"># Prefix spaces to line up &#39;.&#39;s.</span>
      <span class="p">(</span><span class="s1">&#39; &#39;</span> <span class="o">*</span> <span class="p">(</span><span class="n">max_stack_length</span> <span class="o">-</span> <span class="n">length</span><span class="p">)</span> <span class="o">+</span> <span class="n">line</span><span class="p">)</span>
      <span class="k">for</span> <span class="n">length</span><span class="p">,</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span>
-      <span class="p">]</span>
+      <span class="p">]</span></div>

  <span class="k">def</span> <span class="nf">print_</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">try</span><span class="p">:</span>
@@ -51,12 +51,13 @@
 <span class="c1">#    along with Thun.  If not see &lt;http://www.gnu.org/licenses/&gt;.</span>
 <span class="c1">#</span>
 <span class="sd">&#39;&#39;&#39;</span>
-<span class="sd">When talking about Joy we use the terms &quot;stack&quot;, &quot;list&quot;, &quot;sequence&quot;,</span>
-<span class="sd">&quot;quote&quot; and others to mean the same thing: a simple linear datatype that</span>
+<span class="sd">When talking about Joy we use the terms &quot;stack&quot;, &quot;quote&quot;, &quot;sequence&quot;,</span>
+<span class="sd">&quot;list&quot;, and others to mean the same thing: a simple linear datatype that</span>
 <span class="sd">permits certain operations such as iterating and pushing and popping</span>
 <span class="sd">values from (at least) one end.</span>

-<span class="sd">We use the  `cons list`_, a venerable two-tuple recursive sequence datastructure, where the</span>
+<span class="sd">There is no &quot;Stack&quot; Python class, instead we use the  `cons list`_, a </span>
+<span class="sd">venerable two-tuple recursive sequence datastructure, where the</span>
 <span class="sd">empty tuple ``()`` is the empty stack and ``(head, rest)`` gives the recursive</span>
 <span class="sd">form of a stack with one or more items on it::</span>

@@ -84,33 +85,36 @@
 <span class="sd">syntax doesn&#39;t require parentheses around tuples used in expressions</span>
 <span class="sd">where they would be redundant.)</span>

+<span class="sd">Unfortunately, the Sphinx documentation generator, which is used to generate this</span>
+<span class="sd">web page, doesn&#39;t handle tuples in the function parameters.  And in Python 3, this</span>
+<span class="sd">syntax was removed entirely.  Instead you would have to write::</span>
+
+<span class="sd">  def dup(stack):</span>
+<span class="sd">    head, tail = stack</span>
+<span class="sd">    return head, (head, tail)</span>
+
+
+<span class="sd">We have two very simple functions, one to build up a stack from a Python</span>
+<span class="sd">iterable and another to iterate through a stack and yield its items</span>
+<span class="sd">one-by-one in order.  There are also two functions to generate string representations</span>
+<span class="sd">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 *internal stacks* are</span>
+<span class="sd">printed left-to-right.  These functions are written to support :doc:`../pretty`.</span>
+
 <span class="sd">.. _cons list: https://en.wikipedia.org/wiki/Cons#Lists</span>

 <span class="sd">&#39;&#39;&#39;</span>

-<span class="c1">##We have two very simple functions to build up a stack from a Python</span>
-<span class="c1">##iterable and also to iterate through a stack and yield its items</span>
-<span class="c1">##one-by-one in order, and two functions to generate string representations</span>
-<span class="c1">##of stacks::</span>
-<span class="c1">##</span>
-<span class="c1">##  list_to_stack()</span>
-<span class="c1">##</span>
-<span class="c1">##  iter_stack()</span>
-<span class="c1">##</span>
-<span class="c1">##  expression_to_string()  (prints left-to-right)</span>
-<span class="c1">##</span>
-<span class="c1">##  stack_to_string()  (prints right-to-left)</span>
-<span class="c1">##</span>
-<span class="c1">##</span>
-<span class="c1">##A word about the stack data structure.</span>
-
-

 <div class="viewcode-block" id="list_to_stack"><a class="viewcode-back" href="../../../stack.html#joy.utils.stack.list_to_stack">[docs]</a><span class="k">def</span> <span class="nf">list_to_stack</span><span class="p">(</span><span class="n">el</span><span class="p">,</span> <span class="n">stack</span><span class="o">=</span><span class="p">()):</span>
  <span class="sd">&#39;&#39;&#39;Convert a Python list (or other sequence) to a Joy stack::</span>

 <span class="sd">  [1, 2, 3] -&gt; (1, (2, (3, ())))</span>

+<span class="sd">  :param list el: A Python list or other sequence (iterators and generators</span>
+<span class="sd">       won&#39;t work because ``reverse()`` is called on ``el``.)</span>
+<span class="sd">  :param stack stack: A stack, optional, defaults to the empty stack.</span>
+<span class="sd">  :rtype: stack</span>
+
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="nb">reversed</span><span class="p">(</span><span class="n">el</span><span class="p">):</span>
    <span class="n">stack</span> <span class="o">=</span> <span class="n">item</span><span class="p">,</span> <span class="n">stack</span>
@@ -118,7 +122,11 @@


 <div class="viewcode-block" id="iter_stack"><a class="viewcode-back" href="../../../stack.html#joy.utils.stack.iter_stack">[docs]</a><span class="k">def</span> <span class="nf">iter_stack</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
-  <span class="sd">&#39;&#39;&#39;Iterate through the items on the stack.&#39;&#39;&#39;</span>
+  <span class="sd">&#39;&#39;&#39;Iterate through the items on the stack.</span>
+
+<span class="sd">  :param stack stack: A stack.</span>
+<span class="sd">  :rtype: iterator</span>
+<span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">while</span> <span class="n">stack</span><span class="p">:</span>
    <span class="n">item</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
    <span class="k">yield</span> <span class="n">item</span></div>
@@ -131,6 +139,9 @@
 <span class="sd">  The items are written right-to-left::</span>

 <span class="sd">    (top, (second, ...)) -&gt; &#39;... second top&#39;</span>
+
+<span class="sd">  :param stack stack: A stack.</span>
+<span class="sd">  :rtype: str</span>
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="n">f</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">stack</span><span class="p">:</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">stack</span><span class="p">)))</span>
  <span class="k">return</span> <span class="n">_to_string</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span></div>
@@ -143,6 +154,9 @@
 <span class="sd">  The items are written left-to-right::</span>

 <span class="sd">    (top, (second, ...)) -&gt; &#39;top second ...&#39;</span>
+
+<span class="sd">  :param stack expression: A stack.</span>
+<span class="sd">  :rtype: str</span>
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">return</span> <span class="n">_to_string</span><span class="p">(</span><span class="n">expression</span><span class="p">,</span> <span class="n">iter_stack</span><span class="p">)</span></div>

@@ -165,7 +179,16 @@
  <span class="sd">&#39;&#39;&#39;Concatinate quote onto expression.</span>

 <span class="sd">  In joy [1 2] [3 4] would become [1 2 3 4].</span>
+
+<span class="sd">  :param stack quote: A stack.</span>
+<span class="sd">  :param stack expression: A stack.</span>
+<span class="sd">  :raises RuntimeError: if quote is larger than sys.getrecursionlimit().</span>
+<span class="sd">  :rtype: stack</span>
 <span class="sd">  &#39;&#39;&#39;</span>
+  <span class="c1"># This is the fastest implementation, but will trigger</span>
+  <span class="c1"># RuntimeError: maximum recursion depth exceeded</span>
+  <span class="c1"># on quotes longer than sys.getrecursionlimit().</span>
+  <span class="k">return</span> <span class="p">(</span><span class="n">quote</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">pushback</span><span class="p">(</span><span class="n">quote</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">expression</span><span class="p">))</span> <span class="k">if</span> <span class="n">quote</span> <span class="k">else</span> <span class="n">expression</span></div>

  <span class="c1"># Original implementation.</span>

@@ -182,15 +205,17 @@
 <span class="c1">##    expression = item, expression</span>
 <span class="c1">##  return expression</span>

-  <span class="c1"># This is the fastest, but will trigger</span>
-  <span class="c1"># RuntimeError: maximum recursion depth exceeded</span>
-  <span class="c1"># on quotes longer than sys.getrecursionlimit().</span>
-  <span class="k">return</span> <span class="p">(</span><span class="n">quote</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">pushback</span><span class="p">(</span><span class="n">quote</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">expression</span><span class="p">))</span> <span class="k">if</span> <span class="n">quote</span> <span class="k">else</span> <span class="n">expression</span></div>


 <div class="viewcode-block" id="pick"><a class="viewcode-back" href="../../../stack.html#joy.utils.stack.pick">[docs]</a><span class="k">def</span> <span class="nf">pick</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
  <span class="sd">&#39;&#39;&#39;</span>
-<span class="sd">  Find the nth item on the stack. (Pick with zero is the same as &quot;dup&quot;.)</span>
+<span class="sd">  Return the nth item on the stack.</span>
+
+<span class="sd">  :param stack s: A stack.</span>
+<span class="sd">  :param int n: An index into the stack.</span>
+<span class="sd">  :raises ValueError: if ``n`` is less than zero.</span>
+<span class="sd">  :raises IndexError: if ``n`` is equal to or greater than the length of ``s``.</span>
+<span class="sd">  :rtype: whatever</span>
 <span class="sd">  &#39;&#39;&#39;</span>
  <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>
    <span class="k">raise</span> <span class="ne">ValueError</span>