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

A bit more docs.

This commit is contained in:
Simon Forman 2022-09-16 12:28:13 -07:00
parent dbcbf16bc9
commit 466bf3d79b
2 changed files with 112 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
README.md
View File

@ -2,7 +2,7 @@
A Dialect of Joy. A Dialect of Joy.
version 0.5.0 Version 0.5.0
> Simple pleasures are the best. > Simple pleasures are the best.
@ -27,6 +27,13 @@ and a great deal of fascinating material mostly written by Von Thun on
Joy and its deeper facets as well as how to program in it and several Joy and its deeper facets as well as how to program in it and several
interesting aspects. It's quite a treasure trove. interesting aspects. It's quite a treasure trove.
[Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29)
[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
[The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/)
## Example Code ## Example Code
Here is an example of Joy code: Here is an example of Joy code:
@ -90,113 +97,89 @@ coordinate pair in a square spiral (like the kind used to construct an
## Documentation ## Documentation
### Jupyter Notebooks ### [Jupyter Notebooks](/notebooks/index.html)
[Notebooks](/notebooks/index.html) ### [Function Reference](/FuncRef.html)
The docs/notebooks dir contains Jupyter notebooks, ... TODO
### Function Reference
[Function Reference](/FuncRef.html)
### Building the Docs ### Building the Docs
Run `make` in the `docs` directory. Run `make` in the `docs` directory. (This is a lie, it's more complex than
that. Really you need to run (GNU) make in the `docs/notebooks` and
`docs/reference` dirs first, _then_ run `make` in the `docs` directory.)
## Installation
Clone the repo and follow the instructions in the individual `implementations` directories.
## Basics of Joy ## Basics of Joy
Joy is stack-based. There is a main stack that holds data items: Joy is built around three things: a __stack__ of data items, an __expression__
integers, bools, symbols, and sequences or quotes which hold representing a program to evaluate, and a __dictionary__ of named functions.
data items themselves.
23 dup [21 18 /] [1 [2 [3]]] Joy is [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language).
There is a single main __stack__ that holds data items, which can be integers, bools,
symbols (names), or sequences of data items enclosed in square brackets (`[` or `]`).
A Joy expression is just a sequence (a.k.a. "list") of items. Sequences 23 dup [21 18 add] true false [1 [2 [3]]] cons
A Joy __expression__ is just a sequence or list of items. Sequences
intended as programs are called "quoted programs". Evaluation proceeds intended as programs are called "quoted programs". Evaluation proceeds
by iterating through the terms in the expression, putting all literals by iterating through the terms in an expression putting all literals (integers, bools, or lists)
onto the main stack and executing functions as they are encountered. onto the main stack and executing functions named by symbols as they are encountered.
Functions receive the current stack and return the next stack. Functions receive the current stack, expression, and dictionary and return the next stack.
The __dictionary__ associates symbols (strings) with Joy expressions that define the
available functions of the Joy system. Together the stack, expression, and dictionary
are the entire state of the Joy interpreter.
### Stack / Quote / List / Sequence
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.
> In describing Joy I have used the term quotation to describe all of the
> above, because I needed a word to describe the arguments to combinators
> which fulfill the same role in Joy as lambda abstractions (with
> variables) fulfill in the more familiar functional languages. I use the
> term list for those quotations whose members are what I call literals:
> numbers, characters, truth values, sets, strings and other quotations.
> All these I call literals because their occurrence in code results in
> them being pushed onto the stack. But I also call [London Paris] a list.
> So, [dup *] is a quotation but not a list.
From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350
### Literals and Simple Functions ### Literals and Simple Functions
joy? 1 2 3 TODO
. 1 2 3
1 . 2 3
1 2 . 3
1 2 3 .
1 2 3 <-top
joy? + +
1 2 3 . + +
1 5 . +
6 .
6 <-top
joy? 7 *
6 . 7 *
6 7 . *
42 .
42 <-top
joy?
### Combinators ### Combinators
The main loop is very simple as most of the action happens through what The main loop is very simple as most of the action happens through what
are called "combinators": functions which accept quoted programs on the are called __combinators__. These are functions which accept quoted programs on the
stack and run them in various ways. These combinators factor specific stack and run them in various ways. These combinators reify specific
patterns that provide the effect of control-flow in other languages (such control-flow patterns (such as `ifte` which is like `if.. then.. else..` in other
as ifte which is like if..then..else..) Combinators receive the current languages.) Combinators receive the current
expession in addition to the stack and return the next expression. They expession in addition to the stack and return the next expression. They
work by changing the pending expression the interpreter is about to work by changing the pending expression the interpreter is about to
execute. The combinators could work by making recursive calls to the execute. (The combinators could work by making recursive calls to the
interpreter and all intermediate state would be held in the call stack of interpreter and all intermediate state would be held in the call stack of
the implementation language, in this joy implementation they work instead the implementation language, in this joy implementation they work instead
by changing the pending expression and intermediate state is put there. by changing the pending expression and intermediate state is put there.)
joy? 23 [0 >] [dup --] while joy? 23 [0 >] [dup --] while
23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
...
-> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
## TODO:
§.4.4 Definitions and More Elaborate Functions
§.4.5 Programming and Metaprogramming
§.4.6 Refactoring
§.6 References & Further Reading
[Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29)
[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
[The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/)
--------------------------------------------------
Misc...
Stack based - literals (as functions) - functions - combinators -
Refactoring and making new definitions - traces and comparing
performance - metaprogramming as programming, even the lowly integer
range function can be expressed in two phases: building a specialized
program and then executing it with a combinator - ?Partial evaluation?
- ?memoized dynamic dependency graphs? - algebra
-------------------------------------------------- --------------------------------------------------

114
docs/html/index.html
View File

@ -8,7 +8,7 @@
<body> <body>
<h1>Thun</h1> <h1>Thun</h1>
<p>A Dialect of Joy.</p> <p>A Dialect of Joy.</p>
<p>version 0.5.0</p> <p>Version 0.5.0</p>
<blockquote> <blockquote>
<p>Simple pleasures are the best.</p> <p>Simple pleasures are the best.</p>
</blockquote> </blockquote>
@ -31,6 +31,9 @@ which contains source code for the original C interpreter, Joy language source c
and a great deal of fascinating material mostly written by Von Thun on and a great deal of fascinating material mostly written by Von Thun on
Joy and its deeper facets as well as how to program in it and several Joy and its deeper facets as well as how to program in it and several
interesting aspects. It's quite a treasure trove.</p> interesting aspects. It's quite a treasure trove.</p>
<p><a href="https://en.wikipedia.org/wiki/Joy_%28programming_language%29">Wikipedia entry for Joy</a></p>
<p><a href="http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language">Homepage at La Trobe University</a></p>
<p><a href="https://web.archive.org/web/20220411010035/https://joypy.osdn.io/">The original Thun/Joypy site</a></p>
<h2>Example Code</h2> <h2>Example Code</h2>
<p>Here is an example of Joy code:</p> <p>Here is an example of Joy code:</p>
<pre><code>square_spiral ≡ [_p] [_then] [_else] ifte <pre><code>square_spiral ≡ [_p] [_then] [_else] ifte
@ -85,83 +88,64 @@ coordinate pair in a square spiral (like the kind used to construct an
`-- defs.txt - common Joy definitions for all interpreters `-- defs.txt - common Joy definitions for all interpreters
</code></pre> </code></pre>
<h2>Documentation</h2> <h2>Documentation</h2>
<h3>Jupyter Notebooks</h3> <h3><a href="/notebooks/index.html">Jupyter Notebooks</a></h3>
<p><a href="/notebooks/index.html">Notebooks</a></p> <h3><a href="/FuncRef.html">Function Reference</a></h3>
<p>The docs/notebooks dir contains Jupyter notebooks, ... TODO</p>
<h3>Function Reference</h3>
<p><a href="/FuncRef.html">Function Reference</a></p>
<h3>Building the Docs</h3> <h3>Building the Docs</h3>
<p>Run <code>make</code> in the <code>docs</code> directory.</p> <p>Run <code>make</code> in the <code>docs</code> directory. (This is a lie, it's more complex than
that. Really you need to run (GNU) make in the <code>docs/notebooks</code> and
<code>docs/reference</code> dirs first, <em>then</em> run <code>make</code> in the <code>docs</code> directory.)</p>
<h2>Installation</h2>
<p>Clone the repo and follow the instructions in the individual <code>implementations</code> directories.</p>
<h2>Basics of Joy</h2> <h2>Basics of Joy</h2>
<p>Joy is stack-based. There is a main stack that holds data items: <p>Joy is built around three things: a <strong>stack</strong> of data items, an <strong>expression</strong>
integers, bools, symbols, and sequences or quotes which hold representing a program to evaluate, and a <strong>dictionary</strong> of named functions.</p>
data items themselves.</p> <p>Joy is <a href="https://en.wikipedia.org/wiki/Stack-oriented_programming_language">stack-based</a>.
<pre><code>23 dup [21 18 /] [1 [2 [3]]] There is a single main <strong>stack</strong> that holds data items, which can be integers, bools,
symbols (names), or sequences of data items enclosed in square brackets (<code>[</code> or <code>]</code>).</p>
<pre><code>23 dup [21 18 add] true false [1 [2 [3]]] cons
</code></pre> </code></pre>
<p>A Joy expression is just a sequence (a.k.a. "list") of items. Sequences <p>A Joy <strong>expression</strong> is just a sequence or list of items. Sequences
intended as programs are called "quoted programs". Evaluation proceeds intended as programs are called "quoted programs". Evaluation proceeds
by iterating through the terms in the expression, putting all literals by iterating through the terms in an expression putting all literals (integers, bools, or lists)
onto the main stack and executing functions as they are encountered. onto the main stack and executing functions named by symbols as they are encountered.
Functions receive the current stack and return the next stack.</p> Functions receive the current stack, expression, and dictionary and return the next stack.</p>
<p>The <strong>dictionary</strong> associates symbols (strings) with Joy expressions that define the
available functions of the Joy system. Together the stack, expression, and dictionary
are the entire state of the Joy interpreter.</p>
<h3>Stack / Quote / List / Sequence</h3>
<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>
<blockquote>
<p>In describing Joy I have used the term quotation to describe all of the
above, because I needed a word to describe the arguments to combinators
which fulfill the same role in Joy as lambda abstractions (with
variables) fulfill in the more familiar functional languages. I use the
term list for those quotations whose members are what I call literals:
numbers, characters, truth values, sets, strings and other quotations.
All these I call literals because their occurrence in code results in
them being pushed onto the stack. But I also call [London Paris] a list.
So, [dup *] is a quotation but not a list.</p>
</blockquote>
<p>From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350</p>
<h3>Literals and Simple Functions</h3> <h3>Literals and Simple Functions</h3>
<pre><code>joy? 1 2 3 <p>TODO</p>
. 1 2 3
1 . 2 3
1 2 . 3
1 2 3 .
1 2 3 &lt;-top
joy? + +
1 2 3 . + +
1 5 . +
6 .
6 &lt;-top
joy? 7 *
6 . 7 *
6 7 . *
42 .
42 &lt;-top
joy?
</code></pre>
<h3>Combinators</h3> <h3>Combinators</h3>
<p>The main loop is very simple as most of the action happens through what <p>The main loop is very simple as most of the action happens through what
are called "combinators": functions which accept quoted programs on the are called <strong>combinators</strong>. These are functions which accept quoted programs on the
stack and run them in various ways. These combinators factor specific stack and run them in various ways. These combinators reify specific
patterns that provide the effect of control-flow in other languages (such control-flow patterns (such as <code>ifte</code> which is like <code>if.. then.. else..</code> in other
as ifte which is like if..then..else..) Combinators receive the current languages.) Combinators receive the current
expession in addition to the stack and return the next expression. They expession in addition to the stack and return the next expression. They
work by changing the pending expression the interpreter is about to work by changing the pending expression the interpreter is about to
execute. The combinators could work by making recursive calls to the execute. (The combinators could work by making recursive calls to the
interpreter and all intermediate state would be held in the call stack of interpreter and all intermediate state would be held in the call stack of
the implementation language, in this joy implementation they work instead the implementation language, in this joy implementation they work instead
by changing the pending expression and intermediate state is put there.</p> by changing the pending expression and intermediate state is put there.)</p>
<pre><code>joy? 23 [0 &gt;] [dup --] while <pre><code>joy? 23 [0 &gt;] [dup --] while
23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
...
-&gt; 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
</code></pre> </code></pre>
<h2>TODO:</h2>
<p>§.4.4 Definitions and More Elaborate Functions</p>
<p>§.4.5 Programming and Metaprogramming</p>
<p>§.4.6 Refactoring</p>
<p>§.6 References &amp; Further Reading</p>
<p><a href="https://en.wikipedia.org/wiki/Joy_%28programming_language%29">Wikipedia entry for Joy</a></p>
<p><a href="http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language">Homepage at La Trobe University</a></p>
<p><a href="https://web.archive.org/web/20220411010035/https://joypy.osdn.io/">The original Thun/Joypy site</a></p>
<hr>
<p>Misc...</p>
<p>Stack based - literals (as functions) - functions - combinators -
Refactoring and making new definitions - traces and comparing
performance - metaprogramming as programming, even the lowly integer
range function can be expressed in two phases: building a specialized
program and then executing it with a combinator - ?Partial evaluation?
- ?memoized dynamic dependency graphs? - algebra</p>
<hr> <hr>
<p>Copyright © 2014-2022 Simon Forman</p> <p>Copyright © 2014-2022 Simon Forman</p>
<p>This file is part of Thun</p> <p>This file is part of Thun</p>