From 168a106af8b2771d20a2662c1d13c16fa976a68d Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Tue, 2 Feb 2021 16:24:24 -0500 Subject: Add document on Assert --- docs/doc/assert.html | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/doc/assert.html (limited to 'docs/doc/assert.html') diff --git a/docs/doc/assert.html b/docs/doc/assert.html new file mode 100644 index 00000000..35ae159c --- /dev/null +++ b/docs/doc/assert.html @@ -0,0 +1,32 @@ + + + + BQN: Assert + +
BQN / main / doc
+

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
+1
+    ! 2=3  # Failed
+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
+ERROR
+    ! ∧´⥊ (∧=∨⌾¬)⌜˜ ↕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
+ERROR
+    ⟨∘,"abc",˜⟩ ! '0'  # Okay this is not a very helpful printout
+ERROR
+
+

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:

+ -- cgit v1.2.3