From b6185d5029e2adcc721c0cc2097f591d9a09f135 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sun, 26 Jun 2022 21:00:25 -0400 Subject: I am in editing stepped in so far that, should I wade no more, returning were as tedious as go o'er. --- doc/assert.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'doc/assert.md') diff --git a/doc/assert.md b/doc/assert.md index 14e4cf72..83d8570c 100644 --- a/doc/assert.md +++ b/doc/assert.md @@ -9,23 +9,30 @@ BQN provides some simple facilities for dealing with errors. Errors are an unusu 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. ! 2=2 # Passed + ! 2=3 # Failed To pass, the right argument must be exactly the number `1`; any other value causes an error. For example, an array of `1`s still causes an error; use `∧´⥊` to convert a boolean array to a single boolean that indicates whether all of its values are true. ! (∧=∨⌾¬)⌜˜ ↕2 + ! ∧´⥊ (∧=∨⌾¬)⌜˜ ↕2 -Assert can take a left argument, which gives a message to be associated with the error. It's typical to use a string for the left argument in order to display it to the programmer, but the left argument can be any value. +Assert can take a left argument, which gives a message to be associated with the error. It's typical to use a string for `𝕨` in order to display it to the programmer, but `𝕨` can be any value. "Message" ! 0 + ⟨∘,"abc",˜⟩ ! '0' +In the 1-argument case, `𝕩` is used for the error message if it's not `1`. So an unconditional error can also be written this way: + + ! "Message" + ### Computing the error message on demand Because the left argument to a function is always computed before the function is called, Assert [doesn't let you](../commentary/problems.md#assert-has-no-way-to-compute-the-error-message) compute the error message only if there's an error. This might be a problem if the error message computation is slow or has side effects. There are a few ways to work around the issue: -- 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 `!`. +- Handle bad inputs with ordinary if-then logic (perhaps using [control structures](control.md)), not errors. This is probably the best path for user-facing applications where BQN's normal error display isn't wanted. +- 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 -- cgit v1.2.3