A Dialect of Joy.
-version 0.5.0
+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
-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](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. 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, and Scheme).
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))
+* [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](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.
+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)
+ [(Kevin Albrecht's mirror)](https://www.kevinalbrecht.com/code/joy-mirror/)
+* [The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/)
-## Example Code
-Here is an example of Joy code:
+## Example Code
- square_spiral ≡ [_p] [_then] [_else] ifte
+Here is an example of Joy code. This function `square_spiral` accepts
+two integers 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](https://joypy.osdn.io/notebooks/Square_Spiral.html).
- _p ≡ [_p0] [_p1] &&
- _p0 ≡ [abs] ii <=
- _p1 ≡ [<>] [pop !-] ||
+ square_spiral [p] [then] [else] ifte
- _then ≡ [ !-] [[++]] [[--]] ifte dip
- _else ≡ [pop !-] [--] [++] ifte
+ p [p0] [p1] and
+ p0 [abs] ii <=
+ p1 [<>] [pop !-] or
-It might seem unreadable but with a little familiarity it becomes just as legible as any other notation.
+ then [ !-] [[++]] [[--]] ifte dip
+ else [pop !-] [--] [++] ifte
-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)
+It might seem unreadable but with familiarity it becomes as legible as
+any other notation.
-## Project Hosted on [OSDN](https://osdn.net/projects/joypy/)
+## Project Hosted on [SourceHut](https://git.sr.ht/~sforman/Thun)
-* [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/))
+* [Source Repository](https://git.sr.ht/~sforman/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.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
-
-
## Documentation
-### Jupyter Notebooks
-
-[Notebooks](/notebooks/index.html)
-
-The docs/notebooks dir contains Jupyter notebooks, ... TODO
-
-### Function Reference
-
-[Function Reference](/FuncRef.html)
-
-### Building the Docs
-
-Run `make` in the `docs` directory.
-
-
-## 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.
-
- 23 dup [21 18 /] [1 [2 [3]]]
+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.
-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.
+**[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.
-### Literals and Simple Functions
+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.)
- joy? 1 2 3
- . 1 2 3
- 1 . 2 3
- 1 2 . 3
- 1 2 3 .
+**[Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference)**
- 1 2 3 <-top
+There is more in the `docs` directory but it's kind of a mess right now
+(Aug 2023).
- joy? + +
- 1 2 3 . + +
- 1 5 . +
- 6 .
- 6 <-top
-
- joy? 7 *
- 6 . 7 *
- 6 7 . *
- 42 .
-
- 42 <-top
-
- joy?
-
-
-### 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
-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
-
- ...
-
- -> 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:
+## Directory structure
-§.4.4 Definitions and More Elaborate Functions
+ Thun
+ |-- LICENSE - GPLv3
+ |-- README.md - this file
+ |
+ |-- archive
+ | |-- Joy-Programming.zip
+ | `-- README
+ |
+ |-- docs
+ | |-- dep-graphs - Generated dependency graphs.
+ | |-- html - Generated HTML docs.
+ | |-- notebooks - Jupyter Notebooks and supporting modules
+ | `-- reference - Docs for each function.
+ |
+ |-- implementations
+ | |-- defs.txt - common Joy definitions for all interpreters
+ | |-- C - interpreter
+ | |-- GNU Prolog - type inference
+ | |-- Elm - interpreter
+ | |-- Nim - interpreter
+ | |-- Ocaml - work-in-progress interpreter
+ | |-- Python - interpreter
+ | |-- Scheme - interpreter
+ | `-- SWI Prolog - interpreter
+ | type inference
+ | work-in-progress compiler
+ |
+ `-- joy_code - Source code written in Joy.
+ `-- bigints
+ `-- bigints.joy
-§.4.5 Programming and Metaprogramming
-§.4.6 Refactoring
+## Installation
+Clone the repo:
-§.6 References & Further Reading
+ git clone https://git.sr.ht/~sforman/Thun
+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.)
-[Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29)
+There isn't really any installation as such. You can put the binaries in
+your ``PATH``.
-[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
---------------------------------------------------
-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
--------------------------------------------------
-Copyright © 2014-2022 Simon Forman
+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 <http://www.gnu.org/licenses/>.
-
OSDN Git Service
