README.md

   1 # Thun
   2
   3 A Dialect of Joy.
   4
   5 Version 0.5.0
   6
   7 > Simple pleasures are the best.
   8
   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).
  18
  19 Joy is:
  20
  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)
  26
  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.
  35
  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/)
  40
  41
  42 ## Example Code
  43
  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](/notebooks/Square_Spiral.html).
  49
  50     square_spiral [_p] [_then] [_else] ifte
  51
  52     _p  [_p0] [_p1] &&
  53     _p0 [abs] ii <=
  54     _p1 [<>] [pop !-] ||
  55
  56     _then [    !-] [[++]] [[--]] ifte dip
  57     _else [pop !-]  [--]   [++]  ifte
  58
  59 It might seem unreadable but with familiarity it becomes as legible as any other notation.
  60
  61
  62 ## Project Hosted on [SourceHut](https://git.sr.ht/~sforman/Thun)
  63
  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/)
  70
  71
  72 ## Documentation
  73
  74 This document describes Joy in a general way below, however most of the
  75 documentation is in the form of [Jupyter Notebooks](/notebooks/index.html)
  76 that go into more detail.
  77
  78 ### [Jupyter Notebooks](/notebooks/index.html)
  79
  80 There's also a [Function Reference](/FuncRef.html) 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.)
  83
  84 ### [Function Reference](/FuncRef.html)
  85
  86
  87
  88 ### Building the Docs
  89
  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.)
  93
  94
  95 ## Directory structure
  96     Thun
  97     |-- LICENSE - GPLv3
  98     |-- README.md - this file
  99     |
 100     |-- archive
 101     |   |-- Joy-Programming.zip
 102     |   `-- README
 103     |
 104     |-- docs
 105     |   |-- dep-graphs - Generated dependency graphs.
 106     |   |-- html - Generated HTML docs.
 107     |   |-- notebooks - Jupyter Notebooks and supporting modules
 108     |   `-- reference - Docs for each function.
 109     |
 110     |-- implementations
 111     |   |-- defs.txt - common Joy definitions for all interpreters
 112     |   |-- C - interpreter
 113     |   |-- GNUProlog - interpreter
 114         |               type inference
 115         |               work-in-progress compiler
 116     |   |-- Nim - interpreter
 117     |   |-- Ocaml - work-in-progress interpreter
 118     |   `-- Python - interpreter
 119     |
 120     `-- joy_code - Source code written in Joy.
 121         `-- bigints
 122             `-- bigints.joy
 123
 124
 125 ## Installation
 126
 127 Clone the repo and follow the instructions in the individual
 128 `implementations` directories.  There isn't really any installation.  You
 129 can put the binaries in your ``PATH``.
 130
 131 (I had the Python package set up to upload to PyPI as "Thun", but the
 132 whole Python distribution story seems unsettled at the moment (2023) so
 133 I've gone back to the *old ways*: there is a single script ``joy.py``
 134 that gets modified (``defs.txt`` is inserted) to create a ``joy`` script
 135 that uses the "shebang" trick to pretend to be a binary.  In other words,
 136 run ``make`` and put the resulting ``joy`` script in your PATH, if that's
 137 what you want to do.  In a year or two the Python folks will have sorted
 138 things out and we can go back to ``pip install Thun`` or whatever.)
 139
 140
 141 ## Basics of Joy
 142
 143 The original Joy has several datatypes (such as strings and sets)
 144 but the Thun dialect currently only uses four:
 145
 146 * Integers, signed and unbounded by machine word length (they are
 147   [bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).)
 148 * Boolean values ``true`` and ``false``.
 149 * Lists quoted in **[** and **]** brackets.
 150 * Symbols (names).
 151
 152 Joy is built around three things: a __stack__ of data items, an __expression__
 153 representing a program to evaluate, and a __dictionary__ of named functions.
 154
 155 ### Stack
 156
 157 Joy is [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language).
 158 There is a single main __stack__ that holds data items, which can be integers, bools,
 159 symbols (names), or sequences of data items enclosed in square brackets (`[` or `]`).
 160
 161
 162 ### Expression
 163
 164 A Joy __expression__ is just a sequence or list of items.  Sequences
 165 intended as programs are called "quoted programs".  Evaluation proceeds
 166 by iterating through the terms in an expression putting all literals
 167 (integers, bools, or lists) onto the main stack and executing functions
 168 named by symbols as they are encountered.  Functions receive the current
 169 stack, expression, and dictionary and return the next stack, expression,
 170 and dictionary.
 171
 172 ### Dictionary
 173
 174 The __dictionary__ associates symbols (names) with Joy expressions that
 175 define the available functions of the Joy system.  Together the stack,
 176 expression, and dictionary are the entire state of the Joy interpreter.
 177
 178 ### Interpreter
 179
 180 The Joy interpreter is extrememly simple. It accepts a stack, an
 181 expression, and a dictionary, and it iterates through the expression
 182 putting values onto the stack and delegating execution to functions which
 183 it looks up in the dictionary.
 184
 185 All control flow works by
 186 [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).
 187 __Combinators__ (see below) alter control flow by prepending quoted programs to the pending
 188 expression (aka "continuation".)
 189
 190 ![Joy Interpreter Flowchart](https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg)
 191
 192
 193 ## Stack / Quote / List / Sequence
 194
 195 When talking about Joy we use the terms "stack", "quote", "sequence",
 196 "list", and others to mean the same thing: a simple linear datatype that
 197 permits certain operations such as iterating and pushing and popping
 198 values from (at least) one end.
 199
 200 > In describing Joy I have used the term quotation to describe all of the
 201 > above, because I needed a word to describe the arguments to combinators
 202 > which fulfill the same role in Joy as lambda abstractions (with
 203 > variables) fulfill in the more familiar functional languages. I use the
 204 > term list for those quotations whose members are what I call literals:
 205 > numbers, characters, truth values, sets, strings and other quotations.
 206 > All these I call literals because their occurrence in code results in
 207 > them being pushed onto the stack. But I also call [London Paris] a list.
 208 > So, [dup *] is a quotation but not a list.
 209
 210 From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350)
 211
 212
 213 -------------------------------
 214
 215 From here it kinda falls apart...
 216
 217 ### Literals and Simple Functions
 218
 219 TODO
 220
 221
 222 ### Combinators
 223
 224 The main loop is very simple as most of the action happens through what
 225 are called __combinators__. These are functions which accept quoted programs on the
 226 stack and run them in various ways.  These combinators reify specific
 227 control-flow patterns (such as `ifte` which is like `if.. then.. else..` in other
 228 languages.)  Combinators receive the current
 229 expession in addition to the stack and return the next expression.  They
 230 work by changing the pending expression the interpreter is about to
 231 execute.  (The combinators could work by making recursive calls to the
 232 interpreter and all intermediate state would be held in the call stack of
 233 the implementation language, in this joy implementation they work instead
 234 by changing the pending expression and intermediate state is put there.)
 235
 236     joy? 23 [0 >] [dup --] while
 237     23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
 238
 239
 240
 241 --------------------------------------------------
 242
 243 Copyright © 2014 - 2023 Simon Forman
 244
 245 This file is part of Thun
 246
 247 Thun is free software: you can redistribute it and/or modify it under the
 248 terms of the GNU General Public License as published by the Free Software
 249 Foundation, either version 3 of the License, or (at your option) any
 250 later version.
 251
 252 Thun is distributed in the hope that it will be useful, but WITHOUT ANY
 253 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 254 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 255 details.
 256
 257 You should have received a copy of the GNU General Public License along
 258 with Thun.  If not see <http://www.gnu.org/licenses/>.
 259