Document Catch (⎊)

10 files changed, 62 insertions, 18 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)
diff --git a/docs/doc/assert.html b/docs/doc/assert.html
index 948f8cf7..83d4b46c 100644
--- a/docs/doc/assert.html
+++ b/docs/doc/assert.html
@@ -1,10 +1,12 @@
 <head>
   <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
   <link href="../style.css" rel="stylesheet"/>
-  <title>BQN: Assert</title>
+  <title>BQN: Assert and Catch</title>
 </head>
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div>
-<h1 id="assert"><a class="header" href="#assert">Assert</a></h1>
+<h1 id="assert-and-catch"><a class="header" href="#assert-and-catch">Assert and Catch</a></h1>
+<p>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.</p>
+<h2 id="assert"><a class="header" href="#assert">Assert</a></h2>
 <p>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 (<code><span class='Function'>≍</span></code>), 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 <code><span class='Function'>!</span></code>. This function checks whether <code><span class='Value'>𝕩</span></code> matches <code><span class='Number'>1</span></code>: if it does, then it does nothing and returns <code><span class='Value'>𝕩</span></code>, and otherwise it gives an error.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ISAyPTIgICMgUGFzc2VkCiEgMj0zICAjIEZhaWxlZA==">↗️</a><pre>    <span class='Function'>!</span> <span class='Number'>2</span><span class='Function'>=</span><span class='Number'>2</span>  <span class='Comment'># Passed
 </span>1
@@ -30,3 +32,18 @@
 <li>Write a function <code><span class='Function'>Message</span></code> to compute the message, and call <code><span class='Value'>𝕨</span> <span class='Function'>Message</span><span class='Modifier2'>⊸</span><span class='Function'>!</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>≢</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code> or similar instead of <code><span class='Function'>!</span></code>.</li>
 <li>If the error will be caught elsewhere in the program, use a closure for the message and evaluate it when caught. With a function <code><span class='Function'>Message</span></code> as above, <code><span class='Value'>message</span> <span class='Function'>!</span> <span class='Value'>𝕩</span></code> works, and <code><span class='Brace'>{</span><span class='Value'>…</span><span class='Brace'>}</span><span class='Modifier'>˙</span><span class='Modifier2'>⊸</span><span class='Function'>!</span> <span class='Value'>𝕩</span></code> is a convenient syntax for block functions.</li>
 </ul>
+<h2 id="catch"><a class="header" href="#catch">Catch</a></h2>
+<p>The <code><span class='Function'>Catch</span></code> modifier allows you to handle errors in BQN (at present, it's the only way to do so). It evaluates the function <code><span class='Function'>𝔽</span></code> normally. If this function completes without an error, Catch just returns that result. If not, it stops the error, and calls <code><span class='Function'>𝔾</span></code> with the original arguments instead.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy94o6KJ3gnICJhYmNkIiAgIyBObyBlcnJvcgoK4oy94o6KJ3gnIDIgICAgICAgIyBDYW4ndCByZXZlcnNlIGEgdW5pdAoKMC41IOKMveKOiuKKoyDihpU2ICAgICMgQSB0d28tYXJndW1lbnQgZXhhbXBsZQ==">↗️</a><pre>    <span class='Function'>⌽</span><span class='Modifier2'>⎊</span><span class='String'>'x'</span> <span class='String'>&quot;abcd&quot;</span>  <span class='Comment'># No error
+</span>"dcba"
+
+    <span class='Function'>⌽</span><span class='Modifier2'>⎊</span><span class='String'>'x'</span> <span class='Number'>2</span>       <span class='Comment'># Can't reverse a unit
+</span>'x'
+
+    <span class='Number'>0.5</span> <span class='Function'>⌽</span><span class='Modifier2'>⎊</span><span class='Function'>⊣</span> <span class='Function'>↕</span><span class='Number'>6</span>    <span class='Comment'># A two-argument example
+</span>0.5
+</pre>
+<p>Catch doesn't know anything about what an error <em>is</em>, 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 <code><span class='Function'>•CurrentError</span></code>, which is a function that returns a message for the error currently caught (if any).</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy94o6K4oCiQ3VycmVudEVycm9yIDI=">↗️</a><pre>    <span class='Function'>⌽</span><span class='Modifier2'>⎊</span><span class='Function'>•CurrentError</span> <span class='Number'>2</span>
+"⌽: Argument cannot be a unit"
+</pre>
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 2935fc92..98587366 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -43,7 +43,7 @@
 <li><a href="arithmetic.html">Arithmetic</a> (<code><span class='Function'>+-×÷⋆√⌊⌈|≤&lt;&gt;≥=≠</span></code>)</li>
 <li><a href="depth.html">Array depth</a> (<code><span class='Function'>≡</span></code> and <code><span class='Modifier2'>⚇</span></code>)</li>
 <li><a href="shape.html">Array dimensions</a> (<code><span class='Function'>≢=≠</span></code>)</li>
-<li><a href="assert.html">Assert</a> (<code><span class='Function'>!</span></code>)</li>
+<li><a href="assert.html">Assert and Catch</a> (<code><span class='Function'>!</span></code> and <code><span class='Modifier2'>⎊</span></code>)</li>
 <li><a href="reshape.html">Deshape and Reshape</a> (<code><span class='Function'>⥊</span></code>)</li>
 <li><a href="enclose.html">Enclose</a> (<code><span class='Function'>&lt;</span></code>)</li>
 <li><a href="find.html">Find</a> (<code><span class='Function'>⍷</span></code>)</li>
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index 2f39dda5..4def02cf 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -533,5 +533,11 @@
 <td></td>
 <td></td>
 </tr>
+<tr>
+<td></td>
+<td></td>
+<td><code><span class='Modifier2'>⎊</span></code></td>
+<td><a href="assert.html#catch">Catch</a></td>
+</tr>
 </tbody>
 </table>
diff --git a/docs/help/assert_assertwithmessage.html b/docs/help/assert_assertwithmessage.html
index 36c638a2..6ff535a7 100644
--- a/docs/help/assert_assertwithmessage.html
+++ b/docs/help/assert_assertwithmessage.html
@@ -6,7 +6,7 @@
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">help</a></div>
 <h1 id="exclamation-mark-"><a class="header" href="#exclamation-mark-">Exclamation Mark (<code><span class='Function'>!</span></code>)</a></h1>
 <h2 id="-𝕩-assert"><a class="header" href="#-𝕩-assert"><code><span class='Function'>!</span> <span class='Value'>𝕩</span></code>: Assert</a></h2>
-<p><a class="fulldoc" href="../doc/assert.html">→full documentation</a></p>
+<p><a class="fulldoc" href="../doc/assert.html#assert">→full documentation</a></p>
 <p>Throw an error if <code><span class='Value'>𝕩</span></code> is not 1.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ISAxCgohIDIKCiEgImhlbGxvIg==">↗️</a><pre>    <span class='Function'>!</span> <span class='Number'>1</span>
 1
@@ -18,7 +18,7 @@
 <span class='Error'>Error: hello</span>
 </pre>
 <h2 id="𝕨--𝕩-assert-with-message"><a class="header" href="#𝕨--𝕩-assert-with-message"><code><span class='Value'>𝕨</span> <span class='Function'>!</span> <span class='Value'>𝕩</span></code>: Assert With Message</a></h2>
-<p><a class="fulldoc" href="../doc/assert.html">→full documentation</a></p>
+<p><a class="fulldoc" href="../doc/assert.html#assert">→full documentation</a></p>
 <p>Throw an error with message <code><span class='Value'>𝕨</span></code> if <code><span class='Value'>𝕩</span></code> is not 1.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImhpIiAhIDEKCiJ0d28iICEgMgoKImhlbGxvIGVycm9yIiAhICJoZWxsbyI=">↗️</a><pre>    <span class='String'>&quot;hi&quot;</span> <span class='Function'>!</span> <span class='Number'>1</span>
 1
diff --git a/docs/help/catch.html b/docs/help/catch.html
index e98292e1..77cfc3ea 100644
--- a/docs/help/catch.html
+++ b/docs/help/catch.html
@@ -6,6 +6,7 @@
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">help</a></div>
 <h1 id="circled-triangle-down-"><a class="header" href="#circled-triangle-down-">Circled Triangle Down (<code><span class='Modifier2'>⎊</span></code>)</a></h1>
 <h2 id="𝔽𝔾-𝕩-𝕨-𝔽𝔾-𝕩-catch"><a class="header" href="#𝔽𝔾-𝕩-𝕨-𝔽𝔾-𝕩-catch"><code><span class='Function'>𝔽</span><span class='Modifier2'>⎊</span><span class='Function'>𝔾</span> <span class='Value'>𝕩</span></code>, <code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier2'>⎊</span><span class='Function'>𝔾</span> <span class='Value'>𝕩</span></code>: Catch</a></h2>
+<p><a class="fulldoc" href="../doc/assert.html#catch">→full documentation</a></p>
 <p>Apply <code><span class='Function'>𝔽</span></code> to the arguments.</p>
 <p>If an error happens when <code><span class='Function'>𝔽</span></code> is applied, cancel its execution, apply <code><span class='Function'>𝔾</span></code> to the arguments and return its result.</p>
 <p>Otherwise, return the result of <code><span class='Function'>𝔽</span></code>.</p>
diff --git a/help/assert_assertwithmessage.md b/help/assert_assertwithmessage.md
index 37e7f4ba..496bd6c5 100644
--- a/help/assert_assertwithmessage.md
+++ b/help/assert_assertwithmessage.md
@@ -3,7 +3,7 @@
 # Exclamation Mark (`!`)
 
 ## `! 𝕩`: Assert
-[→full documentation](../doc/assert.md)
+[→full documentation](../doc/assert.md#assert)
 
 Throw an error if `𝕩` is not 1.
 
@@ -17,7 +17,7 @@ Throw an error if `𝕩` is not 1.
 
 
 ## `𝕨 ! 𝕩`: Assert With Message
-[→full documentation](../doc/assert.md)
+[→full documentation](../doc/assert.md#assert)
 
 Throw an error with message `𝕨` if `𝕩` is not 1.
 
diff --git a/help/catch.md b/help/catch.md
index a824a8bc..656eba06 100644
--- a/help/catch.md
+++ b/help/catch.md
@@ -3,6 +3,7 @@
 # Circled Triangle Down (`⎊`)
 
 ## `𝔽⎊𝔾 𝕩`, `𝕨 𝔽⎊𝔾 𝕩`: Catch
+[→full documentation](../doc/assert.md#catch)
 
 Apply `𝔽` to the arguments.