From 6ec8f20fc506af4af5513803fb9a708e4f7b5040 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Wed, 2 Apr 2025 16:14:20 -0400
Subject: Syntax change: table types are now: `{K=V; default=...}` and tables
 use `{:K=V, ...; default=...}`

---
 docs/arrays.md |  4 +--
 docs/tables.md | 78 ++++++++++++++++++++++++++++++++++++----------------------
 docs/text.md   |  4 +--
 3 files changed, 53 insertions(+), 33 deletions(-)

(limited to 'docs')

diff --git a/docs/arrays.md b/docs/arrays.md
index 613d793c..e3da6e0e 100644
--- a/docs/arrays.md
+++ b/docs/arrays.md
@@ -235,7 +235,7 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
 - [`func binary_search(arr: [T], by: func(x,y:&T->Int32) = T.compare -> Int)`](#binary_search)
 - [`func by(arr: [T], step: Int -> [T])`](#by)
 - [`func clear(arr: @[T] -> Void)`](#clear)
-- [`func counts(arr: [T] -> {T,Int})`](#counts)
+- [`func counts(arr: [T] -> {T=Int})`](#counts)
 - [`func find(arr: [T], target: T -> Int?)`](#find)
 - [`func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)`](#first)
 - [`func from(arr: [T], first: Int -> [T])`](#from)
@@ -334,7 +334,7 @@ Nothing.
 Counts the occurrences of each element in the array.
 
 ```tomo
-func counts(arr: [T] -> {T,Int})
+func counts(arr: [T] -> {T=Int})
 ```
 
 - `arr`: The array to count elements in.
diff --git a/docs/tables.md b/docs/tables.md
index 42af25d4..f0045ef7 100644
--- a/docs/tables.md
+++ b/docs/tables.md
@@ -7,21 +7,21 @@ support *all* types as both keys and values.
 
 ## Syntax
 
-Tables are written using `{}` curly braces with `:` colons associating key
+Tables are written using `{}` curly braces with `=` equals signs associating key
 expressions with value expressions and commas between entries:
 
 ```tomo
-table := {"A": 10, "B": 20}
+table := {"A"=10, "B"=20}
 ```
 
 Empty tables must specify the key and value types explicitly:
 
 ```tomo
-empty := {:Text,Int}
+empty := {:Text=Int}
 ```
 
 For type annotations, a table that maps keys with type `K` to values of type
-`V` is written as `{K,V}`.
+`V` is written as `{K=V}`.
 
 ### Comprehensions
 
@@ -41,9 +41,9 @@ optional value:
 ```tomo
 table := {"A"=1, "B"=2}
 >> table["A"]
-= 1 : Int?
+= 1?
 >> table["missing"]
-= none : Int?
+= none:Int
 ```
 
 As with all optional values, you can use the `!` postfix operator to assert
@@ -52,10 +52,10 @@ use the `or` operator to provide a fallback value in the case that it's none:
 
 ```tomo
 >> table["A"]!
-= 1 : Int
+= 1
 
 >> table["missing"] or -1
-= -1 : Int
+= -1
 ```
 
 ### Fallback Tables
@@ -67,7 +67,7 @@ is not found in the table itself:
 t := {"A"=10}
 t2 := {"B"=20; fallback=t}
 >> t2["A"]
-= 10 : Int?
+= 10?
 ```
 
 The fallback is available by the `.fallback` field, which returns an optional
@@ -75,11 +75,30 @@ table value:
 
 ```tomo
 >> t2.fallback
-= {"A"=10} : {Text,Int}?
+= {"A"=10}?
 >> t.fallback
-= none : {Text,Int}?
+= none:{Text=Int}
 ```
 
+### Default Values
+
+Tables can specify a default value which will be returned if a value is not
+present in the table or its fallback (if any).
+
+```tomo
+counts := &{"foo"=12; default=0}
+>> counts["foo"]
+= 12
+>> counts["baz"]
+= 0
+counts["baz"] += 1
+>> counts["baz"]
+= 1
+```
+
+When values are accessed from a table with a default value, the return type
+is non-optional (because a value will always be present).
+
 ## Setting Values
 
 You can assign a new key/value mapping or overwrite an existing one using
@@ -133,19 +152,19 @@ iterating over any of the new values.
 
 ## Table Methods
 
-- [`func bump(t:@{K,V}, key: K, amount: Int = 1 -> Void)`](#bump)
-- [`func clear(t:@{K,V})`](#clear)
-- [`func get(t:{K,V}, key: K -> V?)`](#get)
-- [`func has(t:{K,V}, key: K -> Bool)`](#has)
-- [`func remove(t:{K,V}, key: K -> Void)`](#remove)
-- [`func set(t:{K,V}, key: K, value: V -> Void)`](#set)
+- [`func bump(t:&{K=V}, key: K, amount: Int = 1 -> Void)`](#bump)
+- [`func clear(t:&{K=V})`](#clear)
+- [`func get(t:{K=V}, key: K -> V?)`](#get)
+- [`func has(t:{K=V}, key: K -> Bool)`](#has)
+- [`func remove(t:{K=V}, key: K -> Void)`](#remove)
+- [`func set(t:{K=V}, key: K, value: V -> Void)`](#set)
 
 ### `bump`
 Increments the value associated with a key by a specified amount. If the key is
 not already in the table, its value will be assumed to be zero.
 
 ```tomo
-func bump(t:@{K,V}, key: K, amount: Int = 1 -> Void)
+func bump(t:&{K=V}, key: K, amount: Int = 1 -> Void)
 ```
 
 - `t`: The reference to the table.
@@ -170,7 +189,7 @@ t:bump("B", 10)
 Removes all key-value pairs from the table.
 
 ```tomo
-func clear(t:@{K,V})
+func clear(t:&{K=V})
 ```
 
 - `t`: The reference to the table.
@@ -186,32 +205,33 @@ Nothing.
 ---
 
 ### `get`
-Retrieves the value associated with a key, or returns null if the key is not present.
+Retrieves the value associated with a key, or returns `none` if the key is not present.
+**Note:** default values for the table are ignored.
 
 ```tomo
-func get(t:{K,V}, key: K -> V?)
+func get(t:{K=V}, key: K -> V?)
 ```
 
 - `t`: The table.
 - `key`: The key whose associated value is to be retrieved.
 
 **Returns:**  
-The value associated with the key or null if the key is not found.
+The value associated with the key or `none` if the key is not found.
 
 **Example:**  
 ```tomo
 >> t := {"A"=1, "B"=2}
 >> t:get("A")
-= 1 : Int?
+= 1?
 
 >> t:get("????")
-= none : Int?
+= none:Int
 
 >> t:get("A")!
-= 1 : Int
+= 1
 
 >> t:get("????") or 0
-= 0 : Int
+= 0
 ```
 
 ---
@@ -220,7 +240,7 @@ The value associated with the key or null if the key is not found.
 Checks if the table contains a specified key.
 
 ```tomo
-func has(t:{K,V}, key: K -> Bool)
+func has(t:{K=V}, key: K -> Bool)
 ```
 
 - `t`: The table.
@@ -243,7 +263,7 @@ func has(t:{K,V}, key: K -> Bool)
 Removes the key-value pair associated with a specified key.
 
 ```tomo
-func remove(t:{K,V}, key: K -> Void)
+func remove(t:{K=V}, key: K -> Void)
 ```
 
 - `t`: The reference to the table.
@@ -266,7 +286,7 @@ t:remove("A")
 Sets or updates the value associated with a specified key.
 
 ```tomo
-func set(t:{K,V}, key: K, value: V -> Void)
+func set(t:{K=V}, key: K, value: V -> Void)
 ```
 
 - `t`: The reference to the table.
diff --git a/docs/text.md b/docs/text.md
index ca7e399f..fd79fdbd 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -295,7 +295,7 @@ finding the value because the two texts are equivalent under normalization.
 - [`func starts_with(text: Text, prefix: Text -> Bool)`](#starts_with)
 - [`func title(text: Text, language: Text = "C" -> Text)`](#title)
 - [`func to(text: Text, last: Int -> Text)`](#to)
-- [`func translate(translations:{Text,Text} -> Text)`](#translate)
+- [`func translate(translations:{Text=Text} -> Text)`](#translate)
 - [`func trim(text: Text, to_trim: Text = " $\t\r\n", left: Bool = yes, right: Bool = yes -> Text)`](#trim)
 - [`func upper(text: Text, language: Text "C" -> Text)`](#upper)
 - [`func utf32_codepoints(text: Text -> [Int32])`](#utf32_codepoints)
@@ -1065,7 +1065,7 @@ replacement text, so replacement text is not recursively modified. See
 [`replace()`](#replace) for more information about replacement behavior.
 
 ```tomo
-func translate(translations:{Text,Text} -> Text)
+func translate(translations:{Text=Text} -> Text)
 ```
 
 - `text`: The text in which to perform replacements.
-- 
cgit v1.2.3