diff --git a/README.md b/README.md index 52c6efa..986f232 100644 --- a/README.md +++ b/README.md @@ -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 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 -started as a Python project called "Joypy", but after someone claimed that -name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun. -Now there are interpreters implemented in several additional languages -(C, Elm, Nim, OCaml, Prolog, Rust). +started as a Python project called "Joypy", but after someone claimed +that name on PyPI before me I renamed it to Thun in honor of Manfred Von +Thun. Now there are interpreters implemented in several additional +languages (C, Elm, Nim, OCaml, Prolog, and Scheme). Joy is: @@ -24,14 +24,14 @@ Joy is: (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](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language) -| [(mirror)](https://www.kevinalbrecht.com/code/joy-mirror/) -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. +The best source for learning about Joy is the information made available +at the [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 +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. * [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) @@ -56,7 +56,8 @@ For more information see [Square Spiral Example Joy Code](https://joypy.osdn.io/ _then [ !-] [[++]] [[--]] ifte dip _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) @@ -71,25 +72,24 @@ It might seem unreadable but with familiarity it becomes as legible as any other ## Documentation -This document describes Joy in a general way below, however most of the -documentation is in the form of [Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html) +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) that go into more detail. **[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 function and combinator by name and gives a brief description. (It's usually out of date, I'm working on it.) **[Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference)** - - -### 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.) +There is more in the `docs` directory but it's kind of a mess right now +(Aug 2023). ## Directory structure @@ -111,14 +111,15 @@ that. Really you need to run (GNU) make in the `docs/notebooks` and |-- implementations | |-- defs.txt - common Joy definitions for all interpreters | |-- C - interpreter - | |-- GNUProlog - interpreter - | | type inference - | | work-in-progress compiler - | | + | |-- GNU Prolog - type inference | |-- Elm - interpreter | |-- Nim - 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. `-- bigints @@ -131,175 +132,17 @@ Clone the repo: 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. -You can put the binaries in your ``PATH``.) +There isn't really any installation as such. You can put the binaries in +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 -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 . - diff --git a/Thun.md b/Thun.md index 17317b0..0d45846 100644 --- a/Thun.md +++ b/Thun.md @@ -1,23 +1,10 @@ -# Thun - -A Dialect of Joy. +# Thun Specification 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 -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, Booleans `true` and `false`, lists enclosed by square brackets `[` and `]`, or symbols (names of functions.) @@ -56,13 +43,13 @@ but the Thun dialect currently only uses four: ## 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__ of named functions. ### Stack -Joy is +Thun 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 @@ -86,7 +73,7 @@ From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vec ### 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 by iterating through the terms in an expression putting all literals (integers, bools, or lists) onto the main stack and executing functions @@ -96,14 +83,14 @@ 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. +The __dictionary__ associates symbols (names) with Thun expressions that +define the available functions of the Thun system. Together the stack, +expression, and dictionary are the entire state of the Thun 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 putting values onto the stack and delegating execution to functions which it looks up in the dictionary. @@ -118,6 +105,9 @@ expression (aka "continuation".) ## 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 @@ -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 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 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 @@ -221,7 +211,7 @@ leading to an error. 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, -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.) diff --git a/docs/html/css/site.css b/docs/html/css/site.css index 1e0d77d..ff4e257 100644 --- a/docs/html/css/site.css +++ b/docs/html/css/site.css @@ -13,14 +13,16 @@ footer { } pre { + background: #eee; font-size: large; margin-left: 2em; + margin-right: 2em; margin-bottom: 1em; font-family: 'Inconsolata'; + padding: 0.5em; } blockquote { - background: #eee; background: #eee; border-left: 0.2em solid black; padding: 0.5em; diff --git a/docs/misc/neat-talk.txt b/docs/misc/neat-talk.txt index 73509d5..22435a0 100644 --- a/docs/misc/neat-talk.txt +++ b/docs/misc/neat-talk.txt @@ -4,6 +4,5 @@ https://www.youtube.com/watch?v=_IgqJr8jG8M -"Complete and Easy Bidirectional Typechecking -for Higher-Rank Polymorphism" +"Complete and Easy Bidirectional Typechecking for Higher-Rank Polymorphism" diff --git a/docs/misc/words.txt b/docs/misc/words.txt index 7086877..f41fdbf 100644 --- a/docs/misc/words.txt +++ b/docs/misc/words.txt @@ -284,3 +284,43 @@ List Manipulation 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` | | | + + diff --git a/docs/source/index.md b/docs/source/index.md index e878d77..080a412 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -49,9 +49,9 @@ For more information see [Square Spiral Example Joy Code](/notebooks/Square_Spir square_spiral [_p] [_then] [_else] ifte - _p [_p0] [_p1] && + _p [_p0] [_p1] and _p0 [abs] ii <= - _p1 [<>] [pop !-] || + _p1 [<>] [pop !-] or _then [ !-] [[++]] [[--]] ifte dip _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 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 [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).