Using Sphinx 4.3.0

This commit is contained in:
Simon Forman
2021-11-19 12:46:29 -08:00
parent 918aafb139
commit eeda5044ad
44 changed files with 6403 additions and 5626 deletions
+100 -98
View File
@@ -1,19 +1,18 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<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>Thun: Joy in Python &#8212; Thun 0.4.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<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="Joy Interpreter" href="../joy.html" />
@@ -30,20 +29,22 @@
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="thun-joy-in-python">
<section id="thun-joy-in-python">
<h1>Thun: Joy in Python<a class="headerlink" href="#thun-joy-in-python" title="Permalink to this headline"></a></h1>
<p>This implementation is meant as a tool for exploring the programming
model and method of Joy. Python seems like a great implementation
language for Joy for several reasons.</p>
<ul class="simple">
<li>We can lean on the Python immutable types for our basic semantics and types: ints, floats, strings, and tuples, which enforces functional purity.</li>
<li>We get garbage collection for free.</li>
<li>Compilation via Cython.</li>
<li>Python is a “glue language” with loads of libraries which we can wrap in Joy functions.</li>
<li><p>We can lean on the Python immutable types for our basic semantics and types: ints, floats, strings, and tuples, which enforces functional purity.</p></li>
<li><p>We get garbage collection for free.</p></li>
<li><p>Compilation via Cython.</p></li>
<li><p>Python is a “glue language” with loads of libraries which we can wrap in Joy functions.</p></li>
</ul>
<div class="section" id="read-eval-print-loop-repl">
<section id="read-eval-print-loop-repl">
<h2><a class="reference external" href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">Read-Eval-Print Loop (REPL)</a><a class="headerlink" href="#read-eval-print-loop-repl" title="Permalink to this headline"></a></h2>
<p>The main way to interact with the Joy interpreter is through a simple
<a class="reference external" href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">REPL</a>
@@ -86,8 +87,8 @@ joy?
joy?
</pre></div>
</div>
</div>
<div class="section" id="the-stack">
</section>
<section id="the-stack">
<h2>The Stack<a class="headerlink" href="#the-stack" title="Permalink to this headline"></a></h2>
<p>In Joy, in addition to the types Boolean, integer, float, and string,
there is a <a class="reference internal" href="../stack.html"><span class="doc">single sequence type</span></a> represented by enclosing a sequence of
@@ -95,21 +96,21 @@ terms in brackets <code class="docutils literal notranslate"><span class="pre">[
both the stack and the expression. It is a <a class="reference external" href="https://en.wikipedia.org/wiki/Cons#Lists">cons
list</a> made from Python
tuples.</p>
</div>
<div class="section" id="purely-functional-datastructures">
</section>
<section id="purely-functional-datastructures">
<h2>Purely Functional Datastructures<a class="headerlink" href="#purely-functional-datastructures" title="Permalink to this headline"></a></h2>
<p>Because Joy stacks are made out of Python tuples they are immutable, as are the other Python types we “borrow” for Joy, so all Joy datastructures are <a class="reference external" href="https://en.wikipedia.org/wiki/Purely_functional_data_structure">purely functional</a>.</p>
</div>
<div class="section" id="the-joy-function">
</section>
<section id="the-joy-function">
<h2>The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> function<a class="headerlink" href="#the-joy-function" title="Permalink to this headline"></a></h2>
<div class="section" id="an-interpreter">
<section id="an-interpreter">
<h3>An Interpreter<a class="headerlink" href="#an-interpreter" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> interpreter function is extrememly simple. It accepts a stack, an
expression, and a dictionary, and it iterates through the expression
putting values onto the stack and delegating execution to functions which it
looks up in the dictionary.</p>
</div>
<div class="section" id="continuation-passing-style">
</section>
<section id="continuation-passing-style">
<h3><a class="reference external" href="https://en.wikipedia.org/wiki/Continuation-passing_style">Continuation-Passing Style</a><a class="headerlink" href="#continuation-passing-style" title="Permalink to this headline"></a></h3>
<p>One day I thought, What happens if you rewrite Joy to use
<a class="reference external" href="https://en.wikipedia.org/wiki/Continuation-passing_style">CPS</a>? I
@@ -117,8 +118,8 @@ made all the functions accept and return the expression as well as the
stack and found that all the combinators could be rewritten to work by
modifying the expression rather than making recursive calls to the
<code class="docutils literal notranslate"><span class="pre">joy()</span></code> function.</p>
</div>
<div class="section" id="view-function">
</section>
<section id="view-function">
<h3>View function<a class="headerlink" href="#view-function" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> function accepts an optional <code class="docutils literal notranslate"><span class="pre">viewer</span></code> argument that
is a function which it calls on
@@ -127,70 +128,70 @@ evaluation. This can be used for tracing, breakpoints, retrying after
exceptions, or interrupting an evaluation and saving to disk or sending
over the network to resume later. The stack and expression together
contain all the state of the computation at each step.</p>
</div>
<div class="section" id="the-traceprinter">
</section>
<section id="the-traceprinter">
<h3>The <code class="docutils literal notranslate"><span class="pre">TracePrinter</span></code>.<a class="headerlink" href="#the-traceprinter" title="Permalink to this headline"></a></h3>
<p>A <code class="docutils literal notranslate"><span class="pre">viewer</span></code> records each step of the evaluation of a Joy program. The
<code class="docutils literal notranslate"><span class="pre">TracePrinter</span></code> has a facility for printing out a trace of the
evaluation, one line per step. Each step is aligned to the current
interpreter position, signified by a period separating the stack on the
left from the pending expression (“continuation”) on the right.</p>
</div>
</div>
<div class="section" id="parser">
</section>
</section>
<section id="parser">
<h2>Parser<a class="headerlink" href="#parser" title="Permalink to this headline"></a></h2>
<p>The parser is extremely simple. The undocumented <code class="docutils literal notranslate"><span class="pre">re.Scanner</span></code> class
does the tokenizing and then the parser builds the tuple
structure out of the tokens. Theres no Abstract Syntax Tree or anything
like that.</p>
<div class="section" id="symbols">
<section id="symbols">
<h3>Symbols<a class="headerlink" href="#symbols" title="Permalink to this headline"></a></h3>
<p>TODO: Symbols are just a string subclass; used by the parser to represent function names and by the interpreter to look up functions in the dictionary. N.B.: Symbols are not looked up at parse-time. You <em>could</em> define recursive functions, er, recusively, without <code class="docutils literal notranslate"><span class="pre">genrec</span></code> or other recursion combinators <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">==</span> <span class="pre">...</span> <span class="pre">foo</span> <span class="pre">...</span></code> but dont do that.</p>
</div>
<div class="section" id="token-regular-expressions">
</section>
<section id="token-regular-expressions">
<h3>Token Regular Expressions<a class="headerlink" href="#token-regular-expressions" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">123</span> <span class="mf">1.2</span> <span class="s1">&#39;single quotes&#39;</span> <span class="s2">&quot;double quotes&quot;</span> <span class="n">function</span>
</pre></div>
</div>
<p>TBD (look in the :module: joy.parser module.)</p>
</div>
<div class="section" id="examples">
</section>
<section id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h3>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">joy</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">text_to_expression</span><span class="p">(</span><span class="s1">&#39;1 2 3 4 5&#39;</span><span class="p">)</span> <span class="c1"># A simple sequence.</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>joy.parser.text_to_expression(&#39;1 2 3 4 5&#39;) # A simple sequence.
</pre></div>
</div>
<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="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><span class="mi">4</span><span class="p">,</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="p">())))))</span>
</pre></div>
</div>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">joy</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">text_to_expression</span><span class="p">(</span><span class="s1">&#39;[1 2 3] 4 5&#39;</span><span class="p">)</span> <span class="c1"># Three items, the first is a list with three items</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>joy.parser.text_to_expression(&#39;[1 2 3] 4 5&#39;) # Three items, the first is a list with three items
</pre></div>
</div>
<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="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> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="p">())))</span>
</pre></div>
</div>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">joy</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">text_to_expression</span><span class="p">(</span><span class="s1">&#39;1 23 [&quot;four&quot; [-5.0] cons] 8888&#39;</span><span class="p">)</span> <span class="c1"># A mixed bag. cons is</span>
<span class="c1"># a Symbol, no lookup at</span>
<span class="c1"># parse-time. Haiku docs.</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>joy.parser.text_to_expression(&#39;1 23 [&quot;four&quot; [-5.0] cons] 8888&#39;) # A mixed bag. cons is
# a Symbol, no lookup at
# parse-time. Haiku docs.
</pre></div>
</div>
<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="p">(</span><span class="mi">23</span><span class="p">,</span> <span class="p">((</span><span class="s1">&#39;four&#39;</span><span class="p">,</span> <span class="p">((</span><span class="o">-</span><span class="mf">5.0</span><span class="p">,</span> <span class="p">()),</span> <span class="p">(</span><span class="n">cons</span><span class="p">,</span> <span class="p">()))),</span> <span class="p">(</span><span class="mi">8888</span><span class="p">,</span> <span class="p">()))))</span>
</pre></div>
</div>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">joy</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">text_to_expression</span><span class="p">(</span><span class="s1">&#39;[][][][][]&#39;</span><span class="p">)</span> <span class="c1"># Five empty lists.</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>joy.parser.text_to_expression(&#39;[][][][][]&#39;) # Five empty lists.
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">((),</span> <span class="p">((),</span> <span class="p">((),</span> <span class="p">((),</span> <span class="p">((),</span> <span class="p">())))))</span>
</pre></div>
</div>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">joy</span><span class="o">.</span><span class="n">parser</span><span class="o">.</span><span class="n">text_to_expression</span><span class="p">(</span><span class="s1">&#39;[[[[[]]]]]&#39;</span><span class="p">)</span> <span class="c1"># Five nested lists.</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>joy.parser.text_to_expression(&#39;[[[[[]]]]]&#39;) # Five nested lists.
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">((((((),</span> <span class="p">()),</span> <span class="p">()),</span> <span class="p">()),</span> <span class="p">()),</span> <span class="p">())</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="library">
</section>
</section>
<section id="library">
<h2>Library<a class="headerlink" href="#library" title="Permalink to this headline"></a></h2>
<p>The Joy library of functions (aka commands, or “words” after Forth
usage) encapsulates all the actual functionality (no pun intended) of
@@ -198,7 +199,7 @@ the Joy system. There are simple functions such as addition <code class="docutil
<code class="docutils literal notranslate"><span class="pre">+</span></code>, the library module supports aliases), and combinators which
provide control-flow and higher-order operations.</p>
<p>Many of the functions are defined in Python, like <code class="docutils literal notranslate"><span class="pre">dip</span></code>:</p>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span> <span class="n">inspect</span><span class="o">.</span><span class="n">getsource</span><span class="p">(</span><span class="n">joy</span><span class="o">.</span><span class="n">library</span><span class="o">.</span><span class="n">dip</span><span class="p">)</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>print inspect.getsource(joy.library.dip)
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dip</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>
@@ -211,11 +212,10 @@ provide control-flow and higher-order operations.</p>
When the interpreter executes a definition function that function just
pushes its body expression onto the pending expression (the
continuation) and returns control to the interpreter.</p>
<div class="code ipython2 highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span> <span class="n">joy</span><span class="o">.</span><span class="n">library</span><span class="o">.</span><span class="n">definitions</span>
<div class="highlight-ipython2 notranslate"><div class="highlight"><pre><span></span>print joy.library.definitions
</pre></div>
</div>
<pre class="literal-block">
second == rest first
<pre class="literal-block">second == rest first
third == rest rest first
product == 1 swap [*] step
swons == swap cons
@@ -248,8 +248,7 @@ anamorphism == [pop []] swap [dip swons] genrec
range == [0 &lt;=] [1 - dup] anamorphism
while == swap [nullary] cons dup dipd concat loop
dudipd == dup dipd
primrec == [i] genrec
</pre>
primrec == [i] genrec</pre>
<p>Currently, theres no function to add new definitions to the dictionary
from “within” Joy code itself. Adding new definitions remains a
meta-interpreter action. You have to do it yourself, in Python, and wash
@@ -260,7 +259,7 @@ stack and expression. Theres an implicit <em>standard dictionary</em> that
defines the actual semantics of the syntactic stack and expression
datastructures (which only contain symbols, not the actual functions.
Pickle some and see for yourself.)</p>
<div class="section" id="there-should-be-only-one">
<section id="there-should-be-only-one">
<h3>“There should be only one.”<a class="headerlink" href="#there-should-be-only-one" title="Permalink to this headline"></a></h3>
<p>Which brings me to talking about one of my hopes and dreams for this
notation: “There should be only one.” What I mean is that there should
@@ -277,8 +276,8 @@ frameworks, programming languages. Its a waste of time, a <a class="reference
“thundering herd”
attack</a> on
human mentality.</p>
</div>
<div class="section" id="literary-code-library">
</section>
<section id="literary-code-library">
<h3>Literary Code Library<a class="headerlink" href="#literary-code-library" title="Permalink to this headline"></a></h3>
<p>If you read over the other notebooks youll see that developing code in
Joy is a lot like doing simple mathematics, and the descriptions of the
@@ -292,43 +291,47 @@ card is highly desirable. Less code has fewer errors. The structure of
Joy engenders a kind of thinking that seems to be very effective for
developing structured processes.</p>
<p>There seems to be an elegance and power to the notation.</p>
</div>
</div>
</div>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Thun: Joy in Python</a><ul>
<li><a class="reference internal" href="#read-eval-print-loop-repl">Read-Eval-Print Loop (REPL)</a></li>
<li><a class="reference internal" href="#the-stack">The Stack</a></li>
<li><a class="reference internal" href="#purely-functional-datastructures">Purely Functional Datastructures</a></li>
<li><a class="reference internal" href="#the-joy-function">The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> function</a><ul>
<li><a class="reference internal" href="#an-interpreter">An Interpreter</a></li>
<li><a class="reference internal" href="#continuation-passing-style">Continuation-Passing Style</a></li>
<li><a class="reference internal" href="#view-function">View function</a></li>
<li><a class="reference internal" href="#the-traceprinter">The <code class="docutils literal notranslate"><span class="pre">TracePrinter</span></code>.</a></li>
</ul>
</li>
<li><a class="reference internal" href="#parser">Parser</a><ul>
<li><a class="reference internal" href="#symbols">Symbols</a></li>
<li><a class="reference internal" href="#token-regular-expressions">Token Regular Expressions</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#library">Library</a><ul>
<li><a class="reference internal" href="#there-should-be-only-one">“There should be only one.”</a></li>
<li><a class="reference internal" href="#literary-code-library">Literary Code Library</a></li>
</ul>
</li>
<h1 class="logo"><a href="../index.html">Thun</a></h1>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Thun: Joy in Python</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#read-eval-print-loop-repl">Read-Eval-Print Loop (REPL)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-stack">The Stack</a></li>
<li class="toctree-l2"><a class="reference internal" href="#purely-functional-datastructures">Purely Functional Datastructures</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-joy-function">The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> function</a></li>
<li class="toctree-l2"><a class="reference internal" href="#parser">Parser</a></li>
<li class="toctree-l2"><a class="reference internal" href="#library">Library</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../joy.html">Joy Interpreter</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stack.html">Stack or Quote or Sequence or List…</a></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="index.html">Essays about Programming in Joy</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
@@ -338,25 +341,24 @@ developing structured processes.</p>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/notebooks/Intro.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
@@ -367,7 +369,7 @@ developing structured processes.</p>
</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> 1.7.3.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.3.0.
</div>
</body>