A spec doc for Thun.

It's not very good yet, or formal, "but it's mine and I love it."

Thun.md

@@ -0,0 +1,171 @@
+# Thun
+
+A Dialect of Joy.
+
+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.
+
+
+## Grammar
+
+The grammar of Joy is very simple.  A Joy expression is zero or more Joy
+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.)
+
+    joy ::= term*
+    
+    term ::= integer | bool | '[' joy ']' | symbol
+    
+    integer ::= [ '-' ] ('0'...'9')+
+    
+    bool ::= 'true' | 'false'
+    
+    symbol ::= char+
+    
+    char ::= <Any non-space other than '[' and ']'.>
+
+Symbols can be composed of any characters except blanks and square
+brackets.  Integers can be prefixed with a minus sign to denote negative
+numbers.  The symbols `true` and `false` are reserved to denote their
+respective Boolean values.
+
+That's it.  That's the whole of the grammar.
+
+
+## Types
+
+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).
+
+
+## Stack, Expression, Dictionary
+
+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".)
+
+
+## Literals, Functions, Combinators
+
+
+### Literals
+
+Literal values (integers, Booleans, lists) are put onto the stack.
+
+### Functions
+
+Functions take values from the stack and push results onto it.
+
+### Combinators
+
+__Combinators__ 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.  
+
+### Basis Functions
+
+Thun has a set of *basis* functions which are implemented in the host
+language.  The rest of functions in the Thun dialect are defined in terms
+of these:
+
+- 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`
+
+### Definitions
+
+Thun can be extended by adding new definitions to the `defs.txt` file and
+rebuilding the binaries.  Each line in the file is a definition
+consisting of the new symbol name followed by an expression for the body
+of the function.
+
+You can use the `inscribe` command to put new definitions into the
+dictionary at runtime, but they will not persist after the program ends.
+The `inscribe` function is the only function that changes the dictionary.
+It's meant for prototyping.  (You could abuse it to make variables by
+storing "functions" in the dictionary that just contain literal values as
+their bodies.)
+
+
+--------------------------------------------------
+
+Copyright © 2014 - 2023 Simon Forman
+
+This file is part of Thun
+

misc.txt

@@ -53,3 +53,43 @@ or edit either or both of the stack and expression.  All state is in one
 or the other.
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### 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`        |                |                              |
+
+