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

Minor edits.

This commit is contained in:
sforman 2023-08-13 08:47:16 -07:00
parent 9f78b6d8fd
commit 1f5bea98b6
6 changed files with 94 additions and 233 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
README.md
View File

@ -11,10 +11,10 @@ programming language created by Manfred von Thun that is easy to use and
understand and has many other nice properties. **Thun** is a dialect of understand and has many other nice properties. **Thun** is a dialect of
Joy that attempts to stay very close to the spirit of Joy but does not Joy 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. It precisely match the behaviour of the original version written in C. It
started as a Python project called "Joypy", but after someone claimed that started as a Python project called "Joypy", but after someone claimed
name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun. that name on PyPI before me I renamed it to Thun in honor of Manfred Von
Now there are interpreters implemented in several additional languages Thun. Now there are interpreters implemented in several additional
(C, Elm, Nim, OCaml, Prolog, Rust). languages (C, Elm, Nim, OCaml, Prolog, and Scheme).
Joy is: Joy is:
@ -24,14 +24,14 @@ Joy is:
(See also [concatenative.org](http://www.concatenative.org/wiki/view/Concatenative%20language)) (See also [concatenative.org](http://www.concatenative.org/wiki/view/Concatenative%20language))
* [Categorical](https://joypy.osdn.io/notebooks/Categorical.html) * [Categorical](https://joypy.osdn.io/notebooks/Categorical.html)
The best source (no pun intended) for learning about Joy is the The best source for learning about Joy is the information made available
information made available at the at the [website of La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
[website of La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language) | [(mirror)](https://www.kevinalbrecht.com/code/joy-mirror/) which
| [(mirror)](https://www.kevinalbrecht.com/code/joy-mirror/) contains source code for the original C interpreter, Joy language source
which contains source code for the original C interpreter, Joy language source code for various functions, code for various functions, and a great deal of fascinating material
and a great deal of fascinating material mostly written by Von Thun on mostly written by Von Thun on Joy and its deeper facets as well as how to
Joy and its deeper facets as well as how to program in it and several program in it and several interesting aspects. It's quite a treasure
interesting aspects. It's quite a treasure trove. trove.
* [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)
@ -56,7 +56,8 @@ For more information see [Square Spiral Example Joy Code](https://joypy.osdn.io/
_then [ !-] [[++]] [[--]] ifte dip _then [ !-] [[++]] [[--]] ifte dip
_else [pop !-] [--] [++] ifte _else [pop !-] [--] [++] ifte
It might seem unreadable but with familiarity it becomes as legible as any other notation. It might seem unreadable but with familiarity it becomes as legible as
any other notation.
## Project Hosted on [SourceHut](https://git.sr.ht/~sforman/Thun) ## Project Hosted on [SourceHut](https://git.sr.ht/~sforman/Thun)
@ -71,25 +72,24 @@ It might seem unreadable but with familiarity it becomes as legible as any other
## Documentation ## Documentation
This document describes Joy in a general way below, however most of the The `Thun.md` document describes the Thun dialect. Most of the rest of
documentation is in the form of [Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html) documentation is in the form of
[Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html)
that go into more detail. that go into more detail.
**[Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html)** **[Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html)**
I had a Joy kernel for the Jupyter Notebook system, but I can no longer
figure out how to use it, so I'm rewriting the notebooks by hand.
There's also a [Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference) that lists each There's also a [Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference) that lists each
function and combinator by name and gives a brief description. (It's function and combinator by name and gives a brief description. (It's
usually out of date, I'm working on it.) usually out of date, I'm working on it.)
**[Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference)** **[Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference)**
There is more in the `docs` directory but it's kind of a mess right now
(Aug 2023).
### Building the Docs
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.)
## Directory structure ## Directory structure
@ -111,14 +111,15 @@ that. Really you need to run (GNU) make in the `docs/notebooks` and
|-- implementations |-- implementations
| |-- defs.txt - common Joy definitions for all interpreters | |-- defs.txt - common Joy definitions for all interpreters
| |-- C - interpreter | |-- C - interpreter
| |-- GNUProlog - interpreter | |-- GNU Prolog - type inference
| | type inference
| | work-in-progress compiler
| |
| |-- Elm - interpreter | |-- Elm - interpreter
| |-- Nim - interpreter | |-- Nim - interpreter
| |-- Ocaml - work-in-progress interpreter | |-- Ocaml - work-in-progress interpreter
| `-- Python - interpreter | |-- Python - interpreter
| |-- Scheme - interpreter
| `-- SWI Prolog - interpreter
| type inference
| work-in-progress compiler
| |
`-- joy_code - Source code written in Joy. `-- joy_code - Source code written in Joy.
`-- bigints `-- bigints
@ -131,175 +132,17 @@ Clone the repo:
git clone https://git.sr.ht/~sforman/Thun git clone https://git.sr.ht/~sforman/Thun
Then follow the instructions in the individual `implementations` directories. Then follow the instructions in the individual `implementations`
directories. In most cases you can just run `make` and that will build a
binary called `joy` (in Python it's a script.)
(There isn't really any installation as such. There isn't really any installation as such. You can put the binaries in
You can put the binaries in your ``PATH``.) your ``PATH``.
## Basics of Joy
The original Joy has several datatypes (such as strings and sets)
but the Thun dialect currently only uses four:
* Integers, signed and unbounded by machine word length (they are
[bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).)
* Boolean values ``true`` and ``false``.
* Lists quoted in `[` and `]` brackets.
* Symbols (names).
Joy is built around three things: a __stack__ of data items, an __expression__
representing a program to evaluate, and a __dictionary__ of named functions.
### Stack
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 `]`).
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)
### Expression
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 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, expression,
and dictionary.
### Dictionary
The __dictionary__ associates symbols (names) 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.
### Interpreter
The Joy interpreter 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.
![Joy Interpreter Flowchart](https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg)
All control flow works by
[Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).
__Combinators__ (see below) alter control flow by prepending quoted programs to the pending
expression (aka "continuation".)
-------------------------------
From here it kinda falls apart...
### Literals and Simple Functions
TODO
### Combinators
The main loop is very simple as most of the action happens through what
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
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.)
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
### Core Words
This is the *basis* set of functions, the rest of functions in the Thun
dialect of Joy are defined in terms of these:
branch
dip
i
loop
clear
concat
cons
dup
first
pop
rest
stack
swaack
swap
truthy
inscribe
+ - * / %
< > >= <= != <> =
not
They could be grouped:
- Combinators (`branch` `dip` `i` `loop`)
- Stack Chatter (`clear` `dup` `pop` `stack` `swaack` `swap`)
- List Manipulation (`concat` `cons` `first` `rest`)
- Math (`+` `-` `*` `/` `%`)
- Comparison (`<` `>` `>=` `<=` `!=` `<>` `=`)
- Logic (`truthy` `not`)
- Programming (`inscribe`)
Some of these could be definitions, but we don't want to be completely
minimal at the cost of efficiency, eh?
rest == [pop] infra
Also, custom error messages are nice? (E.g. `rest` has a distinct error
from `pop`, at least in the current design.)
### AND, OR, XOR, NOT
There are three families (categories?) of these operations:
1. Logical ops that take and return Boolean values.
2. Bitwise ops that treat integers as bit-strings.
3. Short-Circuiting Combinators that accept two quoted programs
and run top quote *iff* the second doesn't suffice to resolve the clause.
(in other words `[A] [B] and` runs `B` only if `A` evaluates to `true`,
and similarly for `or` but only if `A` evaluates to `false`.)
(So far, only the Elm interpreter implements the bitwise ops. The others
two kinds of ops are defined in the `defs.txt` file, but you could implement
them in host language for greater efficiency if you like.)
| op | Logical (Boolean) | Bitwise (Ints) | Short-Circuiting Combinators |
|-----|-------------------|----------------|------------------------------|
| AND | `/\` | `&&` | `and ` |
| OR | `\/` | `\|\|` | `or` |
| XOR | `_\/_` | `xor` | |
| NOT | `not` | | |
-------------------------------------------------- --------------------------------------------------
@ -308,16 +151,3 @@ Copyright © 2014 - 2023 Simon Forman
This file is part of Thun This file is part of Thun
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.
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.
You should have received a copy of the GNU General Public License along
with Thun. If not see <http://www.gnu.org/licenses/>.

38
Thun.md
View File

@ -1,23 +1,10 @@
# Thun # Thun Specification
A Dialect of Joy.
Version 0.5.0 Version 0.5.0
> Simple pleasures are the best.
[Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29) is a
programming language created by Manfred von Thun that is easy to use and
understand and has many other nice properties. **Thun** is a dialect of
Joy 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.
(In the rest of this document I'll use the names Joy and Thun
interchangably.)
## Grammar ## Grammar
The grammar of Joy is very simple. A Joy expression is zero or more Joy 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, terms separated by blanks. Terms can be integers in decimal notation,
Booleans `true` and `false`, lists enclosed by square brackets `[` and `]`, Booleans `true` and `false`, lists enclosed by square brackets `[` and `]`,
or symbols (names of functions.) or symbols (names of functions.)
@ -56,13 +43,13 @@ but the Thun dialect currently only uses four:
## Stack, Expression, Dictionary ## Stack, Expression, Dictionary
Joy is built around three things: a __stack__ of data items, an Thun is built around three things: a __stack__ of data items, an
__expression__ representing a program to evaluate, and a __dictionary__ __expression__ representing a program to evaluate, and a __dictionary__
of named functions. of named functions.
### Stack ### Stack
Joy is Thun is
[stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language). [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language).
There is a single main __stack__ that holds data items, which can be There is a single main __stack__ that holds data items, which can be
integers, bools, symbols (names), or sequences of data items enclosed in integers, bools, symbols (names), or sequences of data items enclosed in
@ -86,7 +73,7 @@ From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vec
### Expression ### Expression
A Joy __expression__ is just a sequence or list of items. Sequences A Thun __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 an 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 (integers, bools, or lists) onto the main stack and executing functions
@ -96,14 +83,14 @@ and dictionary.
### Dictionary ### Dictionary
The __dictionary__ associates symbols (names) with Joy expressions that The __dictionary__ associates symbols (names) with Thun expressions that
define the available functions of the Joy system. Together the stack, define the available functions of the Thun system. Together the stack,
expression, and dictionary are the entire state of the Joy interpreter. expression, and dictionary are the entire state of the Thun interpreter.
## Interpreter ## Interpreter
The Joy interpreter is extrememly simple. It accepts a stack, an The Thun interpreter is extremely simple. It accepts a stack, an
expression, and a dictionary, and it iterates through the expression expression, and a dictionary, and it iterates through the expression
putting values onto the stack and delegating execution to functions which putting values onto the stack and delegating execution to functions which
it looks up in the dictionary. it looks up in the dictionary.
@ -118,6 +105,9 @@ expression (aka "continuation".)
## Literals, Functions, Combinators ## Literals, Functions, Combinators
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").
### Literals ### Literals
@ -167,7 +157,7 @@ The definitions form a DAG (Directed Acyclic Graph) (there is actually a
cycle in the definition of `genrec` but that's the point, it is a cycle cycle in the definition of `genrec` but that's the point, it is a cycle
to itself that captures the cyclical nature of recursive definitions.) to itself that captures the cyclical nature of recursive definitions.)
I don't imagine that people will read `defs.txt` to understand Joy code. I don't imagine that people will read `defs.txt` to understand Thun code.
Instead people should read the notebooks that derive the functions to Instead people should read the notebooks that derive the functions to
understand them. The reference docs should help, and to that end I'd understand them. The reference docs should help, and to that end I'd
like to cross-link them with the notebooks. The idea is that the docs like to cross-link them with the notebooks. The idea is that the docs
@ -221,7 +211,7 @@ leading to an error.
I don't see an easy way around this. Be careful? It's kind of against I don't see an easy way around this. Be careful? It's kind of against
the spirit of the thing to just leave a footgun like that laying around, 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 Joy code by 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.) derivation seems to lead to bug-free code, which is the kinda the point.)

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

@ -13,14 +13,16 @@ footer {
} }
pre { pre {
background: #eee;
font-size: large; font-size: large;
margin-left: 2em; margin-left: 2em;
margin-right: 2em;
margin-bottom: 1em; margin-bottom: 1em;
font-family: 'Inconsolata'; font-family: 'Inconsolata';
padding: 0.5em;
} }
blockquote { blockquote {
background: #eee;
background: #eee; background: #eee;
border-left: 0.2em solid black; border-left: 0.2em solid black;
padding: 0.5em; padding: 0.5em;

3
docs/misc/neat-talk.txt
View File

@ -4,6 +4,5 @@ https://www.youtube.com/watch?v=_IgqJr8jG8M
"Complete and Easy Bidirectional Typechecking "Complete and Easy Bidirectional Typechecking for Higher-Rank Polymorphism"
for Higher-Rank Polymorphism"

40
docs/misc/words.txt
View File

@ -284,3 +284,43 @@ List Manipulation
concat cons first concat cons first
#############################################
Stashing this here for now
### AND, OR, XOR, NOT
There are three families (categories?) of these operations:
1. Logical ops that take and return Boolean values.
2. Bitwise ops that treat integers as bit-strings.
3. Short-Circuiting Combinators that accept two quoted programs
and run top quote *iff* the second doesn't suffice to resolve the clause.
(in other words `[A] [B] and` runs `B` only if `A` evaluates to `true`,
and similarly for `or` but only if `A` evaluates to `false`.)
(So far, only the Elm interpreter implements the bitwise ops. The others
two kinds of ops are defined in the `defs.txt` file, but you could implement
them in host language for greater efficiency if you like.)
| op | Logical (Boolean) | Bitwise (Ints) | Short-Circuiting Combinators |
|-----|-------------------|----------------|------------------------------|
| AND | `/\` | `&&` | `and ` |
| OR | `\/` | `\|\|` | `or` |
| XOR | `_\/_` | `xor` | |
| NOT | `not` | | |

6
docs/source/index.md
View File

@ -49,9 +49,9 @@ For more information see [Square Spiral Example Joy Code](/notebooks/Square_Spir
square_spiral [_p] [_then] [_else] ifte square_spiral [_p] [_then] [_else] ifte
_p [_p0] [_p1] && _p [_p0] [_p1] and
_p0 [abs] ii <= _p0 [abs] ii <=
_p1 [<>] [pop !-] || _p1 [<>] [pop !-] or
_then [ !-] [[++]] [[--]] ifte dip _then [ !-] [[++]] [[--]] ifte dip
_else [pop !-] [--] [++] ifte _else [pop !-] [--] [++] ifte
@ -200,7 +200,7 @@ expression, and a dictionary, and it iterates through the expression
putting values onto the stack and delegating execution to functions which putting values onto the stack and delegating execution to functions which
it looks up in the dictionary. it looks up in the dictionary.
![Joy Interpreter Flowchart](https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg) ![Joy Interpreter Flowchart](/joy_interpreter_flowchart.svg)
All control flow works by All control flow works by
[Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style). [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).