7 > Simple pleasures are the best.
9 [Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29) is a
10 programming language created by Manfred von Thun that is easy to use and
11 understand and has many other nice properties. **Thun** is a dialect of
12 Joy that attempts to stay very close to the spirit of Joy but does not
13 precisely match the behaviour of the original version written in C. It
14 started as a Python project called "Joypy", but after someone claimed that
15 name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun.
16 Now there are interpreters implemented in several additional languages
17 (C, Nim, Prolog, Rust).
21 * [Purely Functional](https://en.wikipedia.org/wiki/Purely_functional_programming)
22 * [Stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language)
23 * [Concatinative](https://en.wikipedia.org/wiki/Concatenative_programming_language)
24 (See also [concatenative.org](http://www.concatenative.org/wiki/view/Concatenative%20language))
25 * [Categorical](https://joypy.osdn.io/notebooks/Categorical.html)
27 The best source (no pun intended) for learning about Joy is the
28 information made available at the
29 [website of La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
30 | [(mirror)](https://www.kevinalbrecht.com/code/joy-mirror/)
31 which contains source code for the original C interpreter, Joy language source code for various functions,
32 and a great deal of fascinating material mostly written by Von Thun on
33 Joy and its deeper facets as well as how to program in it and several
34 interesting aspects. It's quite a treasure trove.
36 * [Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29)
37 * [Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language)
38 [(Kevin Albrecht's mirror)](https://www.kevinalbrecht.com/code/joy-mirror/)
39 * [The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/)
44 Here is an example of Joy code. This function `square_spiral` accepts
45 two integers and increments or decrements one of them such that the new
46 pair of numbers is the next coordinate pair in a square spiral (like the
47 kind used to construct an [Ulam Spiral](https://en.wikipedia.org/wiki/Ulam_spiral)).
48 For more information see [Square Spiral Example Joy Code](https://joypy.osdn.io/notebooks/Square_Spiral.html).
50 square_spiral [_p] [_then] [_else] ifte
56 _then [ !-] [[++]] [[--]] ifte dip
57 _else [pop !-] [--] [++] ifte
59 It might seem unreadable but with familiarity it becomes as legible as any other notation.
62 ## Project Hosted on [SourceHut](https://git.sr.ht/~sforman/Thun)
64 * [Source Repository](https://git.sr.ht/~sforman/Thun)
65 ([mirror](https://github.com/calroc/Thun))
66 * [Bug tracker](https://todo.sr.ht/~sforman/thun-der)
67 ([old tracker](https://osdn.net/projects/joypy/ticket/))
68 * [Forums](https://osdn.net/projects/joypy/forums/)
69 * [Mailing list](https://osdn.net/projects/joypy/lists/)
74 This document describes Joy in a general way below, however most of the
75 documentation is in the form of [Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html)
76 that go into more detail.
78 **[Jupyter Notebooks](https://joypy.osdn.io/notebooks/index.html)**
80 There's also a [Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference) that lists each
81 function and combinator by name and gives a brief description. (It's
82 usually out of date, I'm working on it.)
84 **[Function Reference](https://git.sr.ht/~sforman/Thun/tree/trunk/item/docs/reference)**
90 Run `make` in the `docs` directory. (This is a lie, it's more complex than
91 that. Really you need to run (GNU) make in the `docs/notebooks` and
92 `docs/reference` dirs first, _then_ run `make` in the `docs` directory.)
95 ## Directory structure
99 |-- README.md - this file
102 | |-- Joy-Programming.zip
106 | |-- dep-graphs - Generated dependency graphs.
107 | |-- html - Generated HTML docs.
108 | |-- notebooks - Jupyter Notebooks and supporting modules
109 | `-- reference - Docs for each function.
112 | |-- defs.txt - common Joy definitions for all interpreters
113 | |-- C - interpreter
114 | |-- GNUProlog - interpreter
116 | | work-in-progress compiler
118 | |-- Nim - interpreter
119 | |-- Ocaml - work-in-progress interpreter
120 | `-- Python - interpreter
122 `-- joy_code - Source code written in Joy.
129 Clone the repo and follow the instructions in the individual
130 `implementations` directories. There isn't really any installation. You
131 can put the binaries in your ``PATH``.
133 (I had the Python package set up to upload to PyPI as "Thun", but the
134 whole Python distribution story seems unsettled at the moment (2023) so
135 I've gone back to the *old ways*: there is a single script ``joy.py``
136 that gets modified (``defs.txt`` is inserted) to create a ``joy`` script
137 that uses the "shebang" trick to pretend to be a binary. In other words,
138 run ``make`` and put the resulting ``joy`` script in your PATH, if that's
139 what you want to do. In a year or two the Python folks will have sorted
140 things out and we can go back to ``pip install Thun`` or whatever.)
145 The original Joy has several datatypes (such as strings and sets)
146 but the Thun dialect currently only uses four:
148 * Integers, signed and unbounded by machine word length (they are
149 [bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).)
150 * Boolean values ``true`` and ``false``.
151 * Lists quoted in `[` and `]` brackets.
154 Joy is built around three things: a __stack__ of data items, an __expression__
155 representing a program to evaluate, and a __dictionary__ of named functions.
159 Joy is [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language).
160 There is a single main __stack__ that holds data items, which can be integers, bools,
161 symbols (names), or sequences of data items enclosed in square brackets (`[` or `]`).
163 We use the terms "stack", "quote", "sequence",
164 "list", and others to mean the same thing: a simple linear datatype that
165 permits certain operations such as iterating and pushing and popping
166 values from (at least) one end.
168 > In describing Joy I have used the term quotation to describe all of the
169 > above, because I needed a word to describe the arguments to combinators
170 > which fulfill the same role in Joy as lambda abstractions (with
171 > variables) fulfill in the more familiar functional languages. I use the
172 > term list for those quotations whose members are what I call literals:
173 > numbers, characters, truth values, sets, strings and other quotations.
174 > All these I call literals because their occurrence in code results in
175 > them being pushed onto the stack. But I also call [London Paris] a list.
176 > So, [dup *] is a quotation but not a list.
178 From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350)
182 A Joy __expression__ is just a sequence or list of items. Sequences
183 intended as programs are called "quoted programs". Evaluation proceeds
184 by iterating through the terms in an expression putting all literals
185 (integers, bools, or lists) onto the main stack and executing functions
186 named by symbols as they are encountered. Functions receive the current
187 stack, expression, and dictionary and return the next stack, expression,
192 The __dictionary__ associates symbols (names) with Joy expressions that
193 define the available functions of the Joy system. Together the stack,
194 expression, and dictionary are the entire state of the Joy interpreter.
198 The Joy interpreter is extrememly simple. It accepts a stack, an
199 expression, and a dictionary, and it iterates through the expression
200 putting values onto the stack and delegating execution to functions which
201 it looks up in the dictionary.
203 ![Joy Interpreter Flowchart](https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg)
205 All control flow works by
206 [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).
207 __Combinators__ (see below) alter control flow by prepending quoted programs to the pending
208 expression (aka "continuation".)
210 -------------------------------
212 From here it kinda falls apart...
214 ### Literals and Simple Functions
221 The main loop is very simple as most of the action happens through what
222 are called __combinators__. These are functions which accept quoted programs on the
223 stack and run them in various ways. These combinators reify specific
224 control-flow patterns (such as `ifte` which is like `if.. then.. else..` in other
225 languages.) Combinators receive the current
226 expession in addition to the stack and return the next expression. They
227 work by changing the pending expression the interpreter is about to
228 execute. (The combinators could work by making recursive calls to the
229 interpreter and all intermediate state would be held in the call stack of
230 the implementation language, in this joy implementation they work instead
231 by changing the pending expression and intermediate state is put there.)
233 joy? 23 [0 >] [dup --] while
234 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
239 This is the *basis* set of functions, the rest of functions in the Thun
240 dialect of Joy are defined in terms of these:
266 /\ \/ _\/_ (These are the logical ops that work on Booleans.)
270 | op | Logical (Boolean) | Bitwise (Ints) | Short-Circuiting Combinators |
271 |-----|-------------------|----------------|------------------------------|
272 | AND | `/\` | `&&` | `and ` |
273 | OR | `\/` | `\|\|` | `or` |
274 | XOR | `_\/_` | `xor` | |
278 --------------------------------------------------
280 Copyright © 2014 - 2023 Simon Forman
282 This file is part of Thun
284 Thun is free software: you can redistribute it and/or modify it under the
285 terms of the GNU General Public License as published by the Free Software
286 Foundation, either version 3 of the License, or (at your option) any
289 Thun is distributed in the hope that it will be useful, but WITHOUT ANY
290 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
291 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
294 You should have received a copy of the GNU General Public License along
295 with Thun. If not see <http://www.gnu.org/licenses/>.