A bit more docs.
This commit is contained in:
Simon Forman
parent
dbcbf16bc9
commit
466bf3d79b
143
README.md
143
README.md
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
A Dialect of Joy.
|
||||
|
||||
version 0.5.0
|
||||
Version 0.5.0
|
||||
|
||||
> 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
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
### Jupyter Notebooks
|
||||
### [Jupyter Notebooks](/notebooks/index.html)
|
||||
|
||||
[Notebooks](/notebooks/index.html)
|
||||
|
||||
The docs/notebooks dir contains Jupyter notebooks, ... TODO
|
||||
|
||||
### Function Reference
|
||||
|
||||
[Function Reference](/FuncRef.html)
|
||||
### [Function Reference](/FuncRef.html)
|
||||
|
||||
### 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
|
||||
|
||||
Joy is stack-based. There is a main stack that holds data items:
|
||||
integers, bools, symbols, and sequences or quotes which hold
|
||||
data items themselves.
|
||||
Joy is built around three things: a __stack__ of data items, an __expression__
|
||||
representing a program to evaluate, and a __dictionary__ of named functions.
|
||||
|
||||
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
|
||||
by iterating through the terms in the expression, putting all literals
|
||||
onto the main stack and executing functions as they are encountered.
|
||||
Functions receive the current stack and return the next stack.
|
||||
by iterating through the terms in an expression putting all literals (integers, bools, or lists)
|
||||
onto the main stack and executing functions named by symbols as they are encountered.
|
||||
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
|
||||
|
||||
joy? 1 2 3
|
||||
. 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?
|
||||
TODO
|
||||
|
||||
|
||||
### Combinators
|
||||
|
||||
The main loop is very simple as most of the action happens through what
|
||||
are called "combinators": functions which accept quoted programs on the
|
||||
stack and run them in various ways. These combinators factor specific
|
||||
patterns that provide the effect of control-flow in other languages (such
|
||||
as ifte which is like if..then..else..) Combinators receive the current
|
||||
are called __combinators__. These are functions which accept quoted programs on the
|
||||
stack and run them in various ways. These combinators reify specific
|
||||
control-flow patterns (such as `ifte` which is like `if.. then.. else..` 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. 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
|
||||
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
|
||||
|
||||
...
|
||||
|
||||
-> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
|
||||
23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<body>
|
||||
<h1>Thun</h1>
|
||||
<p>A Dialect of Joy.</p>
|
||||
<p>version 0.5.0</p>
|
||||
<p>Version 0.5.0</p>
|
||||
<blockquote>
|
||||
<p>Simple pleasures are the best.</p>
|
||||
</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
|
||||
Joy and its deeper facets as well as how to program in it and several
|
||||
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>
|
||||
<p>Here is an example of Joy code:</p>
|
||||
<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
|
||||
</code></pre>
|
||||
<h2>Documentation</h2>
|
||||
<h3>Jupyter Notebooks</h3>
|
||||
<p><a href="/notebooks/index.html">Notebooks</a></p>
|
||||
<p>The docs/notebooks dir contains Jupyter notebooks, ... TODO</p>
|
||||
<h3>Function Reference</h3>
|
||||
<p><a href="/FuncRef.html">Function Reference</a></p>
|
||||
<h3><a href="/notebooks/index.html">Jupyter Notebooks</a></h3>
|
||||
<h3><a href="/FuncRef.html">Function Reference</a></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>
|
||||
<p>Joy is stack-based. There is a main stack that holds data items:
|
||||
integers, bools, symbols, and sequences or quotes which hold
|
||||
data items themselves.</p>
|
||||
<pre><code>23 dup [21 18 /] [1 [2 [3]]]
|
||||
<p>Joy is built around three things: a <strong>stack</strong> of data items, an <strong>expression</strong>
|
||||
representing a program to evaluate, and a <strong>dictionary</strong> of named functions.</p>
|
||||
<p>Joy is <a href="https://en.wikipedia.org/wiki/Stack-oriented_programming_language">stack-based</a>.
|
||||
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>
|
||||
<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
|
||||
by iterating through the terms in the expression, putting all literals
|
||||
onto the main stack and executing functions as they are encountered.
|
||||
Functions receive the current stack and return the next stack.</p>
|
||||
by iterating through the terms in an expression putting all literals (integers, bools, or lists)
|
||||
onto the main stack and executing functions named by symbols as they are encountered.
|
||||
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>
|
||||
<pre><code>joy? 1 2 3
|
||||
. 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?
|
||||
</code></pre>
|
||||
<p>TODO</p>
|
||||
<h3>Combinators</h3>
|
||||
<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
|
||||
stack and run them in various ways. These combinators factor specific
|
||||
patterns that provide the effect of control-flow in other languages (such
|
||||
as ifte which is like if..then..else..) Combinators receive the current
|
||||
are called <strong>combinators</strong>. These 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. 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
|
||||
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 >] [dup --] while
|
||||
|
||||
...
|
||||
|
||||
-> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
|
||||
23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
|
||||
</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 & 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>
|
||||
<p>Copyright © 2014-2022 Simon Forman</p>
|
||||
<p>This file is part of Thun</p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue