Switch paths to use Result return values instead of fail()

10 files changed, 39 insertions, 38 deletions

diff --git a/man/man3/tomo-Path.3 b/man/man3/tomo-Path.3
index f383196e..ae9b6d51 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-11-29 "Tomo man-pages"
+.TH Path 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path \- a Tomo type
 .SH LIBRARY
@@ -19,7 +19,7 @@ For more, see:
 
 
 .TP
-.BI Path.append\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.append\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)
 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. 
 
 For more, see:
@@ -27,7 +27,7 @@ For more, see:
 
 
 .TP
-.BI Path.append_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.append_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)
 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. 
 
 For more, see:
@@ -99,7 +99,7 @@ For more, see:
 
 
 .TP
-.BI Path.create_directory\ :\ func(path:\ Path,\ permissions\ =\ Int32(0o755),\ recursive\ =\ yes\ ->\ Void)
+.BI Path.create_directory\ :\ func(path:\ Path,\ permissions\ =\ Int32(0o755),\ recursive\ =\ yes\ ->\ Result)
 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. 
 
 For more, see:
@@ -235,7 +235,7 @@ For more, see:
 
 
 .TP
-.BI Path.parent\ :\ func(path:\ Path\ ->\ Path)
+.BI Path.parent\ :\ func(path:\ Path\ ->\ Path?)
 Returns the parent directory of the file or directory at the specified path. 
 
 For more, see:
@@ -267,7 +267,7 @@ For more, see:
 
 
 .TP
-.BI Path.remove\ :\ func(path:\ Path,\ ignore_missing\ =\ no\ ->\ Void)
+.BI Path.remove\ :\ func(path:\ Path,\ ignore_missing\ =\ no\ ->\ Result)
 Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. 
 
 For more, see:
@@ -283,7 +283,7 @@ For more, see:
 
 
 .TP
-.BI Path.set_owner\ :\ func(path:\ Path,\ owner:\ Text?\ =\ none,\ group:\ Text?\ =\ none,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Void)
+.BI Path.set_owner\ :\ func(path:\ Path,\ owner:\ Text?\ =\ none,\ group:\ Text?\ =\ none,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Result)
 Set the owning user and/or group for a path. 
 
 For more, see:
@@ -315,7 +315,7 @@ For more, see:
 
 
 .TP
-.BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions\ =\ Int32(0o644)\ ->\ Result)
 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 writing cannot be successfully completed, a runtime error is raised. 
 
 For more, see:
@@ -323,7 +323,7 @@ For more, see:
 
 
 .TP
-.BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions\ =\ Int32(0o644)\ ->\ Result)
 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 writing cannot be successfully completed, a runtime error is raised. 
 
 For more, see:
diff --git a/man/man3/tomo-Path.append.3 b/man/man3/tomo-Path.append.3
index b065d55b..d11169b0 100644
--- a/man/man3/tomo-Path.append.3
+++ b/man/man3/tomo-Path.append.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.append 3 2025-11-29 "Tomo man-pages"
+.TH Path.append 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.append \- append to a file
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.append\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.append\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)
 .fi
 .SH DESCRIPTION
 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.
@@ -27,11 +27,11 @@ text	Text	The text to append to the file. 	-
 permissions	Int32	The permissions to set on the file if it is being created. 	Int32(0o644)
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX
-(./log.txt).append("extra line$(\[rs]n)")
+(./log.txt).append("extra line\[rs]n")!
 .EE
 .SH SEE ALSO
 .BR Tomo-Path (3)
diff --git a/man/man3/tomo-Path.append_bytes.3 b/man/man3/tomo-Path.append_bytes.3
index 48f795c3..c89cf08c 100644
--- a/man/man3/tomo-Path.append_bytes.3
+++ b/man/man3/tomo-Path.append_bytes.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.append_bytes 3 2025-11-29 "Tomo man-pages"
+.TH Path.append_bytes 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.append_bytes \- append bytes to a file
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.append_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.append_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)
 .fi
 .SH DESCRIPTION
 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.
@@ -27,11 +27,11 @@ bytes	[Byte]	The bytes to append to the file. 	-
 permissions	Int32	The permissions to set on the file if it is being created. 	Int32(0o644)
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX
-(./log.txt).append_bytes([104, 105])
+(./log.txt).append_bytes([104, 105])!
 .EE
 .SH SEE ALSO
 .BR Tomo-Path (3)
diff --git a/man/man3/tomo-Path.create_directory.3 b/man/man3/tomo-Path.create_directory.3
index 539aae36..639e3f4a 100644
--- a/man/man3/tomo-Path.create_directory.3
+++ b/man/man3/tomo-Path.create_directory.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.create_directory 3 2025-11-29 "Tomo man-pages"
+.TH Path.create_directory 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.create_directory \- make a directory
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.create_directory\ :\ func(path:\ Path,\ permissions\ =\ Int32(0o755),\ recursive\ =\ yes\ ->\ Void)
+.BI Path.create_directory\ :\ func(path:\ Path,\ permissions\ =\ Int32(0o755),\ recursive\ =\ yes\ ->\ Result)
 .fi
 .SH DESCRIPTION
 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.
@@ -27,7 +27,7 @@ permissions		The permissions to set on the new directory. 	Int32(0o755)
 recursive		If set to \fByes\fR, then recursively create any parent directories if they don't exist, otherwise fail if the parent directory does not exist. When set to \fByes\fR, this function behaves like \fBmkdir -p\fR. 	yes
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH NOTES
 
diff --git a/man/man3/tomo-Path.parent.3 b/man/man3/tomo-Path.parent.3
index 7af4f98f..57c4a4a5 100644
--- a/man/man3/tomo-Path.parent.3
+++ b/man/man3/tomo-Path.parent.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.parent 3 2025-11-29 "Tomo man-pages"
+.TH Path.parent 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.parent \- get parent directory
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.parent\ :\ func(path:\ Path\ ->\ Path)
+.BI Path.parent\ :\ func(path:\ Path\ ->\ Path?)
 .fi
 .SH DESCRIPTION
 Returns the parent directory of the file or directory at the specified path.
@@ -25,7 +25,7 @@ Name	Type	Description
 path	Path	The path of the file or directory. 
 .TE
 .SH RETURN
-The path of the parent directory.
+The path of the parent directory or `none` if the path is `(/)` (the file root).
 
 .SH EXAMPLES
 .EX
diff --git a/man/man3/tomo-Path.relative_to.3 b/man/man3/tomo-Path.relative_to.3
index a3bf2136..d7f547fb 100644
--- a/man/man3/tomo-Path.relative_to.3
+++ b/man/man3/tomo-Path.relative_to.3
@@ -2,7 +2,7 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.relative_to 3 2025-11-29 "Tomo man-pages"
+.TH Path.relative_to 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.relative_to \- apply a relative path to another
 .SH LIBRARY
@@ -26,11 +26,12 @@ path	Path	The path to convert. 	-
 relative_to		The base path for the relative path. 	(./)
 .TE
 .SH RETURN
-The relative path.
+A relative path from the reference point to the given path.
 
 .SH EXAMPLES
 .EX
-assert (./path/to/file.txt).relative(relative_to=(./path)) == (./to/file.txt)
+assert (./path/to/file.txt).relative_to((./path)) == (./to/file.txt)
+assert (/tmp/foo).relative_to((/tmp)) == (./foo)
 .EE
 .SH SEE ALSO
 .BR Tomo-Path (3)
diff --git a/man/man3/tomo-Path.remove.3 b/man/man3/tomo-Path.remove.3
index a98b4483..70ef4a56 100644
--- a/man/man3/tomo-Path.remove.3
+++ b/man/man3/tomo-Path.remove.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.remove 3 2025-11-29 "Tomo man-pages"
+.TH Path.remove 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.remove \- remove a file or directory
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.remove\ :\ func(path:\ Path,\ ignore_missing\ =\ no\ ->\ Void)
+.BI Path.remove\ :\ func(path:\ Path,\ ignore_missing\ =\ no\ ->\ Result)
 .fi
 .SH DESCRIPTION
 Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
@@ -26,7 +26,7 @@ path	Path	The path to remove. 	-
 ignore_missing		Whether to ignore errors if the file or directory does not exist. 	no
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX
diff --git a/man/man3/tomo-Path.set_owner.3 b/man/man3/tomo-Path.set_owner.3
index b0b24e71..1cba764a 100644
--- a/man/man3/tomo-Path.set_owner.3
+++ b/man/man3/tomo-Path.set_owner.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.set_owner 3 2025-11-29 "Tomo man-pages"
+.TH Path.set_owner 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.set_owner \- set the owner
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.set_owner\ :\ func(path:\ Path,\ owner:\ Text?\ =\ none,\ group:\ Text?\ =\ none,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Void)
+.BI Path.set_owner\ :\ func(path:\ Path,\ owner:\ Text?\ =\ none,\ group:\ Text?\ =\ none,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Result)
 .fi
 .SH DESCRIPTION
 Set the owning user and/or group for a path.
@@ -28,7 +28,7 @@ group	Text?	If non-none, the new group to assign to be the owner of the file. 	n
 follow_symlinks	Bool	Whether to follow symbolic links. 	yes
 .TE
 .SH RETURN
-Nothing. If a path does not exist, a failure will be raised.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX
diff --git a/man/man3/tomo-Path.write.3 b/man/man3/tomo-Path.write.3
index 6d9e1043..565935c5 100644
--- a/man/man3/tomo-Path.write.3
+++ b/man/man3/tomo-Path.write.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.write 3 2025-11-29 "Tomo man-pages"
+.TH Path.write 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.write \- write to a file
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions\ =\ Int32(0o644)\ ->\ Result)
 .fi
 .SH DESCRIPTION
 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 writing cannot be successfully completed, a runtime error is raised.
@@ -27,7 +27,7 @@ text	Text	The text to write to the file. 	-
 permissions		The permissions to set on the file if it is created. 	Int32(0o644)
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX
diff --git a/man/man3/tomo-Path.write_bytes.3 b/man/man3/tomo-Path.write_bytes.3
index 6534d18e..c11e97ed 100644
--- a/man/man3/tomo-Path.write_bytes.3
+++ b/man/man3/tomo-Path.write_bytes.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Path.write_bytes 3 2025-11-29 "Tomo man-pages"
+.TH Path.write_bytes 3 2025-12-07 "Tomo man-pages"
 .SH NAME
 Path.write_bytes \- write bytes to a file
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions\ =\ Int32(0o644)\ ->\ Void)
+.BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions\ =\ Int32(0o644)\ ->\ Result)
 .fi
 .SH DESCRIPTION
 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 writing cannot be successfully completed, a runtime error is raised.
@@ -27,7 +27,7 @@ bytes	[Byte]	A list of bytes to write to the file. 	-
 permissions		The permissions to set on the file if it is created. 	Int32(0o644)
 .TE
 .SH RETURN
-Nothing.
+Either `Success` or `Failure(reason)`.
 
 .SH EXAMPLES
 .EX