Thun.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.
  14
  15
  16 ## Grammar
  17
  18 The grammar of Joy is very simple.  A Joy expression is zero or more Joy
  19 terms separated by blanks. Terms can be integers in decimal notation,
  20 Booleans `true` and `false`, lists enclosed by square brackets `[` and `]`,
  21 or symbols (names of functions.)
  22
  23     joy ::= term*
  24
  25     term ::= integer | bool | '[' joy ']' | symbol
  26
  27     integer ::= [ '-' ] ('0'...'9')+
  28
  29     bool ::= 'true' | 'false'
  30
  31     symbol ::= char+
  32
  33     char ::= <Any non-space other than '[' and ']'.>
  34
  35 Symbols can be composed of any characters except blanks and square
  36 brackets.  Integers can be prefixed with a minus sign to denote negative
  37 numbers.  The symbols `true` and `false` are reserved to denote their
  38 respective Boolean values.
  39
  40 That's it.  That's the whole of the grammar.
  41
  42
  43 ## Types
  44
  45 The original Joy has several datatypes (such as strings and sets)
  46 but the Thun dialect currently only uses four:
  47
  48 * Integers, signed and unbounded by machine word length (they are
  49   [bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).)
  50 * Boolean values ``true`` and ``false``.
  51 * Lists quoted in `[` and `]` brackets.
  52 * Symbols (names).
  53
  54
  55 ## Stack, Expression, Dictionary
  56
  57 Joy is built around three things: a __stack__ of data items, an
  58 __expression__ representing a program to evaluate, and a __dictionary__
  59 of named functions.
  60
  61 ### Stack
  62
  63 Joy is
  64 [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language).
  65 There is a single main __stack__ that holds data items, which can be
  66 integers, bools, symbols (names), or sequences of data items enclosed in
  67 square brackets (`[` or `]`).
  68
  69 We use the terms "stack", "quote", "sequence", "list", and others to mean
  70 the same thing: a simple linear datatype that permits certain operations
  71 such as iterating and pushing and popping values from (at least) one end.
  72
  73 > In describing Joy I have used the term quotation to describe all of the
  74 > above, because I needed a word to describe the arguments to combinators
  75 > which fulfill the same role in Joy as lambda abstractions (with
  76 > variables) fulfill in the more familiar functional languages. I use the
  77 > term list for those quotations whose members are what I call literals:
  78 > numbers, characters, truth values, sets, strings and other quotations.
  79 > All these I call literals because their occurrence in code results in
  80 > them being pushed onto the stack. But I also call [London Paris] a
  81 > list. So, [dup \*] is a quotation but not a list.
  82
  83 From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350)
  84
  85 ### Expression
  86
  87 A Joy __expression__ is just a sequence or list of items.  Sequences
  88 intended as programs are called "quoted programs".  Evaluation proceeds
  89 by iterating through the terms in an expression putting all literals
  90 (integers, bools, or lists) onto the main stack and executing functions
  91 named by symbols as they are encountered.  Functions receive the current
  92 stack, expression, and dictionary and return the next stack, expression,
  93 and dictionary.
  94
  95 ### Dictionary
  96
  97 The __dictionary__ associates symbols (names) with Joy expressions that
  98 define the available functions of the Joy system.  Together the stack,
  99 expression, and dictionary are the entire state of the Joy interpreter.
 100
 101
 102 ## Interpreter
 103
 104 The Joy interpreter is extrememly simple. It accepts a stack, an
 105 expression, and a dictionary, and it iterates through the expression
 106 putting values onto the stack and delegating execution to functions which
 107 it looks up in the dictionary.
 108
 109 ![Joy Interpreter Flowchart](https://git.sr.ht/~sforman/Thun/blob/trunk/joy_interpreter_flowchart.svg)
 110
 111 All control flow works by
 112 [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style).
 113 __Combinators__ (see below) alter control flow by prepending quoted programs to the pending
 114 expression (aka "continuation".)
 115
 116
 117 ## Literals, Functions, Combinators
 118
 119
 120 ### Literals
 121
 122 Literal values (integers, Booleans, lists) are put onto the stack.
 123
 124 ### Functions
 125
 126 Functions take values from the stack and push results onto it.
 127
 128 ### Combinators
 129
 130 __Combinators__ are functions which accept quoted programs on the stack
 131 and run them in various ways.  These combinators reify specific
 132 control-flow patterns (such as `ifte` which is like `if.. then.. else..`
 133 in other languages.)  Combinators receive the current expession in
 134 addition to the stack and return the next expression.  They work by
 135 changing the pending expression the interpreter is about to execute.
 136
 137 ### Basis Functions
 138
 139 Thun has a set of *basis* functions which are implemented in the host
 140 language.  The rest of functions in the Thun dialect are defined in terms
 141 of these:
 142
 143 - Combinators: `branch` `dip` `i` `loop`
 144 - Stack Chatter: `clear` `dup` `pop` `stack` `swaack` `swap`
 145 - List Manipulation: `concat` `cons` `first` `rest`
 146 - Math: `+` `-` `*` `/` `%`
 147 - Comparison: `<` `>` `>=` `<=` `!=` `<>` `=`
 148 - Logic: `truthy` `not`
 149 - Programming: `inscribe`
 150
 151 ### Definitions
 152
 153 Thun can be extended by adding new definitions to the `defs.txt` file and
 154 rebuilding the binaries.  Each line in the file is a definition
 155 consisting of the new symbol name followed by an expression for the body
 156 of the function.
 157
 158 You can use the `inscribe` command to put new definitions into the
 159 dictionary at runtime, but they will not persist after the program ends.
 160 The `inscribe` function is the only function that changes the dictionary.
 161 It's meant for prototyping.  (You could abuse it to make variables by
 162 storing "functions" in the dictionary that just contain literal values as
 163 their bodies.)
 164
 165 ## Problems
 166
 167 ### Symbols as Data
 168
 169 Nothing prevents you from using symbols as data:
 170
 171     joy? [cats]
 172     [cats]
 173
 174 But there's a potential pitfall: you might accidentally get a "bare"
 175 unquoted symbol on the stack:
 176
 177     joy? [cats]
 178     [cats]
 179     joy? first
 180     cats
 181
 182 That by itself won't break anything (the stack is just a list.)
 183 But if you were to use, say, `dip`, in such a way as to put the symbol
 184 back onto the expression, then when the interpreter encounters it, it
 185 will attempt to evaluate it, which is almost certainly not what you want.
 186
 187     cats
 188     joy? [23] dip
 189     Unknown: cats
 190     cats
 191
 192 At the very least you get an "Unknown" error, but if the symbol names a
 193 function then the interpreter will attempt to evaluate it, probably
 194 leading to an error.
 195
 196 I don't see an easy way around this.  Be careful?  It's kind of against
 197 the spirit of the thing to just leave a footgun like that laying around,
 198 but perhaps in practice it won't come up.  (Because writing Joy code by
 199 derivation seems to lead to bug-free code, which is the kinda the point.)
 200
 201
 202 --------------------------------------------------
 203
 204 Copyright © 2014 - 2023 Simon Forman
 205
 206 This file is part of Thun
 207