Document Catch (⎊)

3 files changed, 30 insertions, 11 deletions

diff --git a/doc/README.md b/doc/README.md
index 2b88a479..891947ba 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -37,7 +37,7 @@ Primitives:
 - [Arithmetic](arithmetic.md) (`+-×÷⋆√⌊⌈|≤<>≥=≠`)
 - [Array depth](depth.md) (`≡` and `⚇`)
 - [Array dimensions](shape.md) (`≢=≠`)
-- [Assert](assert.md) (`!`)
+- [Assert and Catch](assert.md) (`!` and `⎊`)
 - [Deshape and Reshape](reshape.md) (`⥊`)
 - [Enclose](enclose.md) (`<`)
 - [Find](find.md) (`⍷`)
diff --git a/doc/assert.md b/doc/assert.md
index 121d8a1e..f193be21 100644
--- a/doc/assert.md
+++ b/doc/assert.md
@@ -1,6 +1,10 @@
 *View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/assert.html).*
 
-# Assert
+# Assert and Catch
+
+BQN provides some simple facilities for dealing with errors. Errors are an unusual sort of control flow; if possible, prefer to work with functions that return normally.
+
+## Assert
 
 BQN takes the position that errors exist to indicate exceptional conditions that the developer of a given program didn't expect. However, the types of errors that BQN naturally checks for, such as mismatched shapes in Couple (`≍`), aren't always enough to detect exceptional conditions. Issues like numeric values that don't make physical sense will slip right through. BQN makes it easy for a programmer to check for these sorts of problems by building in the primitive Assert, written `!`. This function checks whether `𝕩` matches `1`: if it does, then it does nothing and returns `𝕩`, and otherwise it gives an error.
 
@@ -23,3 +27,17 @@ Because the left argument to a function is always computed before the function i
 - Handle errors with ordinary if-then logic (perhaps using [control structures](control.md)). This is probably the best path for user-facing applications where displaying an error goes through the user interface.
 - Write a function `Message` to compute the message, and call `𝕨 Message⊸!⍟(1⊸≢) 𝕩` or similar instead of `!`.
 - If the error will be caught elsewhere in the program, use a closure for the message and evaluate it when caught. With a function `Message` as above, `message ! 𝕩` works, and `{…}˙⊸! 𝕩` is a convenient syntax for block functions.
+
+## Catch
+
+The `Catch` modifier allows you to handle errors in BQN (at present, it's the only way to do so). It evaluates the function `𝔽` normally. If this function completes without an error, Catch just returns that result. If not, it stops the error, and calls `𝔾` with the original arguments instead.
+
+        ⌽⎊'x' "abcd"  # No error
+
+        ⌽⎊'x' 2       # Can't reverse a unit
+
+        0.5 ⌽⎊⊣ ↕6    # A two-argument example
+
+Catch doesn't know anything about what an error *is*, just whether there was one or not. In fact, the idea of error message doesn't feature at all in core BQN: it's purely part of the language environment. So you need a system value to access information about the error. Right now the only one is `•CurrentError`, which is a function that returns a message for the error currently caught (if any).
+
+        ⌽⎊•CurrentError 2
diff --git a/doc/primitive.md b/doc/primitive.md
index 2d5a3b6b..d81188c2 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -81,12 +81,13 @@ Choose isn't really a combinator since it calls the function `⊑`, and Under is
 
 Other modifiers control array traversal and iteration. In three cases a simpler 1-modifier is paired with a generalized 2-modifier: in each case the 1-modifier happens to be the same as the 2-modifier with a right operand of `¯1`.
 
-1-Modifier | Name                                  | 2-Modifier | Name
------------|---------------------------------------|------------|--------
-`˘`        | Cells                                 | `⎉`        | [Rank](https://aplwiki.com/wiki/Rank_(operator))
-`¨`        | [Each](map.md)                        | `⚇`        | [Depth](depth.md#the-depth-modifier)
-`⌜`        | [Table](map.md)                       |
-`⁼`        | [Undo](undo.md)                       | `⍟`        | [Repeat](repeat.md)
-`´`        | [Fold](fold.md)                       |
-`˝`        | [Insert](fold.md)                     |
-`` ` ``    | [Scan](scan.md)                       |
+| 1-Modifier | Name                                  | 2-Modifier | Name
+|------------|---------------------------------------|------------|--------
+| `˘`        | Cells                                 | `⎉`        | [Rank](https://aplwiki.com/wiki/Rank_(operator))
+| `¨`        | [Each](map.md)                        | `⚇`        | [Depth](depth.md#the-depth-modifier)
+| `⌜`        | [Table](map.md)                       |
+| `⁼`        | [Undo](undo.md)                       | `⍟`        | [Repeat](repeat.md)
+| `´`        | [Fold](fold.md)                       |
+| `˝`        | [Insert](fold.md)                     |
+| `` ` ``    | [Scan](scan.md)                       |
+|            |                                       | `⎊`        | [Catch](assert.md#catch)