Rebuild HTML docs.

2022-08-16 15:26:07 -07:00
parent f70a941be3
commit 4a5716d8b2
23 changed files with 139 additions and 92 deletions
@@ -58,9 +58,9 @@
 <span class="sd">&#39;&#39;&#39;</span>
 <span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="nb">input</span>
 <span class="kn">from</span> <span class="nn">traceback</span> <span class="kn">import</span> <span class="n">print_exc</span>
-<span class="kn">from</span> <span class="nn">.parser</span> <span class="kn">import</span> <span class="n">text_to_expression</span><span class="p">,</span> <span class="n">ParseError</span><span class="p">,</span> <span class="n">Symbol</span>
-<span class="kn">from</span> <span class="nn">.utils.stack</span> <span class="kn">import</span> <span class="n">stack_to_string</span>
-<span class="kn">from</span> <span class="nn">.utils.errors</span> <span class="kn">import</span> <span class="p">(</span>
+<span class="kn">from</span> <span class="nn">joy.parser</span> <span class="kn">import</span> <span class="n">text_to_expression</span><span class="p">,</span> <span class="n">ParseError</span><span class="p">,</span> <span class="n">Symbol</span>
+<span class="kn">from</span> <span class="nn">joy.utils.stack</span> <span class="kn">import</span> <span class="n">stack_to_string</span>
+<span class="kn">from</span> <span class="nn">joy.utils.errors</span> <span class="kn">import</span> <span class="p">(</span>
    <span class="n">NotAListError</span><span class="p">,</span>
    <span class="n">NotAnIntError</span><span class="p">,</span>
    <span class="n">StackUnderflowError</span><span class="p">,</span>
@@ -71,12 +71,13 @@


 <div class="viewcode-block" id="joy"><a class="viewcode-back" href="../../joy.html#joy.joy.joy">[docs]</a><span class="k">def</span> <span class="nf">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="o">=</span><span class="kc">None</span><span class="p">):</span>
-    <span class="sd">&#39;&#39;&#39;Evaluate a Joy expression on a stack.</span>
+    <span class="sd">&#39;&#39;&#39;</span>
+<span class="sd">    Evaluate a Joy expression on a stack.</span>

-<span class="sd">  This function iterates through a sequence of terms which are either</span>
-<span class="sd">  literals (strings, numbers, sequences of terms) or function symbols.</span>
-<span class="sd">  Literals are put onto the stack and functions are looked up in the</span>
-<span class="sd">  dictionary and executed.</span>
+<span class="sd">    This function iterates through a sequence of terms which are either</span>
+<span class="sd">    literals (strings, numbers, sequences of terms) or function symbols.</span>
+<span class="sd">    Literals are put onto the stack and functions are looked up in the</span>
+<span class="sd">    dictionary and executed.</span>

 <span class="sd">    The viewer is a function that is called with the stack and expression</span>
 <span class="sd">    on every iteration, its return value is ignored.</span>
@@ -173,7 +174,7 @@
            <span class="k">except</span> <span class="n">NotAnIntError</span><span class="p">:</span>
                <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Not an integer.&#39;</span><span class="p">)</span>
            <span class="k">except</span> <span class="n">NotAListError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-                <span class="nb">print</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>  <span class="c1"># &#39;Not a list.&#39;</span>
+                <span class="nb">print</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
            <span class="k">except</span><span class="p">:</span>
                <span class="n">print_exc</span><span class="p">()</span>
            <span class="nb">print</span><span class="p">(</span><span class="n">stack_to_string</span><span class="p">(</span><span class="n">stack</span><span class="p">))</span>
@@ -247,7 +248,7 @@
 </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.3.0.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.4.0.
    </div>

  </body>
@@ -174,9 +174,9 @@
    <span class="k">return</span> <span class="n">inner</span></div>


-<div class="viewcode-block" id="BinaryBuiltinWrapper"><a class="viewcode-back" href="../../library.html#joy.library.BinaryBuiltinWrapper">[docs]</a><span class="k">def</span> <span class="nf">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
+<div class="viewcode-block" id="BinaryMathWrapper"><a class="viewcode-back" href="../../library.html#joy.library.BinaryMathWrapper">[docs]</a><span class="k">def</span> <span class="nf">BinaryMathWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;</span>
-<span class="sd">    Wrap functions that take two arguments and return a single result.</span>
+<span class="sd">    Wrap functions that take two numbers and return a single result.</span>
 <span class="sd">    &#39;&#39;&#39;</span>
    <span class="nd">@FunctionWrapper</span>
    <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
@@ -185,13 +185,33 @@
            <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
        <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
            <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
-        <span class="c1"># Boolean predicates like &quot;or&quot; fail here.  :(</span>
-<span class="c1">##        if (   not isinstance(a, int)</span>
-<span class="c1">##            or not isinstance(b, int)</span>
-<span class="c1">##            or isinstance(a, bool)  # Because bools are ints in Python.</span>
-<span class="c1">##            or isinstance(b, bool)</span>
+        <span class="k">if</span> <span class="p">(</span>   <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
+            <span class="ow">or</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
+            <span class="c1"># bool is int in Python.</span>
+            <span class="ow">or</span>     <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="nb">bool</span><span class="p">)</span>
+            <span class="ow">or</span>     <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">bool</span><span class="p">)</span>
+            <span class="p">):</span>
+            <span class="k">raise</span> <span class="n">NotAnIntError</span>
+        <span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
+        <span class="k">return</span> <span class="p">(</span><span class="n">result</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="k">return</span> <span class="n">inner</span></div>
+
+
+<div class="viewcode-block" id="BinaryLogicWrapper"><a class="viewcode-back" href="../../library.html#joy.library.BinaryLogicWrapper">[docs]</a><span class="k">def</span> <span class="nf">BinaryLogicWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
+    <span class="sd">&#39;&#39;&#39;</span>
+<span class="sd">    Wrap functions that take two numbers and return a single result.</span>
+<span class="sd">    &#39;&#39;&#39;</span>
+    <span class="nd">@FunctionWrapper</span>
+    <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
+    <span class="k">def</span> <span class="nf">inner</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="k">try</span><span class="p">:</span>
+            <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
+        <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
+<span class="c1">##        if (not isinstance(a, bool)</span>
+<span class="c1">##            or not isinstance(b, bool)</span>
 <span class="c1">##            ):</span>
-<span class="c1">##            raise NotAnIntError</span>
+<span class="c1">##            raise NotABoolError</span>
        <span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">result</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="k">return</span> <span class="n">inner</span></div>
@@ -1364,27 +1384,27 @@

    <span class="c1">#divmod_ = pm = __(n2, n1), __(n4, n3)</span>

-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">eq</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ge</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">gt</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">le</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lt</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ne</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">eq</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ge</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">gt</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">le</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lt</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ne</span><span class="p">),</span>

-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">xor</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lshift</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">rshift</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">xor</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lshift</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">rshift</span><span class="p">),</span>

-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">and_</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">or_</span><span class="p">),</span>
+    <span class="n">BinaryLogicWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">and_</span><span class="p">),</span>
+    <span class="n">BinaryLogicWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">or_</span><span class="p">),</span>

-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">add</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">floordiv</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mod</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mul</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">pow</span><span class="p">),</span>
-    <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">sub</span><span class="p">),</span>
-<span class="c1">##    BinaryBuiltinWrapper(operator.truediv),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">add</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">floordiv</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mod</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mul</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">pow</span><span class="p">),</span>
+    <span class="n">BinaryMathWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">sub</span><span class="p">),</span>
+<span class="c1">##    BinaryMathWrapper(operator.truediv),</span>

    <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="nb">bool</span><span class="p">),</span>
    <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">not_</span><span class="p">),</span>
@@ -60,18 +60,18 @@
 <span class="sd">A crude grammar::</span>

 <span class="sd">    joy = term*</span>
-<span class="sd">    term = int | float | string | &#39;[&#39; joy &#39;]&#39; | symbol</span>
+<span class="sd">    term = integer | &#39;[&#39; joy &#39;]&#39; | symbol</span>

 <span class="sd">A Joy expression is a sequence of zero or more terms.  A term is a</span>
-<span class="sd">literal value (integer, float, string, or Joy expression) or a function</span>
-<span class="sd">symbol.  Function symbols are unquoted strings and cannot contain square</span>
+<span class="sd">literal value (integer or Joy expression) or a function symbol.</span>
+<span class="sd">Function symbols are sequences of non-blanks and cannot contain square</span>
 <span class="sd">brackets.   Terms must be separated by blanks, which can be omitted</span>
 <span class="sd">around square brackets.</span>

 <span class="sd">&#39;&#39;&#39;</span>
 <span class="kn">from</span> <span class="nn">re</span> <span class="kn">import</span> <span class="n">Scanner</span>
-<span class="kn">from</span> <span class="nn">.utils.stack</span> <span class="kn">import</span> <span class="n">list_to_stack</span>
-<span class="kn">from</span> <span class="nn">.utils.snippets</span> <span class="kn">import</span> <span class="p">(</span>
+<span class="kn">from</span> <span class="nn">joy.utils.stack</span> <span class="kn">import</span> <span class="n">list_to_stack</span>
+<span class="kn">from</span> <span class="nn">joy.utils.snippets</span> <span class="kn">import</span> <span class="p">(</span>
    <span class="n">pat</span> <span class="k">as</span> <span class="n">SNIPPETS</span><span class="p">,</span>
    <span class="n">from_string</span><span class="p">,</span>
    <span class="n">Snippet</span><span class="p">,</span>
@@ -56,6 +56,18 @@
 <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">    In describing Joy I have used the term quotation to describe all of the</span>
+<span class="sd">    above, because I needed a word to describe the arguments to combinators</span>
+<span class="sd">    which fulfill the same role in Joy as lambda abstractions (with</span>
+<span class="sd">    variables) fulfill in the more familiar functional languages. I use the</span>
+<span class="sd">    term list for those quotations whose members are what I call literals:</span>
+<span class="sd">    numbers, characters, truth values, sets, strings and other quotations.</span>
+<span class="sd">    All these I call literals because their occurrence in code results in</span>
+<span class="sd">    them being pushed onto the stack. But I also call [London Paris] a list.</span>
+<span class="sd">    So, [dup \*] is a quotation but not a list.</span>
+
+<span class="sd">`&quot;A Conversation with Manfred von Thun&quot; w/ Stevan Apter &lt;http://archive.vector.org.uk/art10000350&gt;`_ </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</span>
@@ -95,7 +107,7 @@


 <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">list 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>
@@ -114,7 +126,9 @@

 <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">    :param stack stack: A stack, optional, defaults to the empty stack. This</span>
+<span class="sd">             allows for concatinating Python lists (or other sequence objects)</span>
+<span class="sd">             onto an existing Joy stack.</span>
 <span class="sd">    :rtype: stack</span>

 <span class="sd">    &#39;&#39;&#39;</span>
@@ -196,12 +210,12 @@

 <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="c1"># :raises RuntimeError: if quote is larger than sys.getrecursionlimit().</span>

 <span class="c1">##    return (quote[0], concat(quote[1], expression)) if quote else expression</span>

@@ -212,10 +226,10 @@
    <span class="c1"># In-lining is slightly faster (and won&#39;t break the</span>
    <span class="c1"># recursion limit on long quotes.)</span>

+    <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="n">NotAListError</span><span class="p">(</span><span class="s1">&#39;Not a list.&#39;</span><span class="p">)</span>
    <span class="n">temp</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">while</span> <span class="n">quote</span><span class="p">:</span>
-        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">):</span>
-            <span class="k">raise</span> <span class="n">NotAListError</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">quote</span><span class="p">))</span>
        <span class="n">item</span><span class="p">,</span> <span class="n">quote</span> <span class="o">=</span> <span class="n">quote</span>
        <span class="n">temp</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">item</span><span class="p">)</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">temp</span><span class="p">):</span>