'\" t
.\" Copyright (c) 2026 Bruce Hill
.\" All rights reserved.
.\"
.TH Path 3 2026-09-01 "Tomo man-pages"
.SH NAME
Path \- a Tomo type
.SH LIBRARY
Tomo Standard Library
.fi
.SH METHODS

.TP
.BI Path.accessed\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)
Gets the file access time of a file. 

For more, see:
.BR Tomo-Path.accessed (3)


.TP
.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:
.BR Tomo-Path.append (3)


.TP
.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:
.BR Tomo-Path.append_bytes (3)


.TP
.BI Path.base_name\ :\ func(path:\ Path\ ->\ Text?)
Returns the base name of the file or directory at the specified path. 

For more, see:
.BR Tomo-Path.base_name (3)


.TP
.BI Path.by_line\ :\ func(path:\ Path\ ->\ func(->Text?)?)
Returns an iterator that can be used to iterate over a file one line at a time, or returns none if the file could not be opened. 

For more, see:
.BR Tomo-Path.by_line (3)


.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.bytes\ :\ func(path:\ Path\ ->\ [Byte])
Convert a path to a list of the raw bytes that make up its text representation. This does not read the file at the given path; see \fBPath.read_bytes\fR for that. 

For more, see:
.BR Tomo-Path.bytes (3)


.TP
.BI Path.can_execute\ :\ func(path:\ Path\ ->\ Bool)
Returns whether or not a file can be executed by the current user/group. 

For more, see:
.BR Tomo-Path.can_execute (3)


.TP
.BI Path.can_read\ :\ func(path:\ Path\ ->\ Bool)
Returns whether or not a file can be read by the current user/group. 

For more, see:
.BR Tomo-Path.can_read (3)


.TP
.BI Path.can_write\ :\ func(path:\ Path\ ->\ Bool)
Returns whether or not a file can be written by the current user/group. 

For more, see:
.BR Tomo-Path.can_write (3)


.TP
.BI Path.changed\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)
Gets the file change time of a file. 

For more, see:
.BR Tomo-Path.changed (3)


.TP
.BI Path.child\ :\ func(path:\ Path,\ child:\ Text\ ->\ Path)
Return a path that is a child of another path. 

For more, see:
.BR Tomo-Path.child (3)


.TP
.BI Path.children\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no\ ->\ [Path]?)
Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. Child ordering is not specified. 

For more, see:
.BR Tomo-Path.children (3)


.TP
.BI Path.components\ :\ func(path:\ Path\ ->\ [Text]?)
Returns a list of the file components of a path. 

For more, see:
.BR Tomo-Path.components (3)


.TP
.BI Path.concatenated_with\ :\ func(a:\ Path,\ b:\ Path\ ->\ Path)
Return the concatenation of two paths. This is what the \fB++\fR operator does on paths. The result is normalized, so \fB.\fR and \fB..\fR components in the second path are resolved away. 

For more, see:
.BR Tomo-Path.concatenated_with (3)


.TP
.BI Path.copy_to\ :\ func(path:\ Path,\ dest:\ Path,\ overwrite:\ Bool\ =\ no\ ->\ Result)
Copies the file or directory from one location to another. This is the same behavior as \fBcp -rn -T src dest\fR or \fBcp -rf -T src dest\fR (if \fBoverwrite\fR is enabled). 

For more, see:
.BR Tomo-Path.copy_to (3)


.TP
.BI Path.create_directory\ :\ func(path:\ Path,\ permissions:\ Int32\ =\ Int32(0o755),\ recursive:\ Bool\ =\ 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:
.BR Tomo-Path.create_directory (3)


.TP
.BI Path.current_dir\ :\ func(->\ Path)
Returns the absolute path of the current working directory. 

For more, see:
.BR Tomo-Path.current_dir (3)


.TP
.BI Path.each_child\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no\ ->\ func(->Path?)?)
Returns an iterator over the children (files and directories) within the directory at the specified path. Optionally includes hidden files. Iteration order is not specified. 

For more, see:
.BR Tomo-Path.each_child (3)


.TP
.BI Path.exists\ :\ func(path:\ Path\ ->\ Bool)
Checks if a file or directory exists at the specified path. 

For more, see:
.BR Tomo-Path.exists (3)


.TP
.BI Path.expand_home\ :\ func(path:\ Path\ ->\ Path)
For home-based paths (those starting with \fB~\fR), expand the path to replace the tilde with and absolute path to the user's \fB$HOME\fR directory. 

For more, see:
.BR Tomo-Path.expand_home (3)


.TP
.BI Path.extension\ :\ func(path:\ Path,\ full:\ Bool\ =\ yes\ ->\ Text?)
Returns the file extension of the file at the specified path. Optionally returns the full extension. 

For more, see:
.BR Tomo-Path.extension (3)


.TP
.BI Path.files\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no\ ->\ [Path]?)
Returns a list of files within the directory at the specified path. Optionally includes hidden files. 

For more, see:
.BR Tomo-Path.files (3)


.TP
.BI Path.glob\ :\ func(path:\ Path,\ pattern:\ Text\ ->\ [Path]?)
Search a directory for paths matching a glob pattern. The pattern is relative to the directory, and unlike \fBPath.matches_glob\fR it is anchored: it has to account for every component below the directory. 

For more, see:
.BR Tomo-Path.glob (3)


.TP
.BI Path.group\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Text?)
Get the owning group of a file or directory. 

For more, see:
.BR Tomo-Path.group (3)


.TP
.BI Path.has_extension\ :\ func(path:\ Path,\ extension:\ Text\ ->\ Bool)
Return whether or not a path has a given file extension. Unlike \fBPath.extension\fR, this reads the raw bytes of the name and so works on names that are not valid UTF-8. 

For more, see:
.BR Tomo-Path.has_extension (3)


.TP
.BI Path.is_directory\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Bool)
Checks if the path represents a directory. Optionally follows symbolic links. 

For more, see:
.BR Tomo-Path.is_directory (3)


.TP
.BI Path.is_file\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Bool)
Checks if the path represents a file. Optionally follows symbolic links. 

For more, see:
.BR Tomo-Path.is_file (3)


.TP
.BI Path.is_pipe\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Bool)
Checks if the path represents a named pipe (a FIFO). Optionally follows symbolic links. 

For more, see:
.BR Tomo-Path.is_pipe (3)


.TP
.BI Path.is_socket\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Bool)
Checks if the path represents a socket. Optionally follows symbolic links. 

For more, see:
.BR Tomo-Path.is_socket (3)


.TP
.BI Path.is_symlink\ :\ func(path:\ Path\ ->\ Bool)
Checks if the path represents a symbolic link. 

For more, see:
.BR Tomo-Path.is_symlink (3)


.TP
.BI Path.lines\ :\ func(path:\ Path\ ->\ [Text]?)
Returns a list with the lines of text in a file or returns none if the file could not be opened. 

For more, see:
.BR Tomo-Path.lines (3)


.TP
.BI Path.matches_glob\ :\ func(path:\ Path,\ glob:\ Text\ ->\ Bool)
Return whether or not a path matches a given glob. This is a pattern match, not a filesystem operation, and it reads the raw bytes of the path, so it works on names that are not valid UTF-8. 

For more, see:
.BR Tomo-Path.matches_glob (3)


.TP
.BI Path.modified\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)
Gets the file modification time of a file. 

For more, see:
.BR Tomo-Path.modified (3)


.TP
.BI Path.move\ :\ func(path:\ Path,\ dest:\ Path,\ overwrite:\ Bool\ =\ no\ ->\ Result)
Moves the file or directory from one location to another. 

For more, see:
.BR Tomo-Path.move (3)


.TP
.BI Path.owner\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Text?)
Get the owning user of a file or directory. 

For more, see:
.BR Tomo-Path.owner (3)


.TP
.BI Path.parent\ :\ func(path:\ Path\ ->\ Path?)
Returns the parent directory of the file or directory at the specified path. 

For more, see:
.BR Tomo-Path.parent (3)


.TP
.BI Path.read\ :\ func(path:\ Path\ ->\ Text?)
Reads the contents of the file at the specified path or none if the file could not be read. 

For more, see:
.BR Tomo-Path.read (3)


.TP
.BI Path.read_bytes\ :\ func(path:\ Path,\ limit:\ Int?\ =\ none\ ->\ [Byte]?)
Reads the contents of the file at the specified path or none if the file could not be read. 

For more, see:
.BR Tomo-Path.read_bytes (3)


.TP
.BI Path.relative_to\ :\ func(path:\ Path,\ relative_to:\ Path\ ->\ Path)
Returns the path relative to a given base path. 

For more, see:
.BR Tomo-Path.relative_to (3)


.TP
.BI Path.remove\ :\ func(path:\ Path,\ ignore_missing:\ Bool\ =\ no\ ->\ Result)
Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. 

For more, see:
.BR Tomo-Path.remove (3)


.TP
.BI Path.resolved\ :\ func(path:\ Path,\ relative_to:\ Path\ =\ (./)\ ->\ Path)
Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. A relative base is itself resolved against the current directory first, so the result is always absolute. 

For more, see:
.BR Tomo-Path.resolved (3)


.TP
.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:
.BR Tomo-Path.set_owner (3)


.TP
.BI Path.sibling\ :\ func(path:\ Path,\ name:\ Text\ ->\ Path?)
Return a path that is a sibling of another path (i.e. has the same parent, but a different name). This is equivalent to \fB.parent().child(name)\fR 

For more, see:
.BR Tomo-Path.sibling (3)


.TP
.BI Path.subdirectories\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no\ ->\ [Path]?)
Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. 

For more, see:
.BR Tomo-Path.subdirectories (3)


.TP
.BI Path.unique_directory\ :\ func(path:\ Path\ ->\ Path?)
Generates a unique directory path based on the given path. Useful for creating temporary directories. 

For more, see:
.BR Tomo-Path.unique_directory (3)


.TP
.BI Path.walk\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no,\ follow_symlinks:\ Bool\ =\ no\ ->\ func(->Path?)?)
Returns an iterator that efficiently recursively walks over every file and subdirectory in a given directory. The iteration order is not defined, but in practice it may look a lot like a breadth-first traversal. 

For more, see:
.BR Tomo-Path.walk (3)


.TP
.BI Path.with_extension\ :\ func(path:\ Path,\ extension:\ Text,\ replace:\ Bool\ =\ yes\ ->\ Path)
Return a path with the given file extension, either replacing the path's existing extension or adding to it. 

For more, see:
.BR Tomo-Path.with_extension (3)


.TP
.BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ 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:
.BR Tomo-Path.write (3)


.TP
.BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ 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:
.BR Tomo-Path.write_bytes (3)


.TP
.BI Path.write_unique\ :\ func(path:\ Path,\ text:\ Text\ ->\ Path?)
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 files. 

For more, see:
.BR Tomo-Path.write_unique (3)


.TP
.BI Path.write_unique_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte]\ ->\ Path?)
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 files. 

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)