From de49bc5bb3198f450cb367085f9def0d89782258 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Mon, 16 Sep 2024 16:06:19 -0400
Subject: Deprecate :or_else()/:or_fail()/:or_exit() in favor of the `or`
 operator

---
 docs/optionals.md | 23 +++++++++++++----------
 docs/tables.md    |  2 +-
 2 files changed, 14 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/optionals.md b/docs/optionals.md
index 54fe5f5c..2bc747f9 100644
--- a/docs/optionals.md
+++ b/docs/optionals.md
@@ -30,25 +30,28 @@ having to use a more generalized form of `enum` which may have different naming
 conventions and which would generate a lot of unnecessary code. 
 
 In addition to using conditionals to check for null values, you can also use
-`:or_else(fallback)` or `:or_fail()` or `:or_exit()`:
+`or` to get a non-null value by either providing an alternative non-null value
+or by providing an early out statement like `return`/`skip`/`stop` or a function
+with an `Abort` type like `fail()` or `exit()`:
 
 ```tomo
 maybe_x := 5?
->> maybe_x:or_else(-1)
+>> maybe_x or -1
 = 5 : Int
->> maybe_x:or_fail()
+>> maybe_x or fail("No value!")
 = 5 : Int
 
 maybe_x = !Int
->> maybe_x:or_else(-1)
+>> maybe_x or -1
 = -1 : Int
->> maybe_x:or_fail("No value!")
+>> maybe_x or fail("No value!")
 # Failure!
 
+func do_stuff(matches:[Text]):
+    pass
 
-maybe_x = !Int
->> maybe_x:or_exit()
-= -1 : Int
->> maybe_x:or_exit("No value!")
-# Exit!
+for line in lines:
+    matches := line:matches($/{..},{..}/) or skip
+    # The `or skip` above means that if we're here, `matches` is non-null:
+    do_stuff(matches)
 ```
diff --git a/docs/tables.md b/docs/tables.md
index 9de07b67..f589eb2e 100644
--- a/docs/tables.md
+++ b/docs/tables.md
@@ -195,7 +195,7 @@ The value associated with the key or null if the key is not found.
 >> t:get("A")!
 = 1 : Int
 
->> t:get("????"):or_else(0)
+>> t:get("????") or 0
 = 0 : Int
 ```
 
-- 
cgit v1.2.3