Bruce/tomo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity

Update docs to standardize function signature formatting

Browse Source
This commit is contained in:
Bruce Hill 2024-10-09 13:48:45 -04:00
parent 63d48e9feb
commit 5a80ff0db3
15 changed files with 566 additions and 557 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/README.md
View File

@ -42,9 +42,9 @@ Information about Tomo's built-in types can be found here:
**Description:** **Description:**
Gets a line of user input text with a prompt. Gets a line of user input text with a prompt.
**Usage:** **Signature:**
```markdown ```tomo
ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Void) func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Void)
``` ```
**Parameters:** **Parameters:**
@ -65,7 +65,7 @@ A line of user input text without a trailing newline, or empty text if
something went wrong (e.g. the user hit `Ctrl-D`). something went wrong (e.g. the user hit `Ctrl-D`).
**Example:** **Example:**
```markdown ```tomo
>> ask("What's your name? ") >> ask("What's your name? ")
= "Arthur Dent" = "Arthur Dent"
``` ```
@ -77,9 +77,9 @@ something went wrong (e.g. the user hit `Ctrl-D`).
**Description:** **Description:**
Exits the program with a given status and optionally prints a message. Exits the program with a given status and optionally prints a message.
**Usage:** **Signature:**
```markdown ```tomo
ask(message:Text? = !Text, status:Int32 = 1[32] -> Void) func ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -93,7 +93,7 @@ ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
This function never returns. This function never returns.
**Example:** **Example:**
```markdown ```tomo
exit(status=1, "Goodbye forever!") exit(status=1, "Goodbye forever!")
``` ```
@ -104,9 +104,9 @@ exit(status=1, "Goodbye forever!")
**Description:** **Description:**
Prints a message to the console. Prints a message to the console.
**Usage:** **Signature:**
```markdown ```tomo
say(text:Text, newline:Bool = yes -> Void) func say(text:Text, newline:Bool = yes -> Void)
``` ```
**Parameters:** **Parameters:**
@ -118,7 +118,7 @@ say(text:Text, newline:Bool = yes -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
say("Hello ", newline=no) say("Hello ", newline=no)
say("world!") say("world!")
``` ```
@ -130,9 +130,9 @@ say("world!")
**Description:** **Description:**
Pause execution for a given number of seconds. Pause execution for a given number of seconds.
**Usage:** **Signature:**
```markdown ```tomo
sleep(seconds: Num -> Void) func sleep(seconds: Num -> Void)
``` ```
**Parameters:** **Parameters:**
@ -143,7 +143,7 @@ sleep(seconds: Num -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
sleep(1.5) sleep(1.5)
``` ```
@ -154,9 +154,9 @@ sleep(1.5)
**Description:** **Description:**
Prints a message to the console, aborts the program, and prints a stack trace. Prints a message to the console, aborts the program, and prints a stack trace.
**Usage:** **Signature:**
```markdown ```tomo
fail(message:Text -> Abort) func fail(message:Text -> Abort)
``` ```
**Parameters:** **Parameters:**
@ -167,7 +167,7 @@ fail(message:Text -> Abort)
Nothing, aborts the program. Nothing, aborts the program.
**Example:** **Example:**
```markdown ```tomo
fail("Oh no!") fail("Oh no!")
``` ```
@ -178,9 +178,9 @@ fail("Oh no!")
**Description:** **Description:**
Gets the current time. This is an alias for `DateTime.now()`. Gets the current time. This is an alias for `DateTime.now()`.
**Usage:** **Signature:**
```markdown ```tomo
now(->DateTime) func now(->DateTime)
``` ```
**Parameters:** **Parameters:**
@ -191,7 +191,7 @@ None.
The current moment as a DateTime. The current moment as a DateTime.
**Example:** **Example:**
```markdown ```tomo
>> now() >> now()
= Sun Sep 29 20:12:33 2024 = Sun Sep 29 20:12:33 2024
``` ```

186
docs/arrays.md
View File

@ -237,9 +237,9 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
**Description:** **Description:**
Performs a binary search on a sorted array. Performs a binary search on a sorted array.
**Usage:** **Signature:**
```markdown ```tomo
binary_search(arr: [T], by=T.compare -> Int) func binary_search(arr: [T], by: func(x,y:&T->Int32) = T.compare -> Int)
``` ```
**Parameters:** **Parameters:**
@ -255,7 +255,7 @@ order. That is, if the item is found, return its index, otherwise return the
place where it would be found if it were inserted and the array were sorted. place where it would be found if it were inserted and the array were sorted.
**Example:** **Example:**
```markdown ```tomo
>> [1, 3, 5, 7, 9]:binary_search(5) >> [1, 3, 5, 7, 9]:binary_search(5)
= 3 = 3
@ -273,9 +273,9 @@ place where it would be found if it were inserted and the array were sorted.
**Description:** **Description:**
Creates a new array with elements spaced by the specified step value. Creates a new array with elements spaced by the specified step value.
**Usage:** **Signature:**
```markdown ```tomo
by(arr: [T], step: Int -> [T]) func by(arr: [T], step: Int -> [T])
``` ```
**Parameters:** **Parameters:**
@ -287,7 +287,7 @@ by(arr: [T], step: Int -> [T])
A new array with every `step`-th element from the original array. A new array with every `step`-th element from the original array.
**Example:** **Example:**
```markdown ```tomo
>> [1, 2, 3, 4, 5, 6]:by(2) >> [1, 2, 3, 4, 5, 6]:by(2)
= [1, 3, 5] = [1, 3, 5]
``` ```
@ -299,9 +299,9 @@ A new array with every `step`-th element from the original array.
**Description:** **Description:**
Clears all elements from the array. Clears all elements from the array.
**Usage:** **Signature:**
```markdown ```tomo
clear(arr: & [T] -> Void) func clear(arr: &[T] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -312,7 +312,7 @@ clear(arr: & [T] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> my_array:clear() >> my_array:clear()
``` ```
@ -323,9 +323,9 @@ Nothing.
**Description:** **Description:**
Counts the occurrences of each element in the array. Counts the occurrences of each element in the array.
**Usage:** **Signature:**
```markdown ```tomo
counts(arr: [T] -> {T: Int}) func counts(arr: [T] -> {T: Int})
``` ```
**Parameters:** **Parameters:**
@ -336,7 +336,7 @@ counts(arr: [T] -> {T: Int})
A table mapping each element to its count. A table mapping each element to its count.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30, 30, 30]:counts() >> [10, 20, 30, 30, 30]:counts()
= {10: 1, 20: 1, 30: 3} = {10: 1, 20: 1, 30: 3}
``` ```
@ -348,9 +348,9 @@ A table mapping each element to its count.
**Description:** **Description:**
Finds the index of the first occurrence of an element (if any). Finds the index of the first occurrence of an element (if any).
**Usage:** **Signature:**
```markdown ```tomo
find(arr: [T] -> Int?) func find(arr: [T] -> Int?)
``` ```
**Parameters:** **Parameters:**
@ -361,7 +361,7 @@ find(arr: [T] -> Int?)
The index of the first occurrence or `!Int` if not found. The index of the first occurrence or `!Int` if not found.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30, 40, 50]:find(20) >> [10, 20, 30, 40, 50]:find(20)
= 2? = 2?
@ -376,9 +376,9 @@ The index of the first occurrence or `!Int` if not found.
**Description:** **Description:**
Find the index of the first item that matches a predicate function (if any). Find the index of the first item that matches a predicate function (if any).
**Usage:** **Signature:**
```markdown ```tomo
first(arr: [T], predicate: func(item:&T)->Bool -> Int) func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)
``` ```
**Parameters:** **Parameters:**
@ -392,7 +392,7 @@ Returns the index of the first item where the predicate is true or `!Int` if no
item matches. item matches.
**Example:** **Example:**
```markdown ```tomo
>> [4, 5, 6]:find(func(i:&Int): i:is_prime()) >> [4, 5, 6]:find(func(i:&Int): i:is_prime())
= 5? = 5?
>> [4, 6, 8]:find(func(i:&Int): i:is_prime()) >> [4, 6, 8]:find(func(i:&Int): i:is_prime())
@ -406,9 +406,9 @@ item matches.
**Description:** **Description:**
Returns a slice of the array starting from a specified index. Returns a slice of the array starting from a specified index.
**Usage:** **Signature:**
```markdown ```tomo
from(arr: [T], first: Int -> [T]) func from(arr: [T], first: Int -> [T])
``` ```
**Parameters:** **Parameters:**
@ -420,7 +420,7 @@ from(arr: [T], first: Int -> [T])
A new array starting from the specified index. A new array starting from the specified index.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30, 40, 50]:from(3) >> [10, 20, 30, 40, 50]:from(3)
= [30, 40, 50] = [30, 40, 50]
``` ```
@ -432,9 +432,9 @@ A new array starting from the specified index.
**Description:** **Description:**
Checks if the array has any elements. Checks if the array has any elements.
**Usage:** **Signature:**
```markdown ```tomo
has(arr: [T] -> Bool) func has(arr: [T] -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -445,7 +445,7 @@ has(arr: [T] -> Bool)
`yes` if the array has elements, `no` otherwise. `yes` if the array has elements, `no` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30]:has(20) >> [10, 20, 30]:has(20)
= yes = yes
``` ```
@ -458,9 +458,9 @@ has(arr: [T] -> Bool)
Removes and returns the top element of a heap. By default, this is the Removes and returns the top element of a heap. By default, this is the
*minimum* value in the heap. *minimum* value in the heap.
**Usage:** **Signature:**
```markdown ```tomo
heap_pop(arr: & [T], by=T.compare -> T) func heap_pop(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> T)
``` ```
**Parameters:** **Parameters:**
@ -473,7 +473,7 @@ heap_pop(arr: & [T], by=T.compare -> T)
The removed top element of the heap. The removed top element of the heap.
**Example:** **Example:**
```markdown ```tomo
>> my_heap := [30, 10, 20] >> my_heap := [30, 10, 20]
>> my_heap:heapify() >> my_heap:heapify()
>> my_heap:heap_pop() >> my_heap:heap_pop()
@ -488,9 +488,9 @@ The removed top element of the heap.
Adds an element to the heap and maintains the heap property. By default, this Adds an element to the heap and maintains the heap property. By default, this
is a *minimum* heap. is a *minimum* heap.
**Usage:** **Signature:**
```markdown ```tomo
heap_push(arr: & [T], item: T, by=T.compare -> Void) func heap_push(arr: &[T], item: T, by=T.compare -> Void)
``` ```
**Parameters:** **Parameters:**
@ -504,7 +504,7 @@ heap_push(arr: & [T], item: T, by=T.compare -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> my_heap:heap_push(10) >> my_heap:heap_push(10)
``` ```
@ -515,9 +515,9 @@ Nothing.
**Description:** **Description:**
Converts an array into a heap. Converts an array into a heap.
**Usage:** **Signature:**
```markdown ```tomo
heapify(arr: & [T], by=T.compare -> Void) func heapify(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> Void)
``` ```
**Parameters:** **Parameters:**
@ -530,7 +530,7 @@ heapify(arr: & [T], by=T.compare -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> my_heap := [30, 10, 20] >> my_heap := [30, 10, 20]
>> my_heap:heapify() >> my_heap:heapify()
``` ```
@ -542,9 +542,9 @@ Nothing.
**Description:** **Description:**
Inserts an element at a specified position in the array. Inserts an element at a specified position in the array.
**Usage:** **Signature:**
```markdown ```tomo
insert(arr: & [T], item: T, at: Int = 0 -> Void) func insert(arr: &[T], item: T, at: Int = 0 -> Void)
``` ```
**Parameters:** **Parameters:**
@ -559,7 +559,7 @@ insert(arr: & [T], item: T, at: Int = 0 -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> arr := [10, 20] >> arr := [10, 20]
>> arr:insert(30) >> arr:insert(30)
>> arr >> arr
@ -577,9 +577,9 @@ Nothing.
**Description:** **Description:**
Inserts an array of items at a specified position in the array. Inserts an array of items at a specified position in the array.
**Usage:** **Signature:**
```markdown ```tomo
insert_all(arr: & [T], items: [T], at: Int = 0 -> Void) func insert_all(arr: &[T], items: [T], at: Int = 0 -> Void)
``` ```
**Parameters:** **Parameters:**
@ -594,7 +594,7 @@ insert_all(arr: & [T], items: [T], at: Int = 0 -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
arr := [10, 20] arr := [10, 20]
arr:insert_all([30, 40]) arr:insert_all([30, 40])
>> arr >> arr
@ -612,9 +612,9 @@ arr:insert_all([99, 100], at=2)
**Description:** **Description:**
Selects a random element from the array. Selects a random element from the array.
**Usage:** **Signature:**
```markdown ```tomo
random(arr: [T] -> T) func random(arr: [T] -> T)
``` ```
**Parameters:** **Parameters:**
@ -625,7 +625,7 @@ random(arr: [T] -> T)
A random element from the array. A random element from the array.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30]:random() >> [10, 20, 30]:random()
= 20 = 20
``` ```
@ -637,9 +637,9 @@ A random element from the array.
**Description:** **Description:**
Removes elements from the array starting at a specified index. Removes elements from the array starting at a specified index.
**Usage:** **Signature:**
```markdown ```tomo
remove_at(arr: & [T], at: Int = -1, count: Int = 1 -> Void) func remove_at(arr: &[T], at: Int = -1, count: Int = 1 -> Void)
``` ```
**Parameters:** **Parameters:**
@ -652,7 +652,7 @@ remove_at(arr: & [T], at: Int = -1, count: Int = 1 -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
arr := [10, 20, 30, 40, 50] arr := [10, 20, 30, 40, 50]
arr:remove_at(2) arr:remove_at(2)
>> arr >> arr
@ -670,9 +670,9 @@ arr:remove_at(2, count=2)
**Description:** **Description:**
Removes all occurrences of a specified item from the array. Removes all occurrences of a specified item from the array.
**Usage:** **Signature:**
```markdown ```tomo
remove_item(arr: & [T], item: T, max_count: Int = -1 -> Void) func remove_item(arr: &[T], item: T, max_count: Int = -1 -> Void)
``` ```
**Parameters:** **Parameters:**
@ -685,7 +685,7 @@ remove_item(arr: & [T], item: T, max_count: Int = -1 -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
arr := [10, 20, 10, 20, 30] arr := [10, 20, 10, 20, 30]
arr:remove_item(10) arr:remove_item(10)
>> arr >> arr
@ -703,9 +703,9 @@ arr:remove_item(20, max_count=1)
**Description:** **Description:**
Returns a reversed slice of the array. Returns a reversed slice of the array.
**Usage:** **Signature:**
```markdown ```tomo
reversed(arr: [T] -> [T]) func reversed(arr: [T] -> [T])
``` ```
**Parameters:** **Parameters:**
@ -716,7 +716,7 @@ reversed(arr: [T] -> [T])
A slice of the array with elements in reverse order. A slice of the array with elements in reverse order.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30]:reversed() >> [10, 20, 30]:reversed()
= [30, 20, 10] = [30, 20, 10]
``` ```
@ -729,9 +729,9 @@ A slice of the array with elements in reverse order.
Selects a sample of elements from the array, optionally with weighted Selects a sample of elements from the array, optionally with weighted
probabilities. probabilities.
**Usage:** **Signature:**
```markdown ```tomo
sample(arr: [T], count: Int, weights: [Num]? = ![Num] -> [T]) func sample(arr: [T], count: Int, weights: [Num]? = ![Num] -> [T])
``` ```
**Parameters:** **Parameters:**
@ -755,7 +755,7 @@ Errors will be raised if any of the following conditions occurs:
A list of sampled elements from the array. A list of sampled elements from the array.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30]:sample(2, weights=[90%, 5%, 5%]) >> [10, 20, 30]:sample(2, weights=[90%, 5%, 5%])
= [10, 10] = [10, 10]
``` ```
@ -767,9 +767,9 @@ A list of sampled elements from the array.
**Description:** **Description:**
Shuffles the elements of the array in place. Shuffles the elements of the array in place.
**Usage:** **Signature:**
```markdown ```tomo
shuffle(arr: & [T] -> Void) func shuffle(arr: &[T] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -780,7 +780,7 @@ shuffle(arr: & [T] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> arr:shuffle() >> arr:shuffle()
``` ```
@ -791,9 +791,9 @@ Nothing.
**Description:** **Description:**
Creates a new array with elements shuffled. Creates a new array with elements shuffled.
**Usage:** **Signature:**
```markdown ```tomo
shuffled(arr: [T] -> [T]) func shuffled(arr: [T] -> [T])
``` ```
**Parameters:** **Parameters:**
@ -804,7 +804,7 @@ shuffled(arr: [T] -> [T])
A new array with shuffled elements. A new array with shuffled elements.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30, 40]:shuffled() >> [10, 20, 30, 40]:shuffled()
= [40, 10, 30, 20] = [40, 10, 30, 20]
``` ```
@ -816,9 +816,9 @@ A new array with shuffled elements.
**Description:** **Description:**
Sorts the elements of the array in place in ascending order (small to large). Sorts the elements of the array in place in ascending order (small to large).
**Usage:** **Signature:**
```markdown ```tomo
sort(arr: & [T], by=T.compare -> Void) func sort(arr: &[T], by=T.compare -> Void)
``` ```
**Parameters:** **Parameters:**
@ -831,7 +831,7 @@ sort(arr: & [T], by=T.compare -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
arr := [40, 10, -30, 20] arr := [40, 10, -30, 20]
arr:sort() arr:sort()
>> arr >> arr
@ -849,8 +849,8 @@ arr:sort(func(a,b:&Int): a:abs() <> b:abs())
**Description:** **Description:**
Creates a new array with elements sorted. Creates a new array with elements sorted.
**Usage:** **Signature:**
```markdown ```tomo
sorted(arr: [T], by=T.compare -> [T]) sorted(arr: [T], by=T.compare -> [T])
``` ```
@ -864,7 +864,7 @@ sorted(arr: [T], by=T.compare -> [T])
A new array with sorted elements. A new array with sorted elements.
**Example:** **Example:**
```markdown ```tomo
>> [40, 10, -30, 20]:sorted() >> [40, 10, -30, 20]:sorted()
= [-30, 10, 20, 40] = [-30, 10, 20, 40]
@ -879,8 +879,8 @@ A new array with sorted elements.
**Description:** **Description:**
Returns a slice of the array from the start of the original array up to a specified index (inclusive). Returns a slice of the array from the start of the original array up to a specified index (inclusive).
**Usage:** **Signature:**
```markdown ```tomo
to(arr: [T], last: Int -> [T]) to(arr: [T], last: Int -> [T])
``` ```
@ -893,7 +893,7 @@ to(arr: [T], last: Int -> [T])
A new array containing elements from the start up to the specified index. A new array containing elements from the start up to the specified index.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 30, 40, 50]:to(3) >> [10, 20, 30, 40, 50]:to(3)
= [10, 20, 30] = [10, 20, 30]
@ -908,8 +908,8 @@ A new array containing elements from the start up to the specified index.
**Description:** **Description:**
Returns a Set that contains the unique elements of the array. Returns a Set that contains the unique elements of the array.
**Usage:** **Signature:**
```markdown ```tomo
unique(arr: [T] -> {T}) unique(arr: [T] -> {T})
``` ```
@ -921,7 +921,7 @@ unique(arr: [T] -> {T})
A set containing only unique elements from the array. A set containing only unique elements from the array.
**Example:** **Example:**
```markdown ```tomo
>> [10, 20, 10, 10, 30]:unique() >> [10, 20, 10, 10, 30]:unique()
= {10, 20, 30} = {10, 20, 30}
``` ```

8
docs/booleans.md
View File

@ -14,9 +14,9 @@ Converts a string representation of a boolean value into a boolean. Acceptable
boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`,
`true`/`false`, `on`/`off`. `true`/`false`, `on`/`off`.
**Usage:** **Signature:**
```tomo ```tomo
from_text(text: Text, success: Bool = !&Bool -> Bool) func from_text(text: Text, success: Bool = !&Bool -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -47,9 +47,9 @@ from_text(text: Text, success: Bool = !&Bool -> Bool)
**Description:** **Description:**
Generates a random boolean value based on a specified probability. Generates a random boolean value based on a specified probability.
**Usage:** **Signature:**
```tomo ```tomo
random(p: Float = 0.5 -> Bool) func random(p: Float = 0.5 -> Bool)
``` ```
**Parameters:** **Parameters:**

4
docs/bytes.md
View File

@ -14,9 +14,9 @@ integer with a `[B]` suffix, e.g. `255[B]`.
**Description:** **Description:**
Generates a random byte value in the specified range. Generates a random byte value in the specified range.
**Usage:** **Signature:**
```tomo ```tomo
random(min: Byte = Byte.min, max: Byte = Byte.max -> Byte) func random(min: Byte = Byte.min, max: Byte = Byte.max -> Byte)
``` ```
**Parameters:** **Parameters:**

48
docs/channels.md
View File

@ -29,9 +29,9 @@ small_channel := |:Int; max_size=5|
**Description:** **Description:**
Adds an item to the channel. Adds an item to the channel.
**Usage:** **Signature:**
```markdown ```tomo
give(channel:|T|, item: T, front: Bool = no -> Void) func give(channel:|T|, item: T, front: Bool = no -> Void)
``` ```
**Parameters:** **Parameters:**
@ -44,7 +44,7 @@ give(channel:|T|, item: T, front: Bool = no -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> channel:give("Hello") >> channel:give("Hello")
``` ```
@ -55,9 +55,9 @@ Nothing.
**Description:** **Description:**
Adds multiple items to the channel. Adds multiple items to the channel.
**Usage:** **Signature:**
```markdown ```tomo
give_all(channel:|T|, items: [T], front: Bool = no -> Void) func give_all(channel:|T|, items: [T], front: Bool = no -> Void)
``` ```
**Parameters:** **Parameters:**
@ -70,7 +70,7 @@ give_all(channel:|T|, items: [T], front: Bool = no -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> channel:give_all([1, 2, 3]) >> channel:give_all([1, 2, 3])
``` ```
@ -81,9 +81,9 @@ Nothing.
**Description:** **Description:**
Removes and returns an item from the channel. If the channel is empty, it waits until an item is available. Removes and returns an item from the channel. If the channel is empty, it waits until an item is available.
**Usage:** **Signature:**
```markdown ```tomo
get(channel:|T|, front: Bool = yes -> T) func get(channel:|T|, front: Bool = yes -> T)
``` ```
**Parameters:** **Parameters:**
@ -95,7 +95,7 @@ get(channel:|T|, front: Bool = yes -> T)
The item removed from the channel. The item removed from the channel.
**Example:** **Example:**
```markdown ```tomo
>> channel:peek() >> channel:peek()
= "Hello" = "Hello"
``` ```
@ -108,9 +108,9 @@ The item removed from the channel.
Returns the next item that will come out of the channel, but without removing Returns the next item that will come out of the channel, but without removing
it. If the channel is empty, it waits until an item is available. it. If the channel is empty, it waits until an item is available.
**Usage:** **Signature:**
```markdown ```tomo
peek(channel:|T|, front: Bool = yes -> T) func peek(channel:|T|, front: Bool = yes -> T)
``` ```
**Parameters:** **Parameters:**
@ -122,7 +122,7 @@ peek(channel:|T|, front: Bool = yes -> T)
The item removed from the channel. The item removed from the channel.
**Example:** **Example:**
```markdown ```tomo
>> channel:get() >> channel:get()
= "Hello" = "Hello"
``` ```
@ -134,9 +134,9 @@ The item removed from the channel.
**Description:** **Description:**
Removes all items from the channel. Removes all items from the channel.
**Usage:** **Signature:**
```markdown ```tomo
clear(channel:|T| -> Void) func clear(channel:|T| -> Void)
``` ```
**Parameters:** **Parameters:**
@ -147,7 +147,7 @@ clear(channel:|T| -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> channel:clear() >> channel:clear()
``` ```
@ -158,9 +158,9 @@ Nothing.
**Description:** **Description:**
Returns a list of all items currently in the channel without removing them. Returns a list of all items currently in the channel without removing them.
**Usage:** **Signature:**
```markdown ```tomo
channel:view(->[T]) func channel:view(->[T])
``` ```
**Parameters:** **Parameters:**
@ -171,7 +171,7 @@ channel:view(->[T])
An array of items currently in the channel. An array of items currently in the channel.
**Example:** **Example:**
```markdown ```tomo
>> channel:view() >> channel:view()
= [1, 2, 3] = [1, 2, 3]
``` ```

10
docs/command-line-parsing.md
View File

@ -18,10 +18,10 @@ for the arguments to `main()`:
```bash ```bash
$ tomo greet.tm $ tomo greet.tm
greet: Required argument 'name' was not provided! greet: Required argument 'name' was not provided!
Usage: greet [--help] <name> [--be-excited] Signature: greet [--help] <name> [--be-excited]
$ tomo greet.tm --help $ tomo greet.tm --help
Usage: greet [--help] <name> [--be-excited] Signature: greet [--help] <name> [--be-excited]
$ tomo greet.tm "Zaphod" $ tomo greet.tm "Zaphod"
Hi Zaphod. Hi Zaphod.
@ -34,7 +34,7 @@ Hi Zaphod.
$ tomo greet.tm --not-a-real-argument "Bob" $ tomo greet.tm --not-a-real-argument "Bob"
greet: Unrecognized argument: --not-a-real-argument greet: Unrecognized argument: --not-a-real-argument
Usage: greet [--help] <name> [--be-excited] Signature: greet [--help] <name> [--be-excited]
``` ```
Underscores in argument names are converted to dashes when parsing command line Underscores in argument names are converted to dashes when parsing command line
@ -88,13 +88,13 @@ enum Foo(One, Two, Three)
func main(foo:Foo): func main(foo:Foo):
>> foo >> foo
# Usage: # Signature:
$ tomo foo.tm one $ tomo foo.tm one
>> Foo.One >> Foo.One
$ tomo foo.tm xxx $ tomo foo.tm xxx
foo: Invalid value provided for --foo; valid values are: One Two foo: Invalid value provided for --foo; valid values are: One Two
Usage: foo [--help] <foo> Signature: foo [--help] <foo>
``` ```
### Arrays of Text ### Arrays of Text

139
docs/datetime.md
View File

@ -77,13 +77,14 @@ affected by leap seconds. For this reason, `after()` takes an argument,
`timezone` which is used to determine in which timezone the offsets should be `timezone` which is used to determine in which timezone the offsets should be
calculated. calculated.
**Usage:** **Signature:**
```markdown ```tomo
datetime:after(seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> DateTime) func after(datetime: DateTime, seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> DateTime)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime used as a starting point.
- `seconds` (optional): An amount of seconds to offset the datetime (default: 0). - `seconds` (optional): An amount of seconds to offset the datetime (default: 0).
- `minutes` (optional): An amount of minutes to offset the datetime (default: 0). - `minutes` (optional): An amount of minutes to offset the datetime (default: 0).
- `hours` (optional): An amount of hours to offset the datetime (default: 0). - `hours` (optional): An amount of hours to offset the datetime (default: 0).
@ -98,7 +99,7 @@ datetime:after(seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days
A new `DateTime` offset by the given amount. A new `DateTime` offset by the given amount.
**Example:** **Example:**
```markdown ```tomo
>> DateTime(2024, 9, 29, hour=19):after(days=1, minutes=30) >> DateTime(2024, 9, 29, hour=19):after(days=1, minutes=30)
= Mon Sep 30 19:30:00 2024 EDT = Mon Sep 30 19:30:00 2024 EDT
``` ```
@ -111,20 +112,21 @@ A new `DateTime` offset by the given amount.
Return a text representation of the datetime using the `"%F"` format Return a text representation of the datetime using the `"%F"` format
specifier, which gives the date in `YYYY-MM-DD` form. specifier, which gives the date in `YYYY-MM-DD` form.
**Usage:** **Signature:**
```markdown ```tomo
datetime:date(timezone : Text? = !Text -> Text) func date(datetime: DateTime, timezone : Text? = !Text -> Text)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime to get the date from.
- `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone). - `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone).
**Returns:** **Returns:**
The date in `YYYY-MM-DD` format. The date in `YYYY-MM-DD` format.
**Example:** **Example:**
```markdown ```tomo
>> DateTime(2024, 9, 29):date() >> DateTime(2024, 9, 29):date()
= "2024-09-29" = "2024-09-29"
``` ```
@ -139,13 +141,14 @@ options, return a text representation of the given date in the given format. If
`timezone` is specified, use that timezone instead of the current local `timezone` is specified, use that timezone instead of the current local
timezone. timezone.
**Usage:** **Signature:**
```markdown ```tomo
datetime:format(format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text) func format(datetime: DateTime, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime to format.
- `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`). - `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`).
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone). - `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -153,7 +156,7 @@ datetime:format(format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> DateTime(2024, 9, 29):format("%A") >> DateTime(2024, 9, 29):format("%A")
= "Sunday" = "Sunday"
``` ```
@ -166,9 +169,9 @@ Nothing.
Return a datetime object that represents the same moment in time as Return a datetime object that represents the same moment in time as
the given UNIX epoch timestamp (seconds since January 1, 1970 UTC). the given UNIX epoch timestamp (seconds since January 1, 1970 UTC).
**Usage:** **Signature:**
```markdown ```tomo
DateTime.from_unix_timestamp(timestamp: Int64 -> DateTime) func from_unix_timestamp(timestamp: Int64 -> DateTime)
``` ```
**Parameters:** **Parameters:**
@ -179,7 +182,7 @@ DateTime.from_unix_timestamp(timestamp: Int64 -> DateTime)
A `DateTime` object representing the same moment as the given UNIX timestamp. A `DateTime` object representing the same moment as the given UNIX timestamp.
**Example:** **Example:**
```markdown ```tomo
# In the New York timezone: # In the New York timezone:
>> DateTime.from_unix_timestamp(0) >> DateTime.from_unix_timestamp(0)
= Wed Dec 31 19:00:00 1969 = Wed Dec 31 19:00:00 1969
@ -193,13 +196,14 @@ A `DateTime` object representing the same moment as the given UNIX timestamp.
Get various components of the given datetime object and store them in the Get various components of the given datetime object and store them in the
provided optional fields. provided optional fields.
**Usage:** **Signature:**
```markdown ```tomo
datetime:get(year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, hour : &Int? = !&Int, minute : &Int? = !&Int, second : &Int? = !&Int, nanosecond : &Int? = !&Int, weekday : &Int? = !&Int, timezone : Text? = !Text -> Void) func get(datetime: DateTime, year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, hour : &Int? = !&Int, minute : &Int? = !&Int, second : &Int? = !&Int, nanosecond : &Int? = !&Int, weekday : &Int? = !&Int, timezone : Text? = !Text -> Void)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime from which to extract information.
- `year`: If non-null, store the year here. - `year`: If non-null, store the year here.
- `month`: If non-null, store the month here (1-12). - `month`: If non-null, store the month here (1-12).
- `day`: If non-null, store the day of the month here (1-31). - `day`: If non-null, store the day of the month here (1-31).
@ -214,7 +218,7 @@ datetime:get(year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, h
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
dt := DateTime(2024, 9, 29) dt := DateTime(2024, 9, 29)
month := 0 month := 0
dt:get(month=&month) dt:get(month=&month)
@ -231,9 +235,9 @@ Get the local timezone's name (e.g. `America/New_York` or `UTC`. By default,
this value is read from `/etc/localtime`, however, this can be overridden by this value is read from `/etc/localtime`, however, this can be overridden by
calling `DateTime.set_local_timezone(...)`. calling `DateTime.set_local_timezone(...)`.
**Usage:** **Signature:**
```markdown ```tomo
DateTime.get_local_timezone(->Text) func get_local_timezone(->Text)
``` ```
**Parameters:** **Parameters:**
@ -244,7 +248,7 @@ None.
The name of the current local timezone. The name of the current local timezone.
**Example:** **Example:**
```markdown ```tomo
>> DateTime.get_local_timezone() >> DateTime.get_local_timezone()
= "America/New_York" = "America/New_York"
``` ```
@ -256,20 +260,21 @@ The name of the current local timezone.
**Description:** **Description:**
Return the number of hours until a given datetime. Return the number of hours until a given datetime.
**Usage:** **Signature:**
```markdown ```tomo
datetime:hours_till(then:DateTime -> Num) func hours_till(datetime: DateTime, then:DateTime -> Num)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in hours). - `then`: Another datetime that we want to calculate the time offset from (in hours).
**Returns:** **Returns:**
The number of hours (possibly fractional, possibly negative) until the given time. The number of hours (possibly fractional, possibly negative) until the given time.
**Example:** **Example:**
```markdown ```tomo
the_future := now():after(hours=1, minutes=30) the_future := now():after(hours=1, minutes=30)
>> now():hours_till(the_future) >> now():hours_till(the_future)
= 1.5 = 1.5
@ -282,20 +287,21 @@ the_future := now():after(hours=1, minutes=30)
**Description:** **Description:**
Return the number of minutes until a given datetime. Return the number of minutes until a given datetime.
**Usage:** **Signature:**
```markdown ```tomo
datetime:minutes_till(then:DateTime -> Num) func minutes_till(datetime: DateTime, then:DateTime -> Num)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in minutes). - `then`: Another datetime that we want to calculate the time offset from (in minutes).
**Returns:** **Returns:**
The number of minutes (possibly fractional, possibly negative) until the given time. The number of minutes (possibly fractional, possibly negative) until the given time.
**Example:** **Example:**
```markdown ```tomo
the_future := now():after(minutes=1, seconds=30) the_future := now():after(minutes=1, seconds=30)
>> now():minutes_till(the_future) >> now():minutes_till(the_future)
= 1.5 = 1.5
@ -310,9 +316,9 @@ Return a new `DateTime` object representing the given time parameters expressed
in local time. This function is the same as calling `DateTime` directly as a in local time. This function is the same as calling `DateTime` directly as a
constructor. constructor.
**Usage:** **Signature:**
```markdown ```tomo
DateTime.new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> DateTime) func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> DateTime)
``` ```
**Parameters:** **Parameters:**
@ -332,7 +338,7 @@ example, `DateTime.new(..., hour=3, minute=65)` is the same as
integer, an error will be raised. integer, an error will be raised.
**Example:** **Example:**
```markdown ```tomo
>> DateTime.new(2024, 9, 29) >> DateTime.new(2024, 9, 29)
= Mon Sep 30 00:00:00 2024 EDT = Mon Sep 30 00:00:00 2024 EDT
@ -349,9 +355,9 @@ integer, an error will be raised.
Get a `DateTime` object representing the current date and time. This function Get a `DateTime` object representing the current date and time. This function
is the same as the global function `now()`. is the same as the global function `now()`.
**Usage:** **Signature:**
```markdown ```tomo
DateTime.now(->DateTime) func now(->DateTime)
``` ```
**Parameters:** **Parameters:**
@ -362,7 +368,7 @@ None.
Returns a `DateTime` object representing the current date and time. Returns a `DateTime` object representing the current date and time.
**Example:** **Example:**
```markdown ```tomo
>> DateTime.now() >> DateTime.now()
= Sun Sep 29 20:22:48 2024 EDT = Sun Sep 29 20:22:48 2024 EDT
``` ```
@ -375,9 +381,9 @@ Returns a `DateTime` object representing the current date and time.
Return a new `DateTime` object parsed from the given string in the given format, Return a new `DateTime` object parsed from the given string in the given format,
or a null value if the value could not be successfully parsed. or a null value if the value could not be successfully parsed.
**Usage:** **Signature:**
```markdown ```tomo
DateTime.parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> DateTime?) func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> DateTime?)
``` ```
**Parameters:** **Parameters:**
@ -392,7 +398,7 @@ If the text was successfully parsed according to the given format, return a
`DateTime` representing that information. Otherwise, return a null value. `DateTime` representing that information. Otherwise, return a null value.
**Example:** **Example:**
```markdown ```tomo
>> DateTime.parse("2024-09-29", "%Y-%m-%d")! >> DateTime.parse("2024-09-29", "%Y-%m-%d")!
= Sun Sep 29 00:00:00 2024 EDT = Sun Sep 29 00:00:00 2024 EDT
@ -408,13 +414,14 @@ If the text was successfully parsed according to the given format, return a
Return a plain English textual representation of the approximate time difference Return a plain English textual representation of the approximate time difference
between two `DateTime`s. For example: `5 minutes ago` or `1 day later` between two `DateTime`s. For example: `5 minutes ago` or `1 day later`
**Usage:** **Signature:**
```markdown ```tomo
datetime:relative(relative_to : DateTime = DateTime.now(), timezone : Text? = !Text -> Text) func relative(datetime: DateTime, relative_to : DateTime = DateTime.now(), timezone : Text? = !Text -> Text)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime whose relative time you're getting.
- `relative_to` (optional): The time against which the relative time is calculated (default: `DateTime.now()`). - `relative_to` (optional): The time against which the relative time is calculated (default: `DateTime.now()`).
- `timezone` (optional): If specified, perform calculations in the given - `timezone` (optional): If specified, perform calculations in the given
timezone (otherwise, use the current local timezone). timezone (otherwise, use the current local timezone).
@ -428,7 +435,7 @@ represented as `2 days later`. Datetimes in the past will have the suffix `"
ago"`, while datetimes in the future will have the suffix `" later"`. ago"`, while datetimes in the future will have the suffix `" later"`.
**Example:** **Example:**
```markdown ```tomo
>> now():after(days=2):relative() >> now():after(days=2):relative()
= "2 days later" = "2 days later"
@ -443,20 +450,21 @@ ago"`, while datetimes in the future will have the suffix `" later"`.
**Description:** **Description:**
Return the number of seconds until a given datetime. Return the number of seconds until a given datetime.
**Usage:** **Signature:**
```markdown ```tomo
datetime:seconds_till(then:DateTime -> Num) func seconds_till(datetime: DateTime, then:DateTime -> Num)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in seconds). - `then`: Another datetime that we want to calculate the time offset from (in seconds).
**Returns:** **Returns:**
The number of seconds (possibly fractional, possibly negative) until the given time. The number of seconds (possibly fractional, possibly negative) until the given time.
**Example:** **Example:**
```markdown ```tomo
the_future := now():after(seconds=1) the_future := now():after(seconds=1)
>> now():seconds_till(the_future) >> now():seconds_till(the_future)
= 1 = 1
@ -473,9 +481,9 @@ timezone for performing calculations and constructing `DateTime` objects from
component parts. It's also used as the default way that `DateTime` objects are component parts. It's also used as the default way that `DateTime` objects are
converted to text. converted to text.
**Usage:** **Signature:**
```markdown ```tomo
DateTime.set_local_timezone(timezone : Text? = !Text -> Void) func set_local_timezone(timezone : Text? = !Text -> Void)
``` ```
**Parameters:** **Parameters:**
@ -488,7 +496,7 @@ DateTime.set_local_timezone(timezone : Text? = !Text -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
DateTime.set_local_timezone("America/Los_Angeles") DateTime.set_local_timezone("America/Los_Angeles")
``` ```
@ -499,13 +507,14 @@ DateTime.set_local_timezone("America/Los_Angeles")
**Description:** **Description:**
Return a text representation of the time component of the given datetime. Return a text representation of the time component of the given datetime.
**Usage:** **Signature:**
```markdown ```tomo
datetime:time(seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text) func time(datetime: DateTime, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)
``` ```
**Parameters:** **Parameters:**
- `datetime`: The datetime whose time value you want to get.
- `seconds`: Whether to include seconds in the time (default: `no`). - `seconds`: Whether to include seconds in the time (default: `no`).
- `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`). - `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`).
- `timezone` (optional): If specified, give the time in the given timezone (otherwise, use the current local timezone). - `timezone` (optional): If specified, give the time in the given timezone (otherwise, use the current local timezone).
@ -514,7 +523,7 @@ datetime:time(seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text
A text representation of the time component of the datetime. A text representation of the time component of the datetime.
**Example:** **Example:**
```markdown ```tomo
dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30) dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30)
>> dt:time() >> dt:time()
@ -535,20 +544,20 @@ dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30)
Get the UNIX timestamp of the given datetime (seconds since the UNIX epoch: Get the UNIX timestamp of the given datetime (seconds since the UNIX epoch:
January 1, 1970 UTC). January 1, 1970 UTC).
**Usage:** **Signature:**
```markdown ```tomo
datetime:unix_timestamp(->Int64) func unix_timestamp(datetime:DateTime->Int64)
``` ```
**Parameters:** **Parameters:**
None. `datetime`: The datetime whose UNIX timestamp you want to get.
**Returns:** **Returns:**
A 64-bit integer representation of the UNIX timestamp. A 64-bit integer representation of the UNIX timestamp.
**Example:** **Example:**
```markdown ```tomo
>> now():unix_timestamp() >> now():unix_timestamp()
= 1727654730[64] = 1727654730[64]
``` ```

48
docs/integers.md
View File

@ -35,9 +35,9 @@ can be called either on the type itself: `Int.sqrt(x)` or as a method call:
**Description:** **Description:**
Formats an integer as a string with a specified number of digits. Formats an integer as a string with a specified number of digits.
**Usage:** **Signature:**
```tomo ```tomo
format(i: Int, digits: Int = 0 -> Text) func format(i: Int, digits: Int = 0 -> Text)
``` ```
**Parameters:** **Parameters:**
@ -61,9 +61,9 @@ A string representation of the integer, padded to the specified number of digits
**Description:** **Description:**
Converts an integer to its hexadecimal representation. Converts an integer to its hexadecimal representation.
**Usage:** **Signature:**
```tomo ```tomo
hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text) func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)
``` ```
**Parameters:** **Parameters:**
@ -89,9 +89,9 @@ The hexadecimal string representation of the integer.
**Description:** **Description:**
Converts an integer to its octal representation. Converts an integer to its octal representation.
**Usage:** **Signature:**
```tomo ```tomo
octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text) func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)
``` ```
**Parameters:** **Parameters:**
@ -116,9 +116,9 @@ The octal string representation of the integer.
**Description:** **Description:**
Generates a random integer between the specified minimum and maximum values. Generates a random integer between the specified minimum and maximum values.
**Usage:** **Signature:**
```tomo ```tomo
random(min: Int, max: Int -> Int) func random(min: Int, max: Int -> Int)
``` ```
**Parameters:** **Parameters:**
@ -142,9 +142,9 @@ A random integer between `min` and `max` (inclusive).
**Description:** **Description:**
Converts a text representation of an integer into an integer. Converts a text representation of an integer into an integer.
**Usage:** **Signature:**
```tomo ```tomo
from_text(text: Text, success: Bool = !&Bool? -> Int) func from_text(text: Text, success: Bool = !&Bool? -> Int)
``` ```
**Parameters:** **Parameters:**
@ -186,9 +186,9 @@ success := no
**Description:** **Description:**
Creates an inclusive range of integers between the specified start and end values. Creates an inclusive range of integers between the specified start and end values.
**Usage:** **Signature:**
```tomo ```tomo
to(from: Int, to: Int -> Range) func to(from: Int, to: Int -> Range)
``` ```
**Parameters:** **Parameters:**
@ -212,9 +212,9 @@ A range object representing all integers from `from` to `to` (inclusive).
**Description:** **Description:**
Calculates the absolute value of an integer. Calculates the absolute value of an integer.
**Usage:** **Signature:**
```tomo ```tomo
abs(x: Int -> Int) func abs(x: Int -> Int)
``` ```
**Parameters:** **Parameters:**
@ -237,9 +237,9 @@ The absolute value of `x`.
**Description:** **Description:**
Calculates the square root of an integer. Calculates the square root of an integer.
**Usage:** **Signature:**
```tomo ```tomo
sqrt(x: Int -> Int) func sqrt(x: Int -> Int)
``` ```
**Parameters:** **Parameters:**
@ -270,9 +270,9 @@ getting an incorrect answer are astronomically small (on the order of 10^(-30)).
See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
for more details. for more details.
**Usage:** **Signature:**
```tomo ```tomo
is_prime(x: Int, reps: Int = 50 -> Bool) func is_prime(x: Int, reps: Int = 50 -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -304,9 +304,9 @@ answer are astronomically small (on the order of 10^(-30)).
See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
for more details. for more details.
**Usage:** **Signature:**
```tomo ```tomo
next_prime(x: Int -> Int) func next_prime(x: Int -> Int)
``` ```
**Parameters:** **Parameters:**
@ -337,9 +337,9 @@ answer are astronomically small (on the order of 10^(-30)).
See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
for more details. for more details.
**Usage:** **Signature:**
```tomo ```tomo
prev_prime(x: Int -> Int) func prev_prime(x: Int -> Int)
``` ```
**Parameters:** **Parameters:**
@ -363,9 +363,9 @@ The previous prime number less than `x`.
Returns the given number clamped between two values so that it is within Returns the given number clamped between two values so that it is within
that range. that range.
**Usage:** **Signature:**
```tomo ```tomo
clamped(x, low, high: Int -> Int) func clamped(x, low, high: Int -> Int)
``` ```
**Parameters:** **Parameters:**

206
docs/nums.md
View File

@ -40,9 +40,9 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
**Description:** **Description:**
Calculates the absolute value of a number. Calculates the absolute value of a number.
**Usage:** **Signature:**
```tomo ```tomo
abs(n: Num -> Num) func abs(n: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -65,9 +65,9 @@ The absolute value of `n`.
**Description:** **Description:**
Computes the arc cosine of a number. Computes the arc cosine of a number.
**Usage:** **Signature:**
```tomo ```tomo
acos(x: Num -> Num) func acos(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -90,9 +90,9 @@ The arc cosine of `x` in radians.
**Description:** **Description:**
Computes the inverse hyperbolic cosine of a number. Computes the inverse hyperbolic cosine of a number.
**Usage:** **Signature:**
```tomo ```tomo
acosh(x: Num -> Num) func acosh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -115,9 +115,9 @@ The inverse hyperbolic cosine of `x`.
**Description:** **Description:**
Computes the arc sine of a number. Computes the arc sine of a number.
**Usage:** **Signature:**
```tomo ```tomo
asin(x: Num -> Num) func asin(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -140,9 +140,9 @@ The arc sine of `x` in radians.
**Description:** **Description:**
Computes the inverse hyperbolic sine of a number. Computes the inverse hyperbolic sine of a number.
**Usage:** **Signature:**
```tomo ```tomo
asinh(x: Num -> Num) func asinh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -165,9 +165,9 @@ The inverse hyperbolic sine of `x`.
**Description:** **Description:**
Computes the arc tangent of the quotient of two numbers. Computes the arc tangent of the quotient of two numbers.
**Usage:** **Signature:**
```tomo ```tomo
atan2(x: Num, y: Num -> Num) func atan2(x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -191,9 +191,9 @@ The arc tangent of `x/y` in radians.
**Description:** **Description:**
Computes the arc tangent of a number. Computes the arc tangent of a number.
**Usage:** **Signature:**
```tomo ```tomo
atan(x: Num -> Num) func atan(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -216,9 +216,9 @@ The arc tangent of `x` in radians.
**Description:** **Description:**
Computes the inverse hyperbolic tangent of a number. Computes the inverse hyperbolic tangent of a number.
**Usage:** **Signature:**
```tomo ```tomo
atanh(x: Num -> Num) func atanh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -241,9 +241,9 @@ The inverse hyperbolic tangent of `x`.
**Description:** **Description:**
Computes the cube root of a number. Computes the cube root of a number.
**Usage:** **Signature:**
```tomo ```tomo
cbrt(x: Num -> Num) func cbrt(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -266,9 +266,9 @@ The cube root of `x`.
**Description:** **Description:**
Rounds a number up to the nearest integer. Rounds a number up to the nearest integer.
**Usage:** **Signature:**
```tomo ```tomo
ceil(x: Num -> Num) func ceil(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -291,9 +291,9 @@ The smallest integer greater than or equal to `x`.
**Description:** **Description:**
Copies the sign of one number to another. Copies the sign of one number to another.
**Usage:** **Signature:**
```tomo ```tomo
copysign(x: Num, y: Num -> Num) func copysign(x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -317,9 +317,9 @@ A number with the magnitude of `x` and the sign of `y`.
**Description:** **Description:**
Computes the cosine of a number (angle in radians). Computes the cosine of a number (angle in radians).
**Usage:** **Signature:**
```tomo ```tomo
cos(x: Num -> Num) func cos(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -342,9 +342,9 @@ The cosine of `x`.
**Description:** **Description:**
Computes the hyperbolic cosine of a number. Computes the hyperbolic cosine of a number.
**Usage:** **Signature:**
```tomo ```tomo
cosh(x: Num -> Num) func cosh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -367,9 +367,9 @@ The hyperbolic cosine of `x`.
**Description:** **Description:**
Computes the error function of a number. Computes the error function of a number.
**Usage:** **Signature:**
```tomo ```tomo
erf(x: Num -> Num) func erf(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -392,9 +392,9 @@ The error function of `x`.
**Description:** **Description:**
Computes the complementary error function of a number. Computes the complementary error function of a number.
**Usage:** **Signature:**
```tomo ```tomo
erfc(x: Num -> Num) func erfc(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -417,9 +417,9 @@ The complementary error function of `x`.
**Description:** **Description:**
Computes \( 2^x \) for a number. Computes \( 2^x \) for a number.
**Usage:** **Signature:**
```tomo ```tomo
exp2(x: Num -> Num) func exp2(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -442,9 +442,9 @@ The value of \( 2^x \).
**Description:** **Description:**
Computes the exponential function \( e^x \) for a number. Computes the exponential function \( e^x \) for a number.
**Usage:** **Signature:**
```tomo ```tomo
exp(x: Num -> Num) func exp(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -467,9 +467,9 @@ The value of \( e^x \).
**Description:** **Description:**
Computes \( e^x - 1 \) for a number. Computes \( e^x - 1 \) for a number.
**Usage:** **Signature:**
```tomo ```tomo
expm1(x: Num -> Num) func expm1(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -492,9 +492,9 @@ The value of \( e^x - 1 \).
**Description:** **Description:**
Computes the positive difference between two numbers. Computes the positive difference between two numbers.
**Usage:** **Signature:**
```tomo ```tomo
fdim(x: Num, y: Num -> Num) func fdim(x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -520,9 +520,9 @@ fd
**Description:** **Description:**
Rounds a number down to the nearest integer. Rounds a number down to the nearest integer.
**Usage:** **Signature:**
```tomo ```tomo
floor(x: Num -> Num) func floor(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -545,9 +545,9 @@ The largest integer less than or equal to `x`.
**Description:** **Description:**
Formats a number as a string with a specified precision. Formats a number as a string with a specified precision.
**Usage:** **Signature:**
```tomo ```tomo
format(n: Num, precision: Int = 0 -> Text) func format(n: Num, precision: Int = 0 -> Text)
``` ```
**Parameters:** **Parameters:**
@ -571,9 +571,9 @@ A string representation of the number with the specified precision.
**Description:** **Description:**
Converts a string representation of a number into a floating-point number. Converts a string representation of a number into a floating-point number.
**Usage:** **Signature:**
```tomo ```tomo
from_text(text: Text, the_rest: Text = "!&Text" -> Num) func from_text(text: Text, the_rest: Text = "!&Text" -> Num)
``` ```
**Parameters:** **Parameters:**
@ -599,9 +599,9 @@ The number represented by the string.
**Description:** **Description:**
Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers. Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
**Usage:** **Signature:**
```tomo ```tomo
hypot(x: Num, y: Num -> Num) func hypot(x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -625,9 +625,9 @@ The Euclidean norm of `x` and `y`.
**Description:** **Description:**
Checks if a number is finite. Checks if a number is finite.
**Usage:** **Signature:**
```tomo ```tomo
isfinite(n: Num -> Bool) func isfinite(n: Num -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -652,9 +652,9 @@ isfinite(n: Num -> Bool)
**Description:** **Description:**
Checks if a number is infinite. Checks if a number is infinite.
**Usage:** **Signature:**
```tomo ```tomo
isinf(n: Num -> Bool) func isinf(n: Num -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -679,9 +679,9 @@ isinf(n: Num -> Bool)
**Description:** **Description:**
Checks if a number is NaN (Not a Number). Checks if a number is NaN (Not a Number).
**Usage:** **Signature:**
```tomo ```tomo
isnan(n: Num -> Bool) func isnan(n: Num -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -706,9 +706,9 @@ isnan(n: Num -> Bool)
**Description:** **Description:**
Computes the Bessel function of the first kind of order 0. Computes the Bessel function of the first kind of order 0.
**Usage:** **Signature:**
```tomo ```tomo
j0(x: Num -> Num) func j0(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -731,9 +731,9 @@ The Bessel function of the first kind of order 0 of `x`.
**Description:** **Description:**
Computes the Bessel function of the first kind of order 1. Computes the Bessel function of the first kind of order 1.
**Usage:** **Signature:**
```tomo ```tomo
j1(x: Num -> Num) func j1(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -756,9 +756,9 @@ The Bessel function of the first kind of order 1 of `x`.
**Description:** **Description:**
Computes the base-10 logarithm of a number. Computes the base-10 logarithm of a number.
**Usage:** **Signature:**
```tomo ```tomo
log10(x: Num -> Num) func log10(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -781,9 +781,9 @@ The base-10 logarithm of `x`.
**Description:** **Description:**
Computes \( \log(1 + x) \) for a number. Computes \( \log(1 + x) \) for a number.
**Usage:** **Signature:**
```tomo ```tomo
log1p(x: Num -> Num) func log1p(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -806,9 +806,9 @@ The value of \( \log(1 + x) \).
**Description:** **Description:**
Computes the base-2 logarithm of a number. Computes the base-2 logarithm of a number.
**Usage:** **Signature:**
```tomo ```tomo
log2(x: Num -> Num) func log2(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -831,9 +831,9 @@ The base-2 logarithm of `x`.
**Description:** **Description:**
Computes the natural logarithm (base \( e \)) of a number. Computes the natural logarithm (base \( e \)) of a number.
**Usage:** **Signature:**
```tomo ```tomo
log(x: Num -> Num) func log(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -856,9 +856,9 @@ The natural logarithm of `x`.
**Description:** **Description:**
Computes the binary exponent (base-2 logarithm) of a number. Computes the binary exponent (base-2 logarithm) of a number.
**Usage:** **Signature:**
```tomo ```tomo
logb(x: Num -> Num) func logb(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -881,9 +881,9 @@ The binary exponent of `x`.
**Description:** **Description:**
Interpolates between two numbers based on a given amount. Interpolates between two numbers based on a given amount.
**Usage:** **Signature:**
```tomo ```tomo
mix(amount: Num, x: Num, y: Num -> Num) func mix(amount: Num, x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -910,9 +910,9 @@ The interpolated number between `x` and `y` based on `amount`.
**Description:** **Description:**
Generates a NaN (Not a Number) value. Generates a NaN (Not a Number) value.
**Usage:** **Signature:**
```tomo ```tomo
nan(tag: Text = "" -> Num) func nan(tag: Text = "" -> Num)
``` ```
**Parameters:** **Parameters:**
@ -937,9 +937,9 @@ Checks if two numbers are approximately equal within specified tolerances. If
two numbers are within an absolute difference or the ratio between the two is two numbers are within an absolute difference or the ratio between the two is
small enough, they are considered near each other. small enough, they are considered near each other.
**Usage:** **Signature:**
```tomo ```tomo
near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool) func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -971,9 +971,9 @@ near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
**Description:** **Description:**
Computes the next representable value after a given number towards a specified direction. Computes the next representable value after a given number towards a specified direction.
**Usage:** **Signature:**
```tomo ```tomo
nextafter(x: Num, y: Num -> Num) func nextafter(x: Num, y: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -997,9 +997,9 @@ The next representable value after `x` in the direction of `y`.
**Description:** **Description:**
Generates a random floating-point number. Generates a random floating-point number.
**Usage:** **Signature:**
```tomo ```tomo
random(->Num) func random(->Num)
``` ```
**Parameters:** **Parameters:**
@ -1021,9 +1021,9 @@ A random floating-point number between 0 and 1.
**Description:** **Description:**
Rounds a number to the nearest integer, with ties rounded to the nearest even integer. Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
**Usage:** **Signature:**
```tomo ```tomo
rint(x: Num -> Num) func rint(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1048,9 +1048,9 @@ The nearest integer value of `x`.
**Description:** **Description:**
Rounds a number to the nearest whole number integer. Rounds a number to the nearest whole number integer.
**Usage:** **Signature:**
```tomo ```tomo
round(x: Num -> Num) func round(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1075,9 +1075,9 @@ The nearest integer value of `x`.
**Description:** **Description:**
Formats a number in scientific notation with a specified precision. Formats a number in scientific notation with a specified precision.
**Usage:** **Signature:**
```tomo ```tomo
scientific(n: Num, precision: Int = 0 -> Text) func scientific(n: Num, precision: Int = 0 -> Text)
``` ```
**Parameters:** **Parameters:**
@ -1101,9 +1101,9 @@ A string representation of the number in scientific notation with the specified
**Description:** **Description:**
Extracts the significand (or mantissa) of a number. Extracts the significand (or mantissa) of a number.
**Usage:** **Signature:**
```tomo ```tomo
significand(x: Num -> Num) func significand(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1126,9 +1126,9 @@ The significand of `x`.
**Description:** **Description:**
Computes the sine of a number (angle in radians). Computes the sine of a number (angle in radians).
**Usage:** **Signature:**
```tomo ```tomo
sin(x: Num -> Num) func sin(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1151,9 +1151,9 @@ The sine of `x`.
**Description:** **Description:**
Computes the hyperbolic sine of a number. Computes the hyperbolic sine of a number.
**Usage:** **Signature:**
```tomo ```tomo
sinh(x: Num -> Num) func sinh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1176,9 +1176,9 @@ The hyperbolic sine of `x`.
**Description:** **Description:**
Computes the square root of a number. Computes the square root of a number.
**Usage:** **Signature:**
```tomo ```tomo
sqrt(x: Num -> Num) func sqrt(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1201,9 +1201,9 @@ The square root of `x`.
**Description:** **Description:**
Computes the tangent of a number (angle in radians). Computes the tangent of a number (angle in radians).
**Usage:** **Signature:**
```tomo ```tomo
tan(x: Num -> Num) func tan(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1226,9 +1226,9 @@ The tangent of `x`.
**Description:** **Description:**
Computes the hyperbolic tangent of a number. Computes the hyperbolic tangent of a number.
**Usage:** **Signature:**
```tomo ```tomo
tanh(x: Num -> Num) func tanh(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1251,9 +1251,9 @@ The hyperbolic tangent of `x`.
**Description:** **Description:**
Computes the gamma function of a number. Computes the gamma function of a number.
**Usage:** **Signature:**
```tomo ```tomo
tgamma(x: Num -> Num) func tgamma(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1276,9 +1276,9 @@ The gamma function of `x`.
**Description:** **Description:**
Truncates a number to the nearest integer towards zero. Truncates a number to the nearest integer towards zero.
**Usage:** **Signature:**
```tomo ```tomo
trunc(x: Num -> Num) func trunc(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1303,9 +1303,9 @@ The integer part of `x` towards zero.
**Description:** **Description:**
Computes the Bessel function of the second kind of order 0. Computes the Bessel function of the second kind of order 0.
**Usage:** **Signature:**
```tomo ```tomo
y0(x: Num -> Num) func y0(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1328,9 +1328,9 @@ The Bessel function of the second kind of order 0 of `x`.
**Description:** **Description:**
Computes the Bessel function of the second kind of order 1. Computes the Bessel function of the second kind of order 1.
**Usage:** **Signature:**
```tomo ```tomo
y1(x: Num -> Num) func y1(x: Num -> Num)
``` ```
**Parameters:** **Parameters:**
@ -1354,7 +1354,7 @@ The Bessel function of the second kind of order 1 of `x`.
Returns the given number clamped between two values so that it is within Returns the given number clamped between two values so that it is within
that range. that range.
**Usage:** **Signature:**
```tomo ```tomo
clamped(x, low, high: Num -> Num) clamped(x, low, high: Num -> Num)
``` ```

198
docs/paths.md
View File

@ -43,9 +43,9 @@ intended. Paths can be created from text with slashes using
Appends the given text to the file at the specified path, creating the file if Appends the given text to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error. it doesn't already exist. Failure to write will result in a runtime error.
**Usage:** **Signature:**
```markdown ```tomo
append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void) func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -58,7 +58,7 @@ append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./log.txt):append("extra line$(\n)") (./log.txt):append("extra line$(\n)")
``` ```
@ -70,9 +70,9 @@ Nothing.
Appends the given bytes to the file at the specified path, creating the file if Appends the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error. it doesn't already exist. Failure to write will result in a runtime error.
**Usage:** **Signature:**
```markdown ```tomo
append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void) func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -85,7 +85,7 @@ append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./log.txt):append_bytes([104[B], 105[B]]) (./log.txt):append_bytes([104[B], 105[B]])
``` ```
@ -96,9 +96,9 @@ Nothing.
**Description:** **Description:**
Returns the base name of the file or directory at the specified path. Returns the base name of the file or directory at the specified path.
**Usage:** **Signature:**
```markdown ```tomo
base_name(path: Path -> Text) func base_name(path: Path -> Text)
``` ```
**Parameters:** **Parameters:**
@ -109,7 +109,7 @@ base_name(path: Path -> Text)
The base name of the file or directory. The base name of the file or directory.
**Example:** **Example:**
```markdown ```tomo
>> (./path/to/file.txt):base_name() >> (./path/to/file.txt):base_name()
= "file.txt" = "file.txt"
``` ```
@ -122,9 +122,9 @@ The base name of the file or directory.
Returns an iterator that can be used to iterate over a file one line at a time, Returns an iterator that can be used to iterate over a file one line at a time,
or returns a null value if the file could not be opened. or returns a null value if the file could not be opened.
**Usage:** **Signature:**
```markdown ```tomo
by_line(path: Path -> func(->Text?)?) func by_line(path: Path -> func(->Text?)?)
``` ```
**Parameters:** **Parameters:**
@ -136,7 +136,7 @@ An iterator that can be used to get lines from a file one at a time or a null
value if the file couldn't be read. value if the file couldn't be read.
**Example:** **Example:**
```markdown ```tomo
# Safely handle file not being readable: # Safely handle file not being readable:
if lines := (./file.txt):by_line(): if lines := (./file.txt):by_line():
for line in lines: for line in lines:
@ -156,9 +156,9 @@ for line in (/dev/stdin):by_line()!:
**Description:** **Description:**
Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files.
**Usage:** **Signature:**
```markdown ```tomo
children(path: Path, include_hidden=no -> [Path]) func children(path: Path, include_hidden=no -> [Path])
``` ```
**Parameters:** **Parameters:**
@ -170,7 +170,7 @@ children(path: Path, include_hidden=no -> [Path])
A list of paths for the children. A list of paths for the children.
**Example:** **Example:**
```markdown ```tomo
>> (./directory):children(include_hidden=yes) >> (./directory):children(include_hidden=yes)
= [".git", "foo.txt"] = [".git", "foo.txt"]
``` ```
@ -183,9 +183,9 @@ A list of paths for the children.
Creates a new directory at the specified path with the given permissions. If Creates a new directory at the specified path with the given permissions. If
any of the parent directories do not exist, they will be created as needed. any of the parent directories do not exist, they will be created as needed.
**Usage:** **Signature:**
```markdown ```tomo
create_directory(path: Path, permissions=0o755[32] -> Void) func create_directory(path: Path, permissions=0o755[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -197,7 +197,7 @@ create_directory(path: Path, permissions=0o755[32] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./new_directory):create_directory() (./new_directory):create_directory()
``` ```
@ -208,9 +208,9 @@ Nothing.
**Description:** **Description:**
Checks if a file or directory exists at the specified path. Checks if a file or directory exists at the specified path.
**Usage:** **Signature:**
```markdown ```tomo
exists(path: Path -> Bool) func exists(path: Path -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -221,7 +221,7 @@ exists(path: Path -> Bool)
`True` if the file or directory exists, `False` otherwise. `True` if the file or directory exists, `False` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> (/):exists() >> (/):exists()
= yes = yes
``` ```
@ -233,9 +233,9 @@ exists(path: Path -> Bool)
**Description:** **Description:**
Returns the file extension of the file at the specified path. Optionally returns the full extension. Returns the file extension of the file at the specified path. Optionally returns the full extension.
**Usage:** **Signature:**
```markdown ```tomo
extension(path: Path, full=yes -> Text) func extension(path: Path, full=yes -> Text)
``` ```
**Parameters:** **Parameters:**
@ -249,7 +249,7 @@ The file extension (not including the leading `.`) or an empty text if there is
no file extension. no file extension.
**Example:** **Example:**
```markdown ```tomo
>> (./file.tar.gz):extension() >> (./file.tar.gz):extension()
= "tar.gz" = "tar.gz"
>> (./file.tar.gz):extension(full=no) >> (./file.tar.gz):extension(full=no)
@ -267,9 +267,9 @@ no file extension.
**Description:** **Description:**
Returns a list of files within the directory at the specified path. Optionally includes hidden files. Returns a list of files within the directory at the specified path. Optionally includes hidden files.
**Usage:** **Signature:**
```markdown ```tomo
files(path: Path, include_hidden=no -> [Path]) func files(path: Path, include_hidden=no -> [Path])
``` ```
**Parameters:** **Parameters:**
@ -281,7 +281,7 @@ files(path: Path, include_hidden=no -> [Path])
A list of file paths. A list of file paths.
**Example:** **Example:**
```markdown ```tomo
>> (./directory):files(include_hidden=yes) >> (./directory):files(include_hidden=yes)
= [(./directory/file1.txt), (./directory/file2.txt)] = [(./directory/file1.txt), (./directory/file2.txt)]
``` ```
@ -293,9 +293,9 @@ A list of file paths.
**Description:** **Description:**
Checks if the path represents a directory. Optionally follows symbolic links. Checks if the path represents a directory. Optionally follows symbolic links.
**Usage:** **Signature:**
```markdown ```tomo
is_directory(path: Path, follow_symlinks=yes -> Bool) func is_directory(path: Path, follow_symlinks=yes -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -307,7 +307,7 @@ is_directory(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a directory, `False` otherwise. `True` if the path is a directory, `False` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> (./directory/):is_directory() >> (./directory/):is_directory()
= yes = yes
@ -322,9 +322,9 @@ is_directory(path: Path, follow_symlinks=yes -> Bool)
**Description:** **Description:**
Checks if the path represents a file. Optionally follows symbolic links. Checks if the path represents a file. Optionally follows symbolic links.
**Usage:** **Signature:**
```markdown ```tomo
is_file(path: Path, follow_symlinks=yes -> Bool) func is_file(path: Path, follow_symlinks=yes -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -336,7 +336,7 @@ is_file(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a file, `False` otherwise. `True` if the path is a file, `False` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> (./file.txt):is_file() >> (./file.txt):is_file()
= yes = yes
@ -351,9 +351,9 @@ is_file(path: Path, follow_symlinks=yes -> Bool)
**Description:** **Description:**
Checks if the path represents a socket. Optionally follows symbolic links. Checks if the path represents a socket. Optionally follows symbolic links.
**Usage:** **Signature:**
```markdown ```tomo
is_socket(path: Path, follow_symlinks=yes -> Bool) func is_socket(path: Path, follow_symlinks=yes -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -365,7 +365,7 @@ is_socket(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a socket, `False` otherwise. `True` if the path is a socket, `False` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> (./socket):is_socket() >> (./socket):is_socket()
= yes = yes
``` ```
@ -377,9 +377,9 @@ is_socket(path: Path, follow_symlinks=yes -> Bool)
**Description:** **Description:**
Checks if the path represents a symbolic link. Checks if the path represents a symbolic link.
**Usage:** **Signature:**
```markdown ```tomo
is_symlink(path: Path -> Bool) func is_symlink(path: Path -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -390,7 +390,7 @@ is_symlink(path: Path -> Bool)
`True` if the path is a symbolic link, `False` otherwise. `True` if the path is a symbolic link, `False` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> (./link):is_symlink() >> (./link):is_symlink()
= yes = yes
``` ```
@ -402,9 +402,9 @@ is_symlink(path: Path -> Bool)
**Description:** **Description:**
Returns the parent directory of the file or directory at the specified path. Returns the parent directory of the file or directory at the specified path.
**Usage:** **Signature:**
```markdown ```tomo
parent(path: Path -> Path) func parent(path: Path -> Path)
``` ```
**Parameters:** **Parameters:**
@ -415,7 +415,7 @@ parent(path: Path -> Path)
The path of the parent directory. The path of the parent directory.
**Example:** **Example:**
```markdown ```tomo
>> (./path/to/file.txt):parent() >> (./path/to/file.txt):parent()
= (./path/to/) = (./path/to/)
``` ```
@ -428,9 +428,9 @@ The path of the parent directory.
Reads the contents of the file at the specified path or a null value if the Reads the contents of the file at the specified path or a null value if the
file could not be read. file could not be read.
**Usage:** **Signature:**
```markdown ```tomo
read(path: Path -> Text?) func read(path: Path -> Text?)
``` ```
**Parameters:** **Parameters:**
@ -443,7 +443,7 @@ returned. If the file can be read, but is not valid UTF8 data, an error will be
raised. raised.
**Example:** **Example:**
```markdown ```tomo
>> (./hello.txt):read() >> (./hello.txt):read()
= "Hello"? = "Hello"?
@ -458,9 +458,9 @@ raised.
Reads the contents of the file at the specified path or a null value if the Reads the contents of the file at the specified path or a null value if the
file could not be read. file could not be read.
**Usage:** **Signature:**
```markdown ```tomo
read_bytes(path: Path -> [Byte]?) func read_bytes(path: Path -> [Byte]?)
``` ```
**Parameters:** **Parameters:**
@ -472,7 +472,7 @@ The byte contents of the file. If the file cannot be read, a null value will be
returned. returned.
**Example:** **Example:**
```markdown ```tomo
>> (./hello.txt):read() >> (./hello.txt):read()
= [72[B], 101[B], 108[B], 108[B], 111[B]]? = [72[B], 101[B], 108[B], 108[B], 111[B]]?
@ -487,9 +487,9 @@ returned.
**Description:** **Description:**
Returns the path relative to a given base path. By default, the base path is the current directory. Returns the path relative to a given base path. By default, the base path is the current directory.
**Usage:** **Signature:**
```markdown ```tomo
relative(path: Path, relative_to=(./) -> Path) func relative(path: Path, relative_to=(./) -> Path)
``` ```
**Parameters:** **Parameters:**
@ -501,7 +501,7 @@ relative(path: Path, relative_to=(./) -> Path)
The relative path. The relative path.
**Example:** **Example:**
```markdown ```tomo
>> (./path/to/file.txt):relative(relative_to=(./path)) >> (./path/to/file.txt):relative(relative_to=(./path))
= (./to/file.txt) = (./to/file.txt)
``` ```
@ -513,9 +513,9 @@ The relative path.
**Description:** **Description:**
Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
**Usage:** **Signature:**
```markdown ```tomo
remove(path: Path, ignore_missing=no -> Void) func remove(path: Path, ignore_missing=no -> Void)
``` ```
**Parameters:** **Parameters:**
@ -527,7 +527,7 @@ remove(path: Path, ignore_missing=no -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./file.txt):remove() (./file.txt):remove()
``` ```
@ -538,9 +538,9 @@ Nothing.
**Description:** **Description:**
Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
**Usage:** **Signature:**
```markdown ```tomo
resolved(path: Path, relative_to=(./) -> Path) func resolved(path: Path, relative_to=(./) -> Path)
``` ```
**Parameters:** **Parameters:**
@ -552,7 +552,7 @@ resolved(path: Path, relative_to=(./) -> Path)
The resolved absolute path. The resolved absolute path.
**Example:** **Example:**
```markdown ```tomo
>> (~/foo):resolved() >> (~/foo):resolved()
= (/home/user/foo) = (/home/user/foo)
@ -567,9 +567,9 @@ The resolved absolute path.
**Description:** **Description:**
Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
**Usage:** **Signature:**
```markdown ```tomo
subdirectories(path: Path, include_hidden=no -> [Path]) func subdirectories(path: Path, include_hidden=no -> [Path])
``` ```
**Parameters:** **Parameters:**
@ -581,7 +581,7 @@ subdirectories(path: Path, include_hidden=no -> [Path])
A list of subdirectory paths. A list of subdirectory paths.
**Example:** **Example:**
```markdown ```tomo
>> (./directory):subdirectories() >> (./directory):subdirectories()
= [(./directory/subdir1), (./directory/subdir2)] = [(./directory/subdir1), (./directory/subdir2)]
@ -596,9 +596,9 @@ A list of subdirectory paths.
**Description:** **Description:**
Generates a unique directory path based on the given path. Useful for creating temporary directories. Generates a unique directory path based on the given path. Useful for creating temporary directories.
**Usage:** **Signature:**
```markdown ```tomo
unique_directory(path: Path -> Path) func unique_directory(path: Path -> Path)
``` ```
**Parameters:** **Parameters:**
@ -627,9 +627,9 @@ Writes the given text to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised. writing cannot be successfully completed, a runtime error is raised.
**Usage:** **Signature:**
```markdown ```tomo
write(path: Path, text: Text, permissions=0o644[32] -> Void) func write(path: Path, text: Text, permissions=0o644[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -642,7 +642,7 @@ write(path: Path, text: Text, permissions=0o644[32] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./file.txt):write("Hello, world!") (./file.txt):write("Hello, world!")
``` ```
@ -655,9 +655,9 @@ Writes the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised. writing cannot be successfully completed, a runtime error is raised.
**Usage:** **Signature:**
```markdown ```tomo
write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void) func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -670,7 +670,7 @@ write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
(./file.txt):write_bytes([104[B], 105[B]]) (./file.txt):write_bytes([104[B], 105[B]])
``` ```
@ -683,9 +683,9 @@ Writes the given text to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary file is created if it doesn't exist. This is useful for creating temporary
files. files.
**Usage:** **Signature:**
```markdown ```tomo
write_unique(path: Path, text: Text -> Path) func write_unique(path: Path, text: Text -> Path)
``` ```
**Parameters:** **Parameters:**
@ -698,7 +698,7 @@ write_unique(path: Path, text: Text -> Path)
The path of the newly created unique file. The path of the newly created unique file.
**Example:** **Example:**
```markdown ```tomo
>> created := (./file-XXXXXX.txt):write_unique("Hello, world!") >> created := (./file-XXXXXX.txt):write_unique("Hello, world!")
= (./file-27QHtq.txt) = (./file-27QHtq.txt)
>> created:read() >> created:read()
@ -715,9 +715,9 @@ Writes the given bytes to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary file is created if it doesn't exist. This is useful for creating temporary
files. files.
**Usage:** **Signature:**
```markdown ```tomo
write_unique_bytes(path: Path, bytes: [Byte] -> Path) func write_unique_bytes(path: Path, bytes: [Byte] -> Path)
``` ```
**Parameters:** **Parameters:**
@ -730,7 +730,7 @@ write_unique_bytes(path: Path, bytes: [Byte] -> Path)
The path of the newly created unique file. The path of the newly created unique file.
**Example:** **Example:**
```markdown ```tomo
>> created := (./file-XXXXXX.txt):write_unique_bytes([1[B], 2[B], 3[B]]) >> created := (./file-XXXXXX.txt):write_unique_bytes([1[B], 2[B], 3[B]])
= (./file-27QHtq.txt) = (./file-27QHtq.txt)
>> created:read() >> created:read()

8
docs/ranges.md
View File

@ -18,9 +18,9 @@ created using the `Int.to()` method like so: `5:to(10)`. Ranges are
**Description:** **Description:**
Returns a reversed copy of the range. Returns a reversed copy of the range.
**Usage:** **Signature:**
```tomo ```tomo
reversed(range: Range -> Range) func reversed(range: Range -> Range)
``` ```
**Parameters:** **Parameters:**
@ -43,9 +43,9 @@ A new `Range` with the order of elements reversed.
**Description:** **Description:**
Creates a new range with a specified step value. Creates a new range with a specified step value.
**Usage:** **Signature:**
```tomo ```tomo
by(range: Range, step: Int -> Range) func by(range: Range, step: Int -> Range)
``` ```
**Parameters:** **Parameters:**

44
docs/sets.md
View File

@ -80,9 +80,9 @@ iterating over any of the new values.
**Description:** **Description:**
Checks if the set contains a specified item. Checks if the set contains a specified item.
**Usage:** **Signature:**
```tomo ```tomo
has(set:{T}, item:T -> Bool) func has(set:{T}, item:T -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -106,9 +106,9 @@ has(set:{T}, item:T -> Bool)
**Description:** **Description:**
Adds an item to the set. Adds an item to the set.
**Usage:** **Signature:**
```tomo ```tomo
add(set:{T}, item: T -> Void) func add(set:{T}, item: T -> Void)
``` ```
**Parameters:** **Parameters:**
@ -131,9 +131,9 @@ Nothing.
**Description:** **Description:**
Adds multiple items to the set. Adds multiple items to the set.
**Usage:** **Signature:**
```tomo ```tomo
add_all(set:&{T}, items: [T] -> Void) func add_all(set:&{T}, items: [T] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -156,9 +156,9 @@ Nothing.
**Description:** **Description:**
Removes an item from the set. Removes an item from the set.
**Usage:** **Signature:**
```tomo ```tomo
remove(set:&{T}, item: T -> Void) func remove(set:&{T}, item: T -> Void)
``` ```
**Parameters:** **Parameters:**
@ -181,9 +181,9 @@ Nothing.
**Description:** **Description:**
Removes multiple items from the set. Removes multiple items from the set.
**Usage:** **Signature:**
```tomo ```tomo
remove_all(set:&{T}, items: [T] -> Void) func remove_all(set:&{T}, items: [T] -> Void)
``` ```
**Parameters:** **Parameters:**
@ -206,9 +206,9 @@ Nothing.
**Description:** **Description:**
Removes all items from the set. Removes all items from the set.
**Usage:** **Signature:**
```tomo ```tomo
clear(set:&{T} -> Void) func clear(set:&{T} -> Void)
``` ```
**Parameters:** **Parameters:**
@ -230,9 +230,9 @@ Nothing.
**Description:** **Description:**
Creates a new set that is the union of the original set and another set. Creates a new set that is the union of the original set and another set.
**Usage:** **Signature:**
```tomo ```tomo
with(set:{T}, other: {T} -> {T}) func with(set:{T}, other: {T} -> {T})
``` ```
**Parameters:** **Parameters:**
@ -256,9 +256,9 @@ A new set containing all items from both sets.
**Description:** **Description:**
Creates a new set with items that are in both the original set and another set. Creates a new set with items that are in both the original set and another set.
**Usage:** **Signature:**
```tomo ```tomo
overlap(set:{T}, other: {T} -> {T}) func overlap(set:{T}, other: {T} -> {T})
``` ```
**Parameters:** **Parameters:**
@ -282,9 +282,9 @@ A new set containing only items present in both sets.
**Description:** **Description:**
Creates a new set with items from the original set but without items from another set. Creates a new set with items from the original set but without items from another set.
**Usage:** **Signature:**
```tomo ```tomo
without(set:{T}, other: {T} -> {T}) func without(set:{T}, other: {T} -> {T})
``` ```
**Parameters:** **Parameters:**
@ -308,9 +308,9 @@ A new set containing items from the original set excluding those in the other se
**Description:** **Description:**
Checks if the set is a subset of another set. Checks if the set is a subset of another set.
**Usage:** **Signature:**
```tomo ```tomo
set:is_subset_of(other: {T}, strict: Bool = no -> Bool) func (set: {T}, other: {T}, strict: Bool = no -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -335,9 +335,9 @@ set:is_subset_of(other: {T}, strict: Bool = no -> Bool)
**Description:** **Description:**
Checks if the set is a superset of another set. Checks if the set is a superset of another set.
**Usage:** **Signature:**
```tomo ```tomo
is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool) func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
``` ```
**Parameters:** **Parameters:**

56
docs/tables.md
View File

@ -116,14 +116,14 @@ iterating over any of the new values.
Increments the value associated with a key by a specified amount. If the key is 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. not already in the table, its value will be assumed to be zero.
**Usage:** **Signature:**
```markdown ```tomo
bump(t:{K:V}, key: K, amount: Int = 1 -> Void) func bump(t:&{K:V}, key: K, amount: Int = 1 -> Void)
``` ```
**Parameters:** **Parameters:**
- `t`: The mutable reference to the table. - `t`: The reference to the table.
- `key`: The key whose value is to be incremented. - `key`: The key whose value is to be incremented.
- `amount`: The amount to increment the value by (default: 1). - `amount`: The amount to increment the value by (default: 1).
@ -131,7 +131,7 @@ bump(t:{K:V}, key: K, amount: Int = 1 -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> t := {"A":1} >> t := {"A":1}
t:bump("A") t:bump("A")
t:bump("B", 10) t:bump("B", 10)
@ -146,20 +146,20 @@ t:bump("B", 10)
**Description:** **Description:**
Removes all key-value pairs from the table. Removes all key-value pairs from the table.
**Usage:** **Signature:**
```markdown ```tomo
t:clear() func clear(t:&{K:V})
``` ```
**Parameters:** **Parameters:**
- `t`: The mutable reference to the table. - `t`: The reference to the table.
**Returns:** **Returns:**
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
>> t:clear() >> t:clear()
``` ```
@ -170,9 +170,9 @@ Nothing.
**Description:** **Description:**
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 null if the key is not present.
**Usage:** **Signature:**
```markdown ```tomo
t:get(key: K -> V?) func get(t:{K:V}, key: K -> V?)
``` ```
**Parameters:** **Parameters:**
@ -184,7 +184,7 @@ t:get(key: K -> V?)
The value associated with the key or null if the key is not found. The value associated with the key or null if the key is not found.
**Example:** **Example:**
```markdown ```tomo
>> t := {"A":1, "B":2} >> t := {"A":1, "B":2}
>> t:get("A") >> t:get("A")
= 1? : Int? = 1? : Int?
@ -206,9 +206,9 @@ The value associated with the key or null if the key is not found.
**Description:** **Description:**
Checks if the table contains a specified key. Checks if the table contains a specified key.
**Usage:** **Signature:**
```markdown ```tomo
has(t:{K:V}, key: K -> Bool) func has(t:{K:V}, key: K -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -220,7 +220,7 @@ has(t:{K:V}, key: K -> Bool)
`yes` if the key is present, `no` otherwise. `yes` if the key is present, `no` otherwise.
**Example:** **Example:**
```markdown ```tomo
>> {"A":1, "B":2}:has("A") >> {"A":1, "B":2}:has("A")
= yes = yes
>> {"A":1, "B":2}:has("xxx") >> {"A":1, "B":2}:has("xxx")
@ -234,21 +234,21 @@ has(t:{K:V}, key: K -> Bool)
**Description:** **Description:**
Removes the key-value pair associated with a specified key. Removes the key-value pair associated with a specified key.
**Usage:** **Signature:**
```markdown ```tomo
remove(t:{K:V}, key: K -> Void) func remove(t:{K:V}, key: K -> Void)
``` ```
**Parameters:** **Parameters:**
- `t`: The mutable reference to the table. - `t`: The reference to the table.
- `key`: The key of the key-value pair to remove. - `key`: The key of the key-value pair to remove.
**Returns:** **Returns:**
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
t := {"A":1, "B":2} t := {"A":1, "B":2}
t:remove("A") t:remove("A")
>> t >> t
@ -262,14 +262,14 @@ t:remove("A")
**Description:** **Description:**
Sets or updates the value associated with a specified key. Sets or updates the value associated with a specified key.
**Usage:** **Signature:**
```markdown ```tomo
set(t:{K:V}, key: K, value: V -> Void) func set(t:{K:V}, key: K, value: V -> Void)
``` ```
**Parameters:** **Parameters:**
- `t`: The mutable reference to the table. - `t`: The reference to the table.
- `key`: The key to set or update. - `key`: The key to set or update.
- `value`: The value to associate with the key. - `value`: The value to associate with the key.
@ -277,7 +277,7 @@ set(t:{K:V}, key: K, value: V -> Void)
Nothing. Nothing.
**Example:** **Example:**
```markdown ```tomo
t := {"A": 1, "B": 2} t := {"A": 1, "B": 2}
t:set("C", 3) t:set("C", 3)
>> t >> t

104
docs/text.md
View File

@ -400,9 +400,9 @@ many repetitions you want by putting a number or range of numbers first using
**Description:** **Description:**
Converts a `Text` value to a C-style string. Converts a `Text` value to a C-style string.
**Usage:** **Signature:**
```tomo ```tomo
as_c_string(text: Text -> CString) func as_c_string(text: Text -> CString)
``` ```
**Parameters:** **Parameters:**
@ -426,9 +426,9 @@ A C-style string (`CString`) representing the text.
Converts a `Text` value to an array of bytes representing a UTF8 encoding of Converts a `Text` value to an array of bytes representing a UTF8 encoding of
the text. the text.
**Usage:** **Signature:**
```tomo ```tomo
utf8_bytes(text: Text -> [Byte]) func utf8_bytes(text: Text -> [Byte])
``` ```
**Parameters:** **Parameters:**
@ -451,9 +451,9 @@ An array of bytes (`[Byte]`) representing the text in UTF8 encoding.
**Description:** **Description:**
Returns an array of the names of each codepoint in the text. Returns an array of the names of each codepoint in the text.
**Usage:** **Signature:**
```tomo ```tomo
codepoint_names(text: Text -> [Text]) func codepoint_names(text: Text -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -476,9 +476,9 @@ An array of codepoint names (`[Text]`).
**Description:** **Description:**
Returns an array of Unicode code points for UTF32 encoding of the text. Returns an array of Unicode code points for UTF32 encoding of the text.
**Usage:** **Signature:**
```tomo ```tomo
utf32_codepoints(text: Text -> [Int32]) func utf32_codepoints(text: Text -> [Int32])
``` ```
**Parameters:** **Parameters:**
@ -501,9 +501,9 @@ An array of 32-bit integer Unicode code points (`[Int32]`).
**Description:** **Description:**
Checks if the `Text` ends with a literal suffix text. Checks if the `Text` ends with a literal suffix text.
**Usage:** **Signature:**
```tomo ```tomo
ends_with(text: Text, suffix: Text -> Bool) func ends_with(text: Text, suffix: Text -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -527,9 +527,9 @@ ends_with(text: Text, suffix: Text -> Bool)
**Description:** **Description:**
Converts a C-style string to a `Text` value. Converts a C-style string to a `Text` value.
**Usage:** **Signature:**
```tomo ```tomo
from_c_string(str: CString -> Text) func from_c_string(str: CString -> Text)
``` ```
**Parameters:** **Parameters:**
@ -554,9 +554,9 @@ Returns text that has the given codepoint names (according to the Unicode
specification) as its codepoints. Note: the text will be normalized, so the specification) as its codepoints. Note: the text will be normalized, so the
resulting text's codepoints may not exactly match the input codepoints. resulting text's codepoints may not exactly match the input codepoints.
**Usage:** **Signature:**
```tomo ```tomo
from_codepoint_names(codepoint_names: [Text] -> [Text]) func from_codepoint_names(codepoint_names: [Text] -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -587,9 +587,9 @@ Returns text that has been constructed from the given UTF32 codepoints. Note:
the text will be normalized, so the resulting text's codepoints may not exactly the text will be normalized, so the resulting text's codepoints may not exactly
match the input codepoints. match the input codepoints.
**Usage:** **Signature:**
```tomo ```tomo
from_codepoint_names(codepoints: [Int32] -> [Text]) func from_codepoint_names(codepoints: [Int32] -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -614,9 +614,9 @@ Returns text that has been constructed from the given UTF8 bytes. Note: the
text will be normalized, so the resulting text's UTF8 bytes may not exactly text will be normalized, so the resulting text's UTF8 bytes may not exactly
match the input. match the input.
**Usage:** **Signature:**
```tomo ```tomo
from_codepoint_names(codepoints: [Int32] -> [Text]) func from_codepoint_names(codepoints: [Int32] -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -640,9 +640,9 @@ A new text based on the input UTF8 bytes after normalization has been applied.
Finds the first occurrence of a pattern in the given text (if any). Finds the first occurrence of a pattern in the given text (if any).
See: [Patterns](#Patterns) for more information on patterns. See: [Patterns](#Patterns) for more information on patterns.
**Usage:** **Signature:**
```tomo ```tomo
find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int64 -> Int) func find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int64 -> Int)
``` ```
**Parameters:** **Parameters:**
@ -683,9 +683,9 @@ found.
Finds all occurrences of a pattern in the given text. Finds all occurrences of a pattern in the given text.
See: [Patterns](#Patterns) for more information on patterns. See: [Patterns](#Patterns) for more information on patterns.
**Usage:** **Signature:**
```tomo ```tomo
find_all(text: Text, pattern: Pattern -> [Text]) func find_all(text: Text, pattern: Pattern -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -725,9 +725,9 @@ Note: if `text` or `pattern` is empty, an empty array will be returned.
**Description:** **Description:**
Checks if the `Text` contains a target pattern (see: [Patterns](#Patterns)). Checks if the `Text` contains a target pattern (see: [Patterns](#Patterns)).
**Usage:** **Signature:**
```tomo ```tomo
has(text: Text, pattern: Pattern -> Bool) func has(text: Text, pattern: Pattern -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -757,9 +757,9 @@ has(text: Text, pattern: Pattern -> Bool)
**Description:** **Description:**
Joins an array of text pieces with a specified glue. Joins an array of text pieces with a specified glue.
**Usage:** **Signature:**
```tomo ```tomo
join(glue: Text, pieces: [Text] -> Text) func join(glue: Text, pieces: [Text] -> Text)
``` ```
**Parameters:** **Parameters:**
@ -784,9 +784,9 @@ A single `Text` value with the pieces joined by the glue.
Splits the text into an array of lines of text, preserving blank lines, Splits the text into an array of lines of text, preserving blank lines,
ignoring trailing newlines, and handling `\r\n` the same as `\n`. ignoring trailing newlines, and handling `\r\n` the same as `\n`.
**Usage:** **Signature:**
```tomo ```tomo
split(text: Text -> [Text]) func split(text: Text -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -817,9 +817,9 @@ An array of substrings resulting from the split.
**Description:** **Description:**
Converts all characters in the text to lowercase. Converts all characters in the text to lowercase.
**Usage:** **Signature:**
```tomo ```tomo
lower(text: Text -> Text) func lower(text: Text -> Text)
``` ```
**Parameters:** **Parameters:**
@ -844,9 +844,9 @@ Checks if the `Text` matches target pattern (see: [Patterns](#Patterns)) and
returns an array of the matching texts or a null value if the entire text returns an array of the matching texts or a null value if the entire text
doesn't match the pattern. doesn't match the pattern.
**Usage:** **Signature:**
```tomo ```tomo
matches(text: Text, pattern: Pattern -> [Text]) func matches(text: Text, pattern: Pattern -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -875,9 +875,9 @@ a null value otherwise.
For each occurrence of the given pattern, replace the text with the result of For each occurrence of the given pattern, replace the text with the result of
calling the given function on that text. calling the given function on that text.
**Usage:** **Signature:**
```tomo ```tomo
map(text: Text, pattern: Pattern, fn: func(text:Text)->Text -> Text) func map(text: Text, pattern: Pattern, fn: func(text:Text)->Text -> Text)
``` ```
**Parameters:** **Parameters:**
@ -905,9 +905,9 @@ function to each.
**Description:** **Description:**
Formats the text as a quoted string. Formats the text as a quoted string.
**Usage:** **Signature:**
```tomo ```tomo
quoted(text: Text, color: Bool = no -> Text) func quoted(text: Text, color: Bool = no -> Text)
``` ```
**Parameters:** **Parameters:**
@ -931,9 +931,9 @@ The text formatted as a quoted string.
**Description:** **Description:**
Repeat some text multiple times. Repeat some text multiple times.
**Usage:** **Signature:**
```tomo ```tomo
repeat(text: Text, count:Int -> Text) func repeat(text: Text, count:Int -> Text)
``` ```
**Parameters:** **Parameters:**
@ -959,9 +959,9 @@ Replaces occurrences of a pattern in the text with a replacement string.
See [Patterns](#patterns) for more information about patterns. See [Patterns](#patterns) for more information about patterns.
**Usage:** **Signature:**
```tomo ```tomo
replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text) func replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)
``` ```
**Parameters:** **Parameters:**
@ -1028,9 +1028,9 @@ matching pattern's replacement is applied and the pattern matching moves on to
*after* the replacement text, so replacement text is not recursively modified. *after* the replacement text, so replacement text is not recursively modified.
See [`replace()`](#replace) for more information about replacement behavior. See [`replace()`](#replace) for more information about replacement behavior.
**Usage:** **Signature:**
```tomo ```tomo
replace_all(replacements:{Pattern:Text}, backref: Pattern = $/\/ -> Text) func replace_all(replacements:{Pattern:Text}, backref: Pattern = $/\/ -> Text)
``` ```
**Parameters:** **Parameters:**
@ -1073,9 +1073,9 @@ replacement text.
Splits the text into an array of substrings based on a pattern. Splits the text into an array of substrings based on a pattern.
See [Patterns](#patterns) for more information about patterns. See [Patterns](#patterns) for more information about patterns.
**Usage:** **Signature:**
```tomo ```tomo
split(text: Text, pattern: Pattern = "" -> [Text]) func split(text: Text, pattern: Pattern = "" -> [Text])
``` ```
**Parameters:** **Parameters:**
@ -1109,9 +1109,9 @@ An array of substrings resulting from the split.
**Description:** **Description:**
Checks if the `Text` starts with a literal prefix text. Checks if the `Text` starts with a literal prefix text.
**Usage:** **Signature:**
```tomo ```tomo
starts_with(text: Text, prefix: Text -> Bool) func starts_with(text: Text, prefix: Text -> Bool)
``` ```
**Parameters:** **Parameters:**
@ -1135,9 +1135,9 @@ starts_with(text: Text, prefix: Text -> Bool)
**Description:** **Description:**
Converts the text to title case (capitalizing the first letter of each word). Converts the text to title case (capitalizing the first letter of each word).
**Usage:** **Signature:**
```tomo ```tomo
title(text: Text -> Text) func title(text: Text -> Text)
``` ```
**Parameters:** **Parameters:**
@ -1161,9 +1161,9 @@ The text in title case.
Trims the matching pattern from the left and/or right side of the text Trims the matching pattern from the left and/or right side of the text
See [Patterns](#patterns) for more information about patterns. See [Patterns](#patterns) for more information about patterns.
**Usage:** **Signature:**
```tomo ```tomo
trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text) func trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)
``` ```
**Parameters:** **Parameters:**
@ -1195,9 +1195,9 @@ The text without the trim pattern at either end.
**Description:** **Description:**
Converts all characters in the text to uppercase. Converts all characters in the text to uppercase.
**Usage:** **Signature:**
```tomo ```tomo
upper(text: Text -> Text) func upper(text: Text -> Text)
``` ```
**Parameters:** **Parameters:**

16
docs/threads.md
View File

@ -11,9 +11,9 @@ through thread-safe Channels with no other shared data.
**Description:** **Description:**
Creates a new thread to execute a specified function. Creates a new thread to execute a specified function.
**Usage:** **Signature:**
```tomo ```tomo
Thread.new(fn: func(->Void) -> Thread) func new(fn: func(->Void) -> Thread)
``` ```
**Parameters:** **Parameters:**
@ -45,9 +45,9 @@ A new `Thread` object representing the created thread.
**Description:** **Description:**
Requests the cancellation of a specified thread. Requests the cancellation of a specified thread.
**Usage:** **Signature:**
```tomo ```tomo
cancel(thread: Thread) func cancel(thread: Thread)
``` ```
**Parameters:** **Parameters:**
@ -69,9 +69,9 @@ Nothing.
**Description:** **Description:**
Waits for a specified thread to terminate. Waits for a specified thread to terminate.
**Usage:** **Signature:**
```tomo ```tomo
join(thread: Thread) func join(thread: Thread)
``` ```
**Parameters:** **Parameters:**
@ -93,9 +93,9 @@ Nothing.
**Description:** **Description:**
Detaches a specified thread, allowing it to run independently. Detaches a specified thread, allowing it to run independently.
**Usage:** **Signature:**
```tomo ```tomo
detach(thread: Thread) func detach(thread: Thread)
``` ```
**Parameters:** **Parameters:**