From 83e6cc9197bd8e7a19834d291fe4c5e62639db38 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
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