Improved parsing and prefix/suffix matching using a `remainder`

parameter

1 files changed, 10 insertions, 1 deletions

diff --git a/api/booleans.md b/api/booleans.md
index d45be505..ab08909d 100644
--- a/api/booleans.md
+++ b/api/booleans.md
@@ -6,7 +6,7 @@
 ## Bool.parse
 
 ```tomo
-Bool.parse : func(text: Text -> Bool?)
+Bool.parse : func(text: Text, remainder: &Text? = none -> Bool?)
 ```
 
 Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`.
@@ -14,6 +14,7 @@ Converts a text representation of a boolean value into a boolean. Acceptable boo
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The string containing the boolean value.  | -
+remainder | `&Text?` | If non-none, this argument will be set to the remainder of the text after the matching part. If none, parsing will only succeed if the entire text matches.  | `none`
 
 **Return:** `yes` if the string matches a recognized truthy boolean value; otherwise return `no`.
 
@@ -27,4 +28,12 @@ text | `Text` | The string containing the boolean value.  | -
 >> Bool.parse("???")
 = none : Bool?
 
+>> Bool.parse("yesJUNK")
+= none : Bool?
+remainder : Text
+>> Bool.parse("yesJUNK", &remainder)
+= yes : Bool?
+>> remainder
+= "JUNK"
+
 ```