Rework docs, simpler (no Sphinx.)
This commit is contained in:
Simon Forman
parent
68838155dc
commit
fe6567fd9e
102
README.md
102
README.md
|
|
@ -1,8 +1,10 @@
|
|||
Thun
|
||||
# Thun
|
||||
|
||||
A Dialect of Joy.
|
||||
|
||||
v0.4.2
|
||||
version 0.5.0
|
||||
|
||||
> Simple pleasures are the best.
|
||||
|
||||
Joy is a programming language created by Manfred von Thun that is easy to
|
||||
use and understand and has many other nice properties. This project
|
||||
|
|
@ -10,72 +12,101 @@ implements interpreters for a dialect that attempts to stay very close to
|
|||
the spirit of Joy but does not precisely match the behaviour of the
|
||||
original version written in C.
|
||||
|
||||
Joy is:
|
||||
|
||||
* [Purely Functional](https://en.wikipedia.org/wiki/Purely_functional_programming)
|
||||
* [Stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language)
|
||||
* [Concatinative](https://en.wikipedia.org/wiki/Concatenative_programming_language) (See also [concatenative.org](http://www.concatenative.org/wiki/view/Concatenative%20language))
|
||||
* [Categorical](https://joypy.osdn.io/notebooks/Categorical.html)
|
||||
|
||||
The best source (no pun intended) for learning about Joy is the
|
||||
information made available at the website of La Trobe University (see the
|
||||
references section below for the URL) which contains source code for the
|
||||
original C interpreter, Joy language source code for various functions,
|
||||
information made available at the
|
||||
[website of La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
|
||||
which contains source code for the original C interpreter, Joy language source code for various functions,
|
||||
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.
|
||||
|
||||
|
||||
Directory structure
|
||||
## Example Code
|
||||
|
||||
Here is an example of Joy code:
|
||||
|
||||
[ [[abs] ii <=]
|
||||
[
|
||||
[<>] [pop !-] ||
|
||||
] &&
|
||||
]
|
||||
[[ !-] [[++]] [[--]] ifte dip]
|
||||
[[pop !-] [--] [++] ifte ]
|
||||
ifte
|
||||
|
||||
It might seem unreadable but with a little familiarity it becomes just as legible as any other notation.
|
||||
|
||||
This function accepts two integers on the stack and increments or
|
||||
decrements one of them such that the new pair of numbers is the next
|
||||
coordinate pair in a square spiral (like the kind used to construct an
|
||||
[Ulam Spiral](https://en.wikipedia.org/wiki/Ulam_spiral)
|
||||
). For more information see [Square Spiral Example Joy Code](/notebooks/Square_Spiral.html)
|
||||
|
||||
|
||||
## Project Hosted on [OSDN](https://osdn.net/projects/joypy/)
|
||||
|
||||
* [Source Repository](https://osdn.net/projects/joypy/scm/git/Thun/) ([mirror](https://github.com/calroc/Thun))
|
||||
* [Bug tracker](https://todo.sr.ht/~sforman/thun-der) ([old tracker](https://osdn.net/projects/joypy/ticket/))
|
||||
* [Forums](https://osdn.net/projects/joypy/forums/)
|
||||
* [Mailing list](https://osdn.net/projects/joypy/lists/)
|
||||
|
||||
|
||||
## Directory structure
|
||||
|
||||
Thun
|
||||
|
|
||||
|-- LICENSE - GPLv3
|
||||
|-- README - this file
|
||||
|-- README.md - this file
|
||||
|
|
||||
|-- archive
|
||||
| |-- Joy-Programming.zip
|
||||
| `-- README
|
||||
|
|
||||
|-- docs
|
||||
| |-- Makefile - Generate https://joypy.osdn.io/ site.
|
||||
| |-- notebooks - Jupyter Notebooks and supporting modules
|
||||
| |-- reference - Docs for each function.
|
||||
| |-- sphinx_docs - Generate https://joypy.osdn.io/ site.
|
||||
| |-- dep-graphs - Generated dependency graphs.
|
||||
| `-- README - Table of Contents
|
||||
|
|
||||
`-- implementations
|
||||
|
|
||||
|-- Nim - interpreter
|
||||
|
|
||||
|-- Prolog - interpreter
|
||||
| type inference
|
||||
| work-in-progress compiler
|
||||
|
|
||||
|-- Python - interpreter
|
||||
|-- Rust - work-in-progress interpreter
|
||||
|
|
||||
`-- defs.txt - common Joy definitions for all interpreters
|
||||
|
||||
|
||||
Documentation
|
||||
## Documentation
|
||||
|
||||
Jupyter Notebooks
|
||||
### Jupyter Notebooks
|
||||
|
||||
The docs/notebooks dir contains Jupyter notebooks, ... TODO
|
||||
|
||||
Sphinx Docs
|
||||
### Building the Docs
|
||||
|
||||
Some of the documentation is in the form of ReST files in
|
||||
docs/sphinx_docs dir.
|
||||
|
||||
Building the Docs
|
||||
|
||||
Building the documentation is a little tricky at the moment. It involves
|
||||
a makefile that uses nbconvert to generate ReST files from some of the
|
||||
notebooks, copies those to the sphinx source dir, then builds the HTML
|
||||
output using sphinx.
|
||||
|
||||
Get the dependencies for (re)building the docs:
|
||||
|
||||
pip install Thun[build-docs]
|
||||
make docs
|
||||
Run `make` in the `docs` directory.
|
||||
|
||||
|
||||
Basics of Joy
|
||||
## Basics of Joy
|
||||
|
||||
Joy is stack-based. There is a main stack that holds data items:
|
||||
integers, floats, strings, functions, and sequences or quotes which hold
|
||||
integers, bools, symbols, and sequences or quotes which hold
|
||||
data items themselves.
|
||||
|
||||
23 1.8 'a string' "another" dup [21 18 /] [1 [2 [3]]]
|
||||
23 dup [21 18 /] [1 [2 [3]]]
|
||||
|
||||
A Joy expression is just a sequence (a.k.a. "list") of items. Sequences
|
||||
intended as programs are called "quoted programs". Evaluation proceeds
|
||||
|
|
@ -84,7 +115,7 @@ onto the main stack and executing functions as they are encountered.
|
|||
Functions receive the current stack and return the next stack.
|
||||
|
||||
|
||||
Literals and Simple Functions
|
||||
### Literals and Simple Functions
|
||||
|
||||
joy? 1 2 3
|
||||
. 1 2 3
|
||||
|
|
@ -111,7 +142,7 @@ Literals and Simple Functions
|
|||
joy?
|
||||
|
||||
|
||||
Combinators
|
||||
### 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
|
||||
|
|
@ -132,7 +163,7 @@ by changing the pending expression and intermediate state is put there.
|
|||
-> 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:
|
||||
## TODO:
|
||||
|
||||
§.4.4 Definitions and More Elaborate Functions
|
||||
|
||||
|
|
@ -144,12 +175,9 @@ TODO:
|
|||
§.6 References & Further Reading
|
||||
|
||||
|
||||
Wikipedia entry for Joy:
|
||||
https://en.wikipedia.org/wiki/Joy_%28programming_language%29
|
||||
[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
|
||||
[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
README=../README.md
|
||||
BUILD_SCRIPT=build_index.py
|
||||
GENERATOR=python $(BUILD_SCRIPT)
|
||||
HTML_OUTPUT_DIR=./html
|
||||
|
||||
|
||||
all: $(HTML_OUTPUT_DIR)/index.html
|
||||
|
||||
$(HTML_OUTPUT_DIR)/index.html: $(README) $(BUILD_SCRIPT)
|
||||
$(GENERATOR) $(README) > $(HTML_OUTPUT_DIR)/index.html
|
||||
|
||||
|
||||
# python -m markdown -f index.html -o html $(README)
|
||||
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
import sys
|
||||
import markdown
|
||||
|
||||
filename = '/usr/home/sforman/src/Joypy/README.md'
|
||||
##filename = sys.argv[-1]
|
||||
with open(filename) as f:
|
||||
text = f.read()
|
||||
|
||||
html = markdown.markdown(text, output_format="html5")
|
||||
|
||||
print(f'''\
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Thun</title>
|
||||
<link rel="stylesheet" href="/css/site.css">
|
||||
</head>
|
||||
<body>
|
||||
{html}
|
||||
</body>
|
||||
</html>
|
||||
''')
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,33 @@
|
|||
@import url('https://fonts.googleapis.com/css2?family=EB+Garamond&family=Inconsolata&display=swap');
|
||||
|
||||
|
||||
body {
|
||||
background: #fff;
|
||||
color: black;
|
||||
font-family: 'EB Garamond 12';
|
||||
}
|
||||
|
||||
footer {
|
||||
margin-top: 2em;
|
||||
font-family: 'EB Garamond SC 08';
|
||||
font-size: x-small;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
pre {
|
||||
font-size: large;
|
||||
margin-left: 2em;
|
||||
margin-bottom: 1em;
|
||||
font-family: 'Inconsolata';
|
||||
}
|
||||
|
||||
blockquote {
|
||||
background: #eee;
|
||||
background: #eee;
|
||||
border-left: 0.2em solid black;
|
||||
padding: 0.5em;
|
||||
}
|
||||
|
||||
img {
|
||||
width: 30%;
|
||||
}
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Thun</title>
|
||||
<link rel="stylesheet" href="/css/site.css">
|
||||
</head>
|
||||
<body>
|
||||
<h1>Thun</h1>
|
||||
<p>A Dialect of Joy.</p>
|
||||
<p>version 0.5.0</p>
|
||||
<blockquote>
|
||||
<p>Simple pleasures are the best.</p>
|
||||
</blockquote>
|
||||
<p>Joy is a programming language created by Manfred von Thun that is easy to
|
||||
use and understand and has many other nice properties. This project
|
||||
implements interpreters for a dialect that attempts to stay very close to
|
||||
the spirit of Joy but does not precisely match the behaviour of the
|
||||
original version written in C.</p>
|
||||
<p>Joy is:</p>
|
||||
<ul>
|
||||
<li><a href="https://en.wikipedia.org/wiki/Purely_functional_programming">Purely Functional</a></li>
|
||||
<li><a href="https://en.wikipedia.org/wiki/Stack-oriented_programming_language">Stack-based</a></li>
|
||||
<li><a href="https://en.wikipedia.org/wiki/Concatenative_programming_language">Concatinative</a> (See also <a href="http://www.concatenative.org/wiki/view/Concatenative%20language">concatenative.org</a>)</li>
|
||||
<li><a href="https://joypy.osdn.io/notebooks/Categorical.html">Categorical</a></li>
|
||||
</ul>
|
||||
<p>The best source (no pun intended) for learning about Joy is the
|
||||
information made available at the
|
||||
<a href="http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language">website of La Trobe University</a>
|
||||
which contains source code for the original C interpreter, Joy language source code for various functions,
|
||||
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>
|
||||
<h2>Example Code</h2>
|
||||
<p>Here is an example of Joy code:</p>
|
||||
<pre><code>[ [[abs] ii <=]
|
||||
[
|
||||
[<>] [pop !-] ||
|
||||
] &&
|
||||
]
|
||||
[[ !-] [[++]] [[--]] ifte dip]
|
||||
[[pop !-] [--] [++] ifte ]
|
||||
ifte
|
||||
</code></pre>
|
||||
<p>It might seem unreadable but with a little familiarity it becomes just as legible as any other notation.</p>
|
||||
<p>This function accepts two integers on the stack and increments or
|
||||
decrements one of them such that the new pair of numbers is the next
|
||||
coordinate pair in a square spiral (like the kind used to construct an
|
||||
<a href="https://en.wikipedia.org/wiki/Ulam_spiral">Ulam Spiral</a>
|
||||
). For more information see <a href="/notebooks/Square_Spiral.html">Square Spiral Example Joy Code</a></p>
|
||||
<h2>Project Hosted on <a href="https://osdn.net/projects/joypy/">OSDN</a></h2>
|
||||
<ul>
|
||||
<li><a href="https://osdn.net/projects/joypy/scm/git/Thun/">Source Repository</a> (<a href="https://github.com/calroc/Thun">mirror</a>)</li>
|
||||
<li><a href="https://todo.sr.ht/~sforman/thun-der">Bug tracker</a> (<a href="https://osdn.net/projects/joypy/ticket/">old tracker</a>)</li>
|
||||
<li><a href="https://osdn.net/projects/joypy/forums/">Forums</a></li>
|
||||
<li><a href="https://osdn.net/projects/joypy/lists/">Mailing list</a></li>
|
||||
</ul>
|
||||
<h2>Directory structure</h2>
|
||||
<pre><code>Thun
|
||||
|
|
||||
|-- LICENSE - GPLv3
|
||||
|-- README.md - this file
|
||||
|
|
||||
|-- archive
|
||||
| |-- Joy-Programming.zip
|
||||
| `-- README
|
||||
|
|
||||
|-- docs
|
||||
| |-- Makefile - Generate https://joypy.osdn.io/ site.
|
||||
| |-- notebooks - Jupyter Notebooks and supporting modules
|
||||
| |-- reference - Docs for each function.
|
||||
| |-- dep-graphs - Generated dependency graphs.
|
||||
| `-- README - Table of Contents
|
||||
|
|
||||
`-- implementations
|
||||
|
|
||||
|-- Nim - interpreter
|
||||
|
|
||||
|-- Prolog - interpreter
|
||||
| type inference
|
||||
| work-in-progress compiler
|
||||
|
|
||||
|-- Python - interpreter
|
||||
|
|
||||
`-- defs.txt - common Joy definitions for all interpreters
|
||||
</code></pre>
|
||||
<h2>Documentation</h2>
|
||||
<h3>Jupyter Notebooks</h3>
|
||||
<p>The docs/notebooks dir contains Jupyter notebooks, ... TODO</p>
|
||||
<h3>Building the Docs</h3>
|
||||
<p>Run <code>make</code> in the <code>docs</code> directory.</p>
|
||||
<h2>Basics of Joy</h2>
|
||||
<p>Joy is stack-based. There is a main stack that holds data items:
|
||||
integers, floats, strings, functions, and sequences or quotes which hold
|
||||
data items themselves.</p>
|
||||
<pre><code>23 1.8 'a string' "another" dup [21 18 /] [1 [2 [3]]]
|
||||
</code></pre>
|
||||
<p>A Joy expression is just a sequence (a.k.a. "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>
|
||||
<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>
|
||||
<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
|
||||
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
|
||||
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>
|
||||
<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
|
||||
</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>
|
||||
<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>
|
||||
<p>Thun is free software: you can redistribute it and/or modify it under the
|
||||
terms of the GNU General Public License as published by the Free Software
|
||||
Foundation, either version 3 of the License, or (at your option) any
|
||||
later version.</p>
|
||||
<p>Thun is distributed in the hope that it will be useful, but WITHOUT ANY
|
||||
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
||||
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>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
Reference in New Issue