tweaks

language.md

@@ -1,6 +1,6 @@
 # Ludus language reference
 
-This is not intended for beginners, but to be a language overview for experienced users. That said, it may help beginners orient themselves in the language.
+This is not intended for beginners, but to be a language overview for experienced programmers. That said, it may help beginners orient themselves in the language.
 
 ## Comments
 Ludus's comment character is `&`. Anything after an ampersand on a line is ignored. There are no multiline comments.
@@ -9,7 +9,7 @@ Ludus's comment character is `&`. Anything after an ampersand on a line is ignor
 Ludus has four types of atomic values.
 
 ### `nil`
-`nil` is Ludus's representation of nothing. In the grand Lisp tradition, Ludus can, and frequently does, use `nil`-punning. Its type is `:nil`.
+`nil` is Ludus's representation of nothing. In the grand Lisp tradition, Ludus can, and occasionally does, use `nil`-punning. Its type is `:nil`.
 
 ### Booleans
 `true` and `false`. That said, in all conditional constructs, `nil` and `false` are "falsy," and everything else is "truthy." Their type is `:boolean`.
@@ -50,11 +50,14 @@ let baz = [1, 2, 3]
 Interpolations may _not_ be arbitrary expressions: only bound names may be used in interpolations.
 
 ## Collections
-Ludus has a few different types of collections, in increasing order of complexity: tuples, lists, sets, dicts, and namespaces.
+Ludus has a few different types of collections, in increasing order of complexity: tuples, lists, sets, dicts, and packages. All collections are immutable.
 
-### Separators
+#### Separators
 In all collection literals, members are written with a separator between them. On the same line, use a comma; or a newline will also separate elements. You may use as many separators as you wish at any point inside a collection or pattern. `(,,,,,,,3,,4,,,,,,)` and `(3, 4)` are the same value.
 
+#### Efficiency
+At the current moment, Ludus collections are all copy-on-write; this means that Ludus is _not_ performant with large collections. Eventually, Ludus will have Clojure-style persistent, immutable collections.
+
 ### Tuples
 Tuples are fully-immutable, ordered collections of any kinds of values, delimited by parentheses, e.g. `(1, :a, "foo")`. At current, they have no length limit (although they eventually will). Unlike in some languages, tuples can be empty or contain a single element: `()` and `(:foo)` are both just fine. Tuples largely cannot be manipulated functionally; they must be written as literals and unpacked using pattern matching. They can, however, be converted to lists, either through pattern matching or the `list` function. Their type is `:tuple`.
 
@@ -70,7 +73,7 @@ Sets are persistent and immutable unordered collections of any kinds of values,
 Dicts are persistent and immutable associative collections of any kinds of values. Dicts use keywords as keys (and cannot use any other kind of Ludus value as a key, not even strings), but can store any values. Dict literals are written as keyword-value pairs: `#{:a 1, :b false}`. Single words may be used as a shorthand for a key-value pair. Accessing a key that holds no value returns `nil`. Their type is `:dict`.
 
 ### Packages
-Packages are immutable collections of bindings. They may only be described at the top level of a script, and their names must begin with a capital letter. Accessing a key that has no value on a package results in a panic. They may not be accessed using functions, only direct keyword access. Their type is `:pkg`.
+Packages are immutable collections of bindings. They may only be described at the top level of a script, and their names must begin with a capital letter. Accessing a key that has no value on a package results in a validation error. They may not be accessed using functions, but only direct keyword access. Their type is `:pkg`.
 
 They are written with the form `pkg`, then a package name, beginning with a capital letter, that will be bound as their name, and then an associative structure (pairs or word shorthands), delimited by `{}`, e.g.:
 
@@ -83,7 +86,7 @@ pkg Foo {
 ```
 
 ### Working with collections
-Ludus names are bound permanently and immutably. How do you add something to a list or a dict? How do you get things out of them?
+Ludus names are bound permanently and immutably. Collections are immutable. How do you add something to a list or a dict? How do you get things out of them?
 
 Ludus provides functions that allow working with persistent collections. They're detailed in [the Prelude](/prelude.md). That said, all functions that modify collections take a collection and produce the modified collection _as a return value_, without changing the original collection. E.g., `append ([1, 2, 3], 4)` will produce `[1, 2, 3, 4]`, but the original list is unchanged. (For dicts, the equivalent is `assoc`.)
 
@@ -102,7 +105,7 @@ Many compound forms will only accept "simple" expressions. Formally, simple expr
 ## Words and bindings
 Ludus uses _words_ to bind values to names. Words must start with a lower case ASCII letter, and can subsequently include any letter character (modulo backing character encoding), as well as , `_`, `/`, `?`, `!`, and `*`.
 
-Ludus binds values to names immutably and permanently: no name in the same scope may ever be re-bound to a different value. (Although see [refs](#references-and-state), below.
+Ludus binds values to names immutably and permanently: no name in the same scope may ever be re-bound to a different value. (Although see [boxes](#boxes-and-state), below.
 
 Attempting to use an unbound name (a word that has not had a value bound to it) will result in a validation error, and the script will not run.
 
@@ -258,6 +261,17 @@ If a test expression does not match against any clause's pattern, a panic is rai
 
 Ludus does not attempt to do any exhaustiveness checking on match forms; match errors are always runtime errors.
 
+#### Guards
+`match` clauses may have a _guard expression_, which allows a clause only to match if the expression's result is truthy. In the previous example, consider that we might want different behaviour depending on the value of the number:
+```
+match may_fail () with {
+  (:ok, value) if pos? (value) -> calculate_positive_result (value)
+  (:ok, value) if neg? (value) -> calculate_negative_result (value)
+  (:ok, 0) -> do_something_with_zero ()
+  (:err, msg) -> { log! (msg); recover_somehow () }
+}
+```
+
 ## Functions
 Ludus is an emphatically functional language. Almost everything in Ludus is accomplished by applying functions to values, or calling functions with arguments. (These are precise synonyms.)
 
@@ -278,7 +292,7 @@ A named function is identical to a lambda, with the one change that a word follo
 #### Compound functions
 Compound functions are functions that have multiple clauses. They must be named, and in place of a single clause after a name, they consist in one or more clauses, separated by semicolons or newlines, delimited by curly braces. Optionally, compound functions may have a docstring as their first element after the opening curly brace. The docstring explains the function's purpose and use, before any of the function clauses.
 
-An exampele from Ludus's Prelude:
+An example from Ludus's Prelude:
 
 ```
 fn some {
@@ -289,7 +303,7 @@ fn some {
 ```
 
 ### Closures
-Functions in Ludus are closures: function bodies have access not only to their specific scope, but any enclosing scope. Note that function bodies may have access to names bound after them in their scope, so long as the function is _called_ after any names it accesses are bound.
+Functions in Ludus are closures: function bodies have access not only to their specific scope, but any enclosing scope. That said, functions only have access to names bound _before_ they are defined; nothing is hoisted in Ludus.
 
 ### Mutual recursion and forward declaration
 If you try the following, you'll get a validation error:
@@ -297,7 +311,7 @@ If you try the following, you'll get a validation error:
 ```
 fn stupid_odd? {
   (0) -> false
-  (x) -> supid_even? (dec (x)) & Validation error: unbound name
+  (x) -> supid_even? (dec (x)) & Validation error: unbound name stupid_even?
 }
 
 fn stupid_even? {
@@ -306,7 +320,9 @@ fn stupid_even? {
 }
 ```
 
-To allow for mutual recursion, Ludus allows forward declarations, which are written `fn name` without any clauses. In the example above, we would simply put `fn stupid_even?` before we define `stupid_odd?`. If you declare a function without defining it, however, Ludus will raise a validation error.
+To allow for mutual recursion, Ludus allows forward declarations, which are written `fn name` without any clauses. In the example above, we would simply put `fn stupid_even?` before we define `stupid_odd?`. 
+
+If you declare a function without defining it, however, Ludus will raise a validation error.
 
 ### The Prelude
 The Prelude is a substantial set of functions that is available in any given Ludus script. (It is, itself, just a Ludus file that has special access to host functions.) Because of that, a large number of functions are always available. The prelude documentation is [here](/prelude.md).
@@ -405,7 +421,7 @@ Status: not yet implemented.
 ### `use`
 `use` loads the contents of a namespace into a script's context. To ensure that this is statically checkable, this must be at the toplevel. 
 
-Status: not yet implemented
+Status: not yet implemented.
 
 ### `pkg`
 Packages, `pkg`es, may only be described at the toplevel of a script. This is to ensure they can be statically evaluatable.
@@ -430,7 +446,7 @@ Formally: `test <string> <expression>`.
 Status: not yet implemented.
 
 ## Changing things: `box`es
-Ludus does not let you re-bind names. It does, however, have a type that allows for changing values over time: `box`. A box is a place to put things, it has its own identity, it can store whatever you put in it. 
+Ludus does not let you re-bind names. It does, however, have a type that allows for changing values over time: `box`. A box is a place to put things, it has its own identity, it can store whatever you put in it, but to get what's in it, you have to `unbox` it. 
 
 Syntactically and semantically, `box`es are straightforward, but do require a bit more overhead than `let` bindings. The idea is that Ludus makes it obvious where mutable state is in a program, as well as where that mutable state may change. It does so elegantly, but with some guardrails that may take a little getting used to.
 
@@ -476,7 +492,7 @@ Panics also happen in the following cases:
 In fact, the only functions in the Prelude which explicitly cause panics are, at current, `div`, `inv`, `mod`, `sqrt`, `unwrap!`, and `assert!`.
 
 ### `nil`s, not errors
-Ludus, however, tries to return `nil` instead of panicking a lot of the time. So, for example, attempting to get access a value at a keyword off a number, while nonsensical, will return `nil` rather than panicking:
+Ludus, however, tries to return `nil` instead of panicking where it seems prudent. So, for example, attempting to get access a value at a keyword off a number or `nil`, while nonsensical, will return `nil` rather than panicking:
 
 ```
 let a = true