sforman
/
Thun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Put interpreter on pages.

This commit is contained in:
sforman 2023-09-29 15:25:49 -07:00
parent c3054377a6
commit 52e831a137
10 changed files with 7731 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/MAKE Normal file
View File

@ -0,0 +1,7 @@
python build_index.py ./source/index.md > ./html/index.html
python build_index.py ./source/Thun.md > html/Thun.html
python build_index.py ./source/notebooks/BigNums.md > ./html/notebooks/BigInts.html
python build_index.py ./source/notebooks/Generator_Programs.md > ./html/notebooks/Generator_Programs.html
(cd ../implementations/Elm/ ; make)
cp -f ../implementations/Elm/demo/Joy.js ./html/Joy.js

3
docs/build_index.py
View File

@ -21,9 +21,12 @@ print(f'''\
<title>{title_of(html)}</title>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/site.css">
<script src="/Joy.js"></script>
</head>
<body>
<div id="joy_interpreter"></div>
{html}
<script>var joy_interpreter = Elm.Main.init({{node: document.getElementById('joy_interpreter')}});</script>
</body>
</html>''')

7637
docs/html/Joy.js Normal file
View File

File diff suppressed because it is too large Load Diff

54
docs/html/Thun.html
View File

@ -5,20 +5,22 @@
<title>Thun Specification</title>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/site.css">
<script src="/Joy.js"></script>
</head>
<body>
<div id="joy_interpreter"></div>
<h1>Thun Specification</h1>
<p>Version 0.5.0</p>
<h2>Grammar</h2>
<p>The grammar of Thun is very simple. A Thun expression is zero or more Thun
terms separated by blanks. Terms can be integers in decimal notation,
Booleans <code>true</code> and <code>false</code>, lists enclosed by square brackets <code>[</code> and <code>]</code>,
or symbols (names of functions.)</p>
<p>The grammar of Thun is very simple. A Thun expression is zero or more
Thun terms separated by blanks. Terms can be integers in decimal
notation, Booleans <code>true</code> and <code>false</code>, lists enclosed by square brackets
<code>[</code> and <code>]</code>, or symbols (names of functions.)</p>
<pre><code>joy ::= term*
term ::= integer | bool | '[' joy ']' | symbol
integer ::= [ '-' ] ('0'...'9')+
integer ::= 0 | [ '-' ] ('1'...'9') ('0'...'9')*
bool ::= 'true' | 'false'
@ -31,6 +33,7 @@ brackets. Integers can be prefixed with a minus sign to denote negative
numbers. The symbols <code>true</code> and <code>false</code> are reserved to denote their
respective Boolean values.</p>
<p>That's it. That's the whole of the grammar.</p>
<p><img alt="Thun Grammar Railroad Diagram" src="https://git.sr.ht/~sforman/Thun/blob/trunk/docs/html/images/grammar.png"></p>
<h2>Types</h2>
<p>The original Joy has several datatypes (such as strings and sets)
but the Thun dialect currently only uses four:</p>
@ -89,20 +92,24 @@ it looks up in the dictionary.</p>
<strong>Combinators</strong> (see below) alter control flow by prepending quoted programs to the pending
expression (aka "continuation".)</p>
<h2>Literals, Functions, Combinators</h2>
<p>Terms in Thun can be categorized into literal, simple functions that
operate on the stack only, and combinators that can prepend quoted
programs onto the pending expression ("continuation").</p>
<p>Terms in Thun can be categorized into <strong>literals</strong>, simple <strong>functions</strong>
that operate on the stack only, and <strong>combinators</strong> that can prepend
quoted programs onto the pending expression ("continuation").</p>
<h3>Literals</h3>
<p>Literal values (integers, Booleans, lists) are put onto the stack.</p>
<p>Literal values (integers, Booleans, lists) are put onto the stack.
Literals can be thought of as functions that accept a stack and
return it with the value they denote on top.</p>
<h3>Functions</h3>
<p>Functions take values from the stack and push results onto it.</p>
<p>Functions take values from the stack and push results onto it. There are
a few kinds of functions: math, comparison, list and stack manipulation.</p>
<h3>Combinators</h3>
<p><strong>Combinators</strong> are functions which accept quoted programs on the stack
and run them in various ways. These combinators reify specific
control-flow patterns (such as <code>ifte</code> which is like <code>if.. then.. else..</code>
in other languages.) Combinators receive the current expession in
addition to the stack and return the next expression. They work by
changing the pending expression the interpreter is about to execute.</p>
and run them in various ways by prepending them (or not) to the pending
expression. These combinators reify specific control-flow patterns (such
as <code>ifte</code> which is like <code>if.. then.. else..</code> in other languages.)
Combinators receive the current expession in addition to the stack and
return the next expression. They work by changing the pending expression
the interpreter is about to execute.</p>
<h3>Basis Functions</h3>
<p>Thun has a set of <em>basis</em> functions which are implemented in the host
language. The rest of functions in the Thun dialect are defined in terms
@ -174,8 +181,25 @@ leading to an error.</p>
the spirit of the thing to just leave a footgun like that laying around,
but perhaps in practice it won't come up. (Because writing Thun code by
derivation seems to lead to bug-free code, which is the kinda the point.)</p>
<h3>Variations between Interpreters</h3>
<p>There are several small choices to be made when implementing a Thun
interpreter (TODO: make a comprehensive list), for example, the Python
interpreter keeps all of its functions in one dictionary but most of the
other interpreters have a <code>case</code> or <code>switch</code> statement for the built-in
functions and a separate hash table for definitions. Additionally, of
the interpreters that have hash tables most of them check the hash table
after the <code>case</code> statement. This means that one cannot "shadow" built-in
functions in some interpreters. You can <code>inscribe</code> them, but the
interpreter will not look for them.</p>
<p>I haven't yet formally made a decision for how Thun <em>shall</em> work.
Letting built-ins be shadowed is fun and useful for exploration, and
letting them be inviolate is useful for unsurprising behaviour.</p>
<p>Another choice is how to handle duplicate definitions in general. Should
you be able to reuse a name? Or should <code>inscribe</code> throw some sort of
error if you try?</p>
<hr>
<p>Copyright © 2014 - 2023 Simon Forman</p>
<p>This file is part of Thun</p>
<script>var joy_interpreter = Elm.Main.init({node: document.getElementById('joy_interpreter')});</script>
</body>
</html>

5
docs/html/css/func_ref.css
View File

@ -31,3 +31,8 @@ blockquote {
border-left: 0.2em solid black;
padding: 0.5em;
}
li {
font-family: monospace, 'Inconsolata';
display: inline list-item;
}

24
docs/html/css/site.css
View File

@ -30,3 +30,27 @@ blockquote {
border-left: 0.2em solid black;
padding: 0.5em;
}
#joy_interpreter {
background: #fff;
font-family: monospace, Inconsolata;
padding: 0.25em;
position: sticky;
top: 0;
border: 2px solid black;
}
#joy_interpreter > input {
box-sizing: border-box;
width: 100%;
height: 2em;
}
#joy_interpreter > div {
background: #eee;
border-left: 1px solid black;
padding: 0.5em;
height: 1em;
margin-left: 0.25em;
margin-right: 0.25em;
}

10
docs/html/index.html
View File

@ -5,8 +5,10 @@
<title>Thun</title>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/site.css">
<script src="/Joy.js"></script>
</head>
<body>
<div id="joy_interpreter"></div>
<h1>Thun</h1>
<p>A Dialect of Joy.</p>
<p>Version 0.5.0</p>
@ -52,9 +54,9 @@ kind used to construct an <a href="https://en.wikipedia.org/wiki/Ulam_spiral">Ul
For more information see <a href="/notebooks/Square_Spiral.html">Square Spiral Example Joy Code</a>.</p>
<pre><code>square_spiral [_p] [_then] [_else] ifte
_p [_p0] [_p1] &amp;&amp;
_p [_p0] [_p1] and
_p0 [abs] ii &lt;=
_p1 [&lt;&gt;] [pop !-] ||
_p1 [&lt;&gt;] [pop !-] or
_then [ !-] [[++]] [[--]] ifte dip
_else [pop !-] [--] [++] ifte
@ -173,7 +175,7 @@ expression, and dictionary are the entire state of the Joy interpreter.</p>
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>
<p><img alt="Joy Interpreter Flowchart" src="https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg"></p>
<p><img alt="Joy Interpreter Flowchart" src="/joy_interpreter_flowchart.svg"></p>
<p>All control flow works by
<a href="https://en.wikipedia.org/wiki/Continuation-passing_style">Continuation Passing Style</a>.
<strong>Combinators</strong> (see below) alter control flow by prepending quoted programs to the pending
@ -237,6 +239,6 @@ FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.</p>
<p>You should have received a copy of the GNU General Public License along
with Thun. If not see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.</p>
<script>var joy_interpreter = Elm.Main.init({node: document.getElementById('joy_interpreter')});</script>
</body>
</html>

5
docs/html/notebooks/BigInts.html
View File

@ -5,8 +5,10 @@
<title>BigNums in Joy</title>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/site.css">
<script src="/Joy.js"></script>
</head>
<body>
<div id="joy_interpreter"></div>
<h1>BigNums in Joy</h1>
<p>Most of the implementations of Thun support
<a href="https://en.wikipedia.org/wiki/BigNum">BigNums</a>, either built-in or as
@ -887,6 +889,8 @@ sub-digits′ == [both-empty] [one-empty] [both-non-empty] list-combiner-genrec
[both-non-empty]
[i cons]
genrec
sub-digits′ == [either-or-both-null] [[both-null] [both-empty] [ditch-empty-list sub-carry-from-digits] ifte] [uncons-two [sub-with-carry] dipd] [i cons] genrec
</code></pre>
<p>We just need to define the pieces.</p>
<h3>≡ <code>sub-with-carry</code></h3>
@ -1140,5 +1144,6 @@ inscribe
both? == boolii &amp;
one-of? == boolii |
</code></pre>
<script>var joy_interpreter = Elm.Main.init({node: document.getElementById('joy_interpreter')});</script>
</body>
</html>

3
docs/html/notebooks/Generator_Programs.html
View File

@ -5,8 +5,10 @@
<title>Generator Programs</title>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/site.css">
<script src="/Joy.js"></script>
</head>
<body>
<div id="joy_interpreter"></div>
<h1>Generator Programs</h1>
<h2>Using <code>x</code> to Generate Values</h2>
<p>Cf. <a href="https://www.kevinalbrecht.com/code/joy-mirror/jp-reprod.html">Self-reproducing and reproducing programs</a> by Manfred von Thun</p>
@ -418,5 +420,6 @@ joy? x
<p>And so it goes...</p>
<h2>Conclusion</h2>
<p>Generator programs like these are fun and interesting.</p>
<script>var joy_interpreter = Elm.Main.init({node: document.getElementById('joy_interpreter')});</script>
</body>
</html>

3
docs/html/notebooks/index.html
View File

@ -16,13 +16,14 @@ I'm in the process of rewriting them to use the Joy kernel.</p>
<li><a href="/notebooks/1._Basic_Use_of_Joy_in_a_Notebook.html">1. Basic Use of Joy in a Notebook</a></li>
<li><a href="/notebooks/2._Library_Examples.html">2. Library Examples</a></li>
<li><a href="/notebooks/3._Developing_a_Program.html">3. Developing a Program</a></li>
<li><a href="/notebooks/Developing_a_Program.html">Developing a Program</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_1st.html">Advent of Code 2017 December 1st</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_2nd.html">Advent of Code 2017 December 2nd</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_3rd.html">Advent of Code 2017 December 3rd</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_4th.html">Advent of Code 2017 December 4th</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_5th.html">Advent of Code 2017 December 5th</a></li>
<li><a href="/notebooks/Advent_of_Code_2017_December_6th.html">Advent of Code 2017 December 6th</a></li>
<li><a href="/notebooks/BigInts.html">BigInts</a></li>
<li><a href="/notebooks/BigInts.html">BigNums</a></li>
<li><a href="/notebooks/Compiling_Joy.html">Compiling Joy</a></li>
<li><a href="/notebooks/Correcet_Programming.html">Correcet Programming</a></li>
<li><a href="/notebooks/Derivatives_of_Regular_Expressions.html">Derivatives of Regular Expressions</a></li>