diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2022-01-29 20:53:23 -0500 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2022-01-29 20:53:29 -0500 |
| commit | ba1928402a83fe24ee667450257b66fe5cefcc00 (patch) | |
| tree | a4078111fdf15652a1d0d25d0e594bfb6e2aa920 /docs | |
| parent | 1a1f4a5a54494f91a91c6cc85558d5f1e62e5ca9 (diff) | |
Document Catch (β)
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/doc/assert.html | 21 | ||||
| -rw-r--r-- | docs/doc/index.html | 2 | ||||
| -rw-r--r-- | docs/doc/primitive.html | 6 | ||||
| -rw-r--r-- | docs/help/assert_assertwithmessage.html | 4 | ||||
| -rw-r--r-- | docs/help/catch.html | 1 |
5 files changed, 29 insertions, 5 deletions
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'>"abcd"</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'>+-ΓΓ·ββββ|β€<>β₯=β </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'><</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'>"hi"</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> |