From ba1928402a83fe24ee667450257b66fe5cefcc00 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sat, 29 Jan 2022 20:53:23 -0500 Subject: =?UTF-8?q?Document=20Catch=20(=E2=8E=8A)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/doc/assert.html | 21 +++++++++++++++++++-- docs/doc/index.html | 2 +- docs/doc/primitive.html | 6 ++++++ docs/help/assert_assertwithmessage.html | 4 ++-- docs/help/catch.html | 1 + 5 files changed, 29 insertions(+), 5 deletions(-) (limited to 'docs') 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 @@ - BQN: Assert + BQN: Assert and Catch
(github) / BQN / doc
-

Assert

+

Assert and Catch

+

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
 1
@@ -30,3 +32,18 @@
 
  • 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
    
+
    The Catch modifier allows you to handle errors in BQN (at present, it's the only way to do so). It evaluates the function 𝔽 normally. If this function completes without an error, Catch just returns that result. If not, it stops the error, and calls 𝔾 with the original arguments instead.
    
+↗️
        ⌽⎊'x' "abcd"  # No error
+"dcba"
+
+    ⌽⎊'x' 2       # Can't reverse a unit
+'x'
+
+    0.5 ⌽⎊⊣ ↕6    # A two-argument example
+0.5
+
    
+
    Catch doesn't know anything about what an error is, 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 β€’CurrentError, which is a function that returns a message for the error currently caught (if any).
    
+↗️
        βŒ½βŽŠβ€’CurrentError 2
+"⌽: Argument cannot be a unit"
+
    
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 @@
 
  • Arithmetic (+-Γ—Γ·β‹†βˆšβŒŠβŒˆ|≀<>β‰₯=β‰ )
    • 
 
  • Array depth (≑ and βš‡)
    • 
 
  • Array dimensions (β‰’=β‰ )
    • 
-
  • Assert (!)
    • 
+
  • Assert and Catch (! and ⎊)
    • 
 
  • Deshape and Reshape (β₯Š)
    • 
 
  • Enclose (<)
    • 
 
  • Find (⍷)
    • 
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 @@
 
 
 
+
+
+
+⎊
+Catch
+
 
 
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 @@
 
    (github) / BQN / help
    
 
    Exclamation Mark (!)
    
 
    ! 𝕩: Assert
    
-
    β†’full documentation
    
+
    β†’full documentation
    
 
    Throw an error if 𝕩 is not 1.
    
 ↗️
        ! 1
 1
@@ -18,7 +18,7 @@
 Error: hello
 
    
 
    𝕨 ! 𝕩: Assert With Message
    
-
    β†’full documentation
    
+
    β†’full documentation
    
 
    Throw an error with message 𝕨 if 𝕩 is not 1.
    
 ↗️
        "hi" ! 1
 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 @@
 
    (github) / BQN / help
    
 
    Circled Triangle Down (⎊)
    
 
    π”½βŽŠπ”Ύ 𝕩, 𝕨 π”½βŽŠπ”Ύ 𝕩: Catch
    
+
    β†’full documentation
    
 
    Apply 𝔽 to the arguments.
    
 
    If an error happens when 𝔽 is applied, cancel its execution, apply 𝔾 to the arguments and return its result.
    
 
    Otherwise, return the result of 𝔽.
    
-- 
cgit v1.2.3