better readme

README.md

@@ -1,8 +1,10 @@
-**Matzo** is my first attempt at a language designed for creating random text fragments, now reimplemented in Rust.
+**Matzo** was my first attempt at a language designed for creating random text fragments, now reimplemented in Rust.
 
 (The earlier versions were Haskell and JavaScript, and both have bit-rotted rather badly: I'm hoping that this version is both cleaner—on account of my writing it a decade later—and also that this version is easier to modify and will be more resilient to bit-rot.)
 
-## Matzo basics
+## The Matzo language
+
+### Basic features
 
 There are two basic kinds of statements: assignment and printing. Assignment is usually done with `:=`. All statements are terminated with a semicolon (although the REPL will usually tolerate you leaving it off.)
 
@@ -74,11 +76,55 @@ fix letter;
 puts letter letter; (* aa or bb *)
 ```
 
-## Fancier Matzo
+### Data types
+
+Matzo offers a handful of other data types in addition to strings. Matzo is dynamically typed, and additionally all of these types coerce implicitly to strings when they're printed.
+
+- _Numbers_ are written as you'd expect. Matzo only offers integer numbers: there are no floating point numbers in Matzo. Additionally, many of the usual integer operations are missing, or are only offered via named functions in the stdlib. There's also a special case for generating numbers from a range: a range literal like `2..4` represents not an actual range but a choice from inside an inclusive range: that means that an expression like `2..4` is equivalent to writing `2 | 3 | 4`.
+- _Atoms_ are simple named types, and are represented with capital letters. Atoms are used for things like boolean (e.g. `True` and `False`) but can be used for any kind of tag. It's common to use fixed atoms for certain kinds of categories and then later on branch on them to come up with specific strings: for example, defining a kind of pet as `fixed pet := Cat | Dog | Rabbit;` and then later on casing on `pet` to build parts of a description.
+- _Tuples_ are sequences of values, and are written within angle brackets, e.g. `<2, Foo>` is a 2-tuple containing the number `2` and the atom `Foo`. Tuples are especially useful with functions and pattern-matching.
+
+### Functions
+
+Applying functions is done using an explicit operator: the `.` operator. That is to say, to apply the `to-upper` function to the string `"foo"`, you'd write `to-upper."foo"`.
+
+Functions can only be applied to one value at a time. This means that functions can sometimes take tuples of arguments (e.g. `rep.<3, "na">`) but functions can also be curried. Most stdlib functions take the tuple approach.
+
+All functions are defined as anonymous functions and can optionally feature definition-by-cases. A simple function which just returns its argument looks like this:
+
+```
+id := { x => x };
+```
+
+In order to define a function by cases, you can separate individual cases with `;`.
 
-- Data types (atoms, tuples)
-- Functions
-- Pattern-matching
+```
+if := { <True,  x, _> => x
+      ; <False, _, y> => y
+      };
+```
+
+You can also return other functions, which retain access to their environment, which means the above function be expressed isomorphically as:
+
+```
+if := { True  => { x => { _ => x }}
+      ; False => { _ => { y => y }}
+      };
+```
+
+While these two express the same functionality, the former would be called with `if.<condition, thenCase, elseCase>` while the latter would be called with `if.condition.then-case.else-case`.
+
+### A sample program
+
+The intention of Matzo is to be used for generating text, and was originally created for the task of creating fake words for constructed languages. Here is an example program which creates words in a simple language:
+
+```
+consonant ::= p t k w h n;
+vowel ::= a e i o u;
+nucleus := 4: vowel | vowel "'";
+syll := 4: consonant nucleus | nucleus;
+puts syll rep.<1..5, syll>;
+```
 
 ## Implementation notes