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. --- docs/doc/assert.html | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/doc/assert.html') diff --git a/docs/doc/assert.html b/docs/doc/assert.html index ceccf72a..d800155f 100644 --- a/docs/doc/assert.html +++ b/docs/doc/assert.html @@ -8,28 +8,35 @@

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.

-↗️
    ! 2=2  # Passed
+↗️
    ! 2=2  # Passed
 1
+
     ! 2=3  # Failed
 Error: Assertion error
 

 
To pass, the right argument must be exactly the number 1; any other value causes an error. For example, an array of 1s 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
 Error: 2‿2⥊1‿1‿1‿1
+
     ! ∧´⥊ (∧=∨⌾¬)⌜˜ ↕2
 1
 

-
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.

-↗️
    "Message" ! 0
+
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
 Error: Message
+
     ⟨∘,"abc",˜⟩ ! '0'
 Error: ⟨∘,"abc",˜⟩
 

+
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"
+Error: 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 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). 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), 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