Add Path.writer() and Path.byte_writer()

3 files changed, 101 insertions, 1 deletions

diff --git a/man/man3/tomo-Path.3 b/man/man3/tomo-Path.3
index ae9b6d51..b916005a 100644
--- a/man/man3/tomo-Path.3
+++ b/man/man3/tomo-Path.3
@@ -2,7 +2,7 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path 3 2025-12-07 "Tomo man-pages"
+.TH Path 3 2025-12-22 "Tomo man-pages"
 .SH NAME
 Path \- a Tomo type
 .SH LIBRARY
@@ -51,6 +51,14 @@ For more, see:
 
 
 .TP
+.BI 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. 
+
+For more, see:
+.BR Tomo-Path.byte_writer (3)
+
+
+.TP
 .BI Path.can_execute\ :\ func(path:\ Path\ ->\ Bool)
 Returns whether or not a file can be executed by the current user/group. 
 
@@ -345,3 +353,11 @@ Writes the given bytes to a unique file path based on the specified path. The fi
 For more, see:
 .BR Tomo-Path.write_unique_bytes (3)
 
+
+.TP
+.BI 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. 
+
+For more, see:
+.BR Tomo-Path.writer (3)
+
diff --git a/man/man3/tomo-Path.byte_writer.3 b/man/man3/tomo-Path.byte_writer.3
new file mode 100644
index 00000000..595f0156
--- /dev/null
+++ b/man/man3/tomo-Path.byte_writer.3
@@ -0,0 +1,42 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Path.byte_writer 3 2025-12-22 "Tomo man-pages"
+.SH NAME
+Path.byte_writer \- create a byte-based file writer
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Path.byte_writer\ :\ func(path:\ Path,\ append:\ Bool\ =\ no,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ func(bytes:[Byte],\ close:Bool=no\ ->\ Result))
+.fi
+.SH DESCRIPTION
+Returns a function that can be used to repeatedly write bytes to the same file.
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+path	Path	The path of the file to write to. 	-
+append	Bool	If set to \fByes\fR, writes to the file will append. If set to \fBno\fR, 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)
+.TE
+.SH 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.
+
+.SH NOTES
+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.
+
+.SH EXAMPLES
+.EX
+write := (./file.txt).byte_writer()
+write("Hello\[rs]n".utf8())!
+write("world\[rs]n".utf8(), close=yes)!
+.EE
+.SH SEE ALSO
+.BR Tomo-Path (3)
diff --git a/man/man3/tomo-Path.writer.3 b/man/man3/tomo-Path.writer.3
new file mode 100644
index 00000000..8b3d53d8
--- /dev/null
+++ b/man/man3/tomo-Path.writer.3
@@ -0,0 +1,42 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Path.writer 3 2025-12-22 "Tomo man-pages"
+.SH NAME
+Path.writer \- create a file writer
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Path.writer\ :\ func(path:\ Path,\ append:\ Bool\ =\ no,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ func(text:Text,\ close:Bool=no\ ->\ Result))
+.fi
+.SH DESCRIPTION
+Returns a function that can be used to repeatedly write to the same file.
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+path	Path	The path of the file to write to. 	-
+append	Bool	If set to \fByes\fR, writes to the file will append. If set to \fBno\fR, 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)
+.TE
+.SH 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.
+
+.SH NOTES
+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.
+
+.SH EXAMPLES
+.EX
+write := (./file.txt).writer()
+write("Hello\[rs]n")!
+write("world\[rs]n", close=yes)!
+.EE
+.SH SEE ALSO
+.BR Tomo-Path (3)