Add document on Assert

3 files changed, 27 insertions, 1 deletions

diff --git a/doc/README.md b/doc/README.md
index 3a766abf..01e5bcb5 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -21,6 +21,7 @@ Concepts:
 
 Primitives:
 - [Array depth](depth.md) (`≡` and `⚇`)
+- [Assert](assert.md) (`!`)
 - [Deshape and Reshape](reshape.md) (`⥊`)
 - [Group](group.md) (`⊔`)
 - [Join and Join To](join.md) (`∾`)
diff --git a/doc/assert.md b/doc/assert.md
new file mode 100644
index 00000000..7f4bee6d
--- /dev/null
+++ b/doc/assert.md
@@ -0,0 +1,25 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/assert.html).*
+
+# 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=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.
+
+        "Message" ! 0
+        ⟨∘,"abc",˜⟩ ! '0'  # Okay this is not a very helpful printout
+
+### 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 `!`.
+- 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.
diff --git a/doc/primitive.md b/doc/primitive.md
index dfc03f01..9546ae9f 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -52,7 +52,7 @@ Functions that have significant differences from APL functions are marked with a
 | `∊`   | [Unique Mask](https://aplwiki.com/wiki/Nub_Sieve)   | [Member of](https://aplwiki.com/wiki/Membership)
 | `⍷`   | [Deduplicate](https://aplwiki.com/wiki/Unique)      | [Find](https://aplwiki.com/wiki/Find)
 | `⊔`   | [Group Indices](group.md)*                          | [Group](group.md)*
-| `!`   | Assert*                                             | Assert with Message*
+| `!`   | [Assert](assert.md)*                                | [Assert with Message](assert.md)*
 
 ## Modifiers