From 83e6cc9197bd8e7a19834d291fe4c5e62639db38 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 22 Dec 2025 16:32:40 -0500 Subject: Add Path.writer() and Path.byte_writer() --- api/api.md | 52 ++++++++++++++++++++++++++++++++++++++++ api/paths.md | 52 ++++++++++++++++++++++++++++++++++++++++ api/paths.yaml | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 180 insertions(+) (limited to 'api') diff --git a/api/api.md b/api/api.md index 2be5e4e9..d035a3fe 100644 --- a/api/api.md +++ b/api/api.md @@ -2645,6 +2645,32 @@ else for line in (/dev/stdin).by_line()! say(line.upper()) +``` +## Path.byte_writer + +```tomo +Path.byte_writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(bytes:[Byte], close:Bool=no -> Result)) +``` + +Returns a function that can be used to repeatedly write bytes to the same file. + +The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | - +append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no` +permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)` + +**Return:** Returns a function that can repeatedly write bytes to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending. + + +**Example:** +```tomo +write := (./file.txt).byte_writer() +write("Hello\n".utf8())! +write("world\n".utf8(), close=yes)! + ``` ## Path.can_execute @@ -3463,6 +3489,32 @@ assert created == (./file-27QHtq.txt) assert created.read() == [1, 2, 3] created.remove() +``` +## Path.writer + +```tomo +Path.writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(text:Text, close:Bool=no -> Result)) +``` + +Returns a function that can be used to repeatedly write to the same file. + +The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | - +append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no` +permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)` + +**Return:** Returns a function that can repeatedly write to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending. + + +**Example:** +```tomo +write := (./file.txt).writer() +write("Hello\n")! +write("world\n", close=yes)! + ``` # Table diff --git a/api/paths.md b/api/paths.md index 435932e3..8c08b45b 100644 --- a/api/paths.md +++ b/api/paths.md @@ -117,6 +117,32 @@ else for line in (/dev/stdin).by_line()! say(line.upper()) +``` +## Path.byte_writer + +```tomo +Path.byte_writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(bytes:[Byte], close:Bool=no -> Result)) +``` + +Returns a function that can be used to repeatedly write bytes to the same file. + +The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | - +append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no` +permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)` + +**Return:** Returns a function that can repeatedly write bytes to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending. + + +**Example:** +```tomo +write := (./file.txt).byte_writer() +write("Hello\n".utf8())! +write("world\n".utf8(), close=yes)! + ``` ## Path.can_execute @@ -936,3 +962,29 @@ assert created.read() == [1, 2, 3] created.remove() ``` +## Path.writer + +```tomo +Path.writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(text:Text, close:Bool=no -> Result)) +``` + +Returns a function that can be used to repeatedly write to the same file. + +The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | - +append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no` +permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)` + +**Return:** Returns a function that can repeatedly write to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending. + + +**Example:** +```tomo +write := (./file.txt).writer() +write("Hello\n")! +write("world\n", close=yes)! + +``` diff --git a/api/paths.yaml b/api/paths.yaml index 02b8fbe8..a659ffbc 100644 --- a/api/paths.yaml +++ b/api/paths.yaml @@ -838,6 +838,82 @@ Path.write: example: | (./file.txt).write("Hello, world!") +Path.writer: + short: create a file writer + description: > + Returns a function that can be used to repeatedly write to the same file. + note: > + The file writer will keep its file descriptor open after each write (unless + the `close` argument is set to `yes`). If the file writer is never closed, + it will be automatically closed when the file writer is garbage collected. + return: + type: 'func(text:Text, close:Bool=no -> Result)' + description: > + Returns a function that can repeatedly write to the same file. If `close` + is set to `yes`, then the file will be closed after writing. If this + function is called again after closing, the file will be reopened for + appending. + args: + path: + type: 'Path' + description: > + The path of the file to write to. + append: + type: 'Bool' + default: 'no' + description: > + If set to `yes`, writes to the file will append. If set to `no`, then + the first write to the file will overwrite its contents and subsequent + calls will append. + permissions: + type: 'Int32' + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is created. + example: | + write := (./file.txt).writer() + write("Hello\n")! + write("world\n", close=yes)! + +Path.byte_writer: + short: create a byte-based file writer + description: > + Returns a function that can be used to repeatedly write bytes to the same + file. + note: > + The file writer will keep its file descriptor open after each write (unless + the `close` argument is set to `yes`). If the file writer is never closed, + it will be automatically closed when the file writer is garbage collected. + return: + type: 'func(bytes:[Byte], close:Bool=no -> Result)' + description: > + Returns a function that can repeatedly write bytes to the same file. If + `close` is set to `yes`, then the file will be closed after writing. If + this function is called again after closing, the file will be reopened + for appending. + args: + path: + type: 'Path' + description: > + The path of the file to write to. + append: + type: 'Bool' + default: 'no' + description: > + If set to `yes`, writes to the file will append. If set to `no`, then + the first write to the file will overwrite its contents and subsequent + calls will append. + permissions: + type: 'Int32' + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is created. + example: | + write := (./file.txt).byte_writer() + write("Hello\n".utf8())! + write("world\n".utf8(), close=yes)! + + Path.write_bytes: short: write bytes to a file description: > -- cgit v1.2.3 From dbae987f1fb54da795185a03f4c00d56a639f8cd Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Wed, 31 Dec 2025 15:13:32 -0500 Subject: Changed is_between() to be bidirectional --- api/api.md | 23 +++++++++++++---------- api/bytes.md | 7 ++++--- api/bytes.yaml | 7 ++++--- api/integers.md | 9 +++++---- api/integers.yaml | 11 ++++++----- api/nums.md | 7 ++++--- api/nums.yaml | 7 ++++--- 7 files changed, 40 insertions(+), 31 deletions(-) (limited to 'api') diff --git a/api/api.md b/api/api.md index d035a3fe..df8386ff 100644 --- a/api/api.md +++ b/api/api.md @@ -295,15 +295,16 @@ Determines if an integer is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Byte` | The integer to be checked. | - -low | `Byte` | The lower bound to check (inclusive). | - -high | `Byte` | The upper bound to check (inclusive). | - +low | `Byte` | One end of the range to check (inclusive); | - +high | `Byte` | The other end of the range to check (inclusive); | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` **Example:** ```tomo assert Byte(7).is_between(1, 10) == yes +assert Byte(7).is_between(10, 1) == yes assert Byte(7).is_between(100, 200) == no assert Byte(7).is_between(1, 7) == yes @@ -545,7 +546,7 @@ assert (255).hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF" ## Int.is_between ```tomo -Int.is_between : func(x: Int, low: Int, high: Int -> Bool) +Int.is_between : func(x: Int, a: Int, b: Int -> Bool) ``` Determines if an integer is between two numbers (inclusive). @@ -553,15 +554,16 @@ Determines if an integer is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Int` | The integer to be checked. | - -low | `Int` | The lower bound to check (inclusive). | - -high | `Int` | The upper bound to check (inclusive). | - +a | `Int` | One end of the range to check (inclusive). | - +b | `Int` | The other end of the range to check (inclusive). | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no` **Example:** ```tomo assert (7).is_between(1, 10) == yes +assert (7).is_between(10, 1) == yes assert (7).is_between(100, 200) == no assert (7).is_between(1, 7) == yes @@ -1949,15 +1951,16 @@ Determines if a number is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Num` | The integer to be checked. | - -low | `Num` | The lower bound to check (inclusive). | - -high | `Num` | The upper bound to check (inclusive). | - +low | `Num` | One end of the range to check (inclusive). | - +high | `Num` | The other end of the range to check (inclusive). | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` **Example:** ```tomo assert (7.5).is_between(1, 10) == yes +assert (7.5).is_between(10, 1) == yes assert (7.5).is_between(100, 200) == no assert (7.5).is_between(1, 7.5) == yes diff --git a/api/bytes.md b/api/bytes.md index bb54d92c..99055523 100644 --- a/api/bytes.md +++ b/api/bytes.md @@ -62,15 +62,16 @@ Determines if an integer is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Byte` | The integer to be checked. | - -low | `Byte` | The lower bound to check (inclusive). | - -high | `Byte` | The upper bound to check (inclusive). | - +low | `Byte` | One end of the range to check (inclusive); | - +high | `Byte` | The other end of the range to check (inclusive); | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` **Example:** ```tomo assert Byte(7).is_between(1, 10) == yes +assert Byte(7).is_between(10, 1) == yes assert Byte(7).is_between(100, 200) == no assert Byte(7).is_between(1, 7) == yes diff --git a/api/bytes.yaml b/api/bytes.yaml index dea650e2..adf7103b 100644 --- a/api/bytes.yaml +++ b/api/bytes.yaml @@ -57,7 +57,7 @@ Byte.is_between: return: type: 'Bool' description: > - `yes` if `low <= x and x <= high`, otherwise `no` + `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` args: x: type: 'Byte' @@ -66,13 +66,14 @@ Byte.is_between: low: type: 'Byte' description: > - The lower bound to check (inclusive). + One end of the range to check (inclusive); high: type: 'Byte' description: > - The upper bound to check (inclusive). + The other end of the range to check (inclusive); example: | assert Byte(7).is_between(1, 10) == yes + assert Byte(7).is_between(10, 1) == yes assert Byte(7).is_between(100, 200) == no assert Byte(7).is_between(1, 7) == yes diff --git a/api/integers.md b/api/integers.md index ef3a6a60..73779021 100644 --- a/api/integers.md +++ b/api/integers.md @@ -138,7 +138,7 @@ assert (255).hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF" ## Int.is_between ```tomo -Int.is_between : func(x: Int, low: Int, high: Int -> Bool) +Int.is_between : func(x: Int, a: Int, b: Int -> Bool) ``` Determines if an integer is between two numbers (inclusive). @@ -146,15 +146,16 @@ Determines if an integer is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Int` | The integer to be checked. | - -low | `Int` | The lower bound to check (inclusive). | - -high | `Int` | The upper bound to check (inclusive). | - +a | `Int` | One end of the range to check (inclusive). | - +b | `Int` | The other end of the range to check (inclusive). | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no` **Example:** ```tomo assert (7).is_between(1, 10) == yes +assert (7).is_between(10, 1) == yes assert (7).is_between(100, 200) == no assert (7).is_between(1, 7) == yes diff --git a/api/integers.yaml b/api/integers.yaml index b3c6b579..bbbd395d 100644 --- a/api/integers.yaml +++ b/api/integers.yaml @@ -146,22 +146,23 @@ Int.is_between: return: type: 'Bool' description: > - `yes` if `low <= x and x <= high`, otherwise `no` + `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no` args: x: type: 'Int' description: > The integer to be checked. - low: + a: type: 'Int' description: > - The lower bound to check (inclusive). - high: + One end of the range to check (inclusive). + b: type: 'Int' description: > - The upper bound to check (inclusive). + The other end of the range to check (inclusive). example: | assert (7).is_between(1, 10) == yes + assert (7).is_between(10, 1) == yes assert (7).is_between(100, 200) == no assert (7).is_between(1, 7) == yes diff --git a/api/nums.md b/api/nums.md index dac5967f..1bad194d 100644 --- a/api/nums.md +++ b/api/nums.md @@ -574,15 +574,16 @@ Determines if a number is between two numbers (inclusive). Argument | Type | Description | Default ---------|------|-------------|--------- x | `Num` | The integer to be checked. | - -low | `Num` | The lower bound to check (inclusive). | - -high | `Num` | The upper bound to check (inclusive). | - +low | `Num` | One end of the range to check (inclusive). | - +high | `Num` | The other end of the range to check (inclusive). | - -**Return:** `yes` if `low <= x and x <= high`, otherwise `no` +**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` **Example:** ```tomo assert (7.5).is_between(1, 10) == yes +assert (7.5).is_between(10, 1) == yes assert (7.5).is_between(100, 200) == no assert (7.5).is_between(1, 7.5) == yes diff --git a/api/nums.yaml b/api/nums.yaml index 4561bb91..28714ab9 100644 --- a/api/nums.yaml +++ b/api/nums.yaml @@ -401,7 +401,7 @@ Num.is_between: return: type: 'Bool' description: > - `yes` if `low <= x and x <= high`, otherwise `no` + `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no` args: x: type: 'Num' @@ -410,13 +410,14 @@ Num.is_between: low: type: 'Num' description: > - The lower bound to check (inclusive). + One end of the range to check (inclusive). high: type: 'Num' description: > - The upper bound to check (inclusive). + The other end of the range to check (inclusive). example: | assert (7.5).is_between(1, 10) == yes + assert (7.5).is_between(10, 1) == yes assert (7.5).is_between(100, 200) == no assert (7.5).is_between(1, 7.5) == yes -- cgit v1.2.3