(387 lines)
1 '\" t2 .\" Copyright (c) 2026 Bruce Hill3 .\" All rights reserved.4 .\"5 .TH Path 3 2026-03-14 "Tomo man-pages"6 .SH NAME7 Path \- a Tomo type8 .SH LIBRARY9 Tomo Standard Library10 .fi11 .SH METHODS13 .TP14 .BI Path.accessed\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)15 Gets the file access time of a file.17 For more, see:18 .BR Tomo-Path.accessed (3)21 .TP22 .BI Path.append\ :\ func(path:\ Path,\ text:\ Text,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)23 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.25 For more, see:26 .BR Tomo-Path.append (3)29 .TP30 .BI Path.append_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ Result)31 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.33 For more, see:34 .BR Tomo-Path.append_bytes (3)37 .TP38 .BI Path.base_name\ :\ func(path:\ Path\ ->\ Text)39 Returns the base name of the file or directory at the specified path.41 For more, see:42 .BR Tomo-Path.base_name (3)45 .TP46 .BI Path.by_line\ :\ func(path:\ Path\ ->\ func(->Text?)?)47 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.49 For more, see:50 .BR Tomo-Path.by_line (3)53 .TP54 .BI Path.byte_writer\ :\ func(path:\ Path,\ append:\ Bool\ =\ no,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ func(bytes:[Byte],\ close:Bool=no\ ->\ Result))55 Returns a function that can be used to repeatedly write bytes to the same file.57 For more, see:58 .BR Tomo-Path.byte_writer (3)61 .TP62 .BI Path.can_execute\ :\ func(path:\ Path\ ->\ Bool)63 Returns whether or not a file can be executed by the current user/group.65 For more, see:66 .BR Tomo-Path.can_execute (3)69 .TP70 .BI Path.can_read\ :\ func(path:\ Path\ ->\ Bool)71 Returns whether or not a file can be read by the current user/group.73 For more, see:74 .BR Tomo-Path.can_read (3)77 .TP78 .BI Path.can_write\ :\ func(path:\ Path\ ->\ Bool)79 Returns whether or not a file can be written by the current user/group.81 For more, see:82 .BR Tomo-Path.can_write (3)85 .TP86 .BI Path.changed\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)87 Gets the file change time of a file.89 For more, see:90 .BR Tomo-Path.changed (3)93 .TP94 .BI Path.child\ :\ func(path:\ Path,\ child:\ Text\ ->\ Path)95 Return a path that is a child of another path.97 For more, see:98 .BR Tomo-Path.child (3)101 .TP102 .BI Path.children\ :\ func(path:\ Path,\ include_hidden\ =\ no\ ->\ [Path])103 Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. Child ordering is not specified.105 For more, see:106 .BR Tomo-Path.children (3)109 .TP110 .BI Path.create_directory\ :\ func(path:\ Path,\ permissions\ =\ Int32(0o755),\ recursive\ =\ yes\ ->\ Result)111 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.113 For more, see:114 .BR Tomo-Path.create_directory (3)117 .TP118 .BI Path.current_dir\ :\ func(->\ Path)119 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.121 For more, see:122 .BR Tomo-Path.current_dir (3)125 .TP126 .BI Path.each_child\ :\ func(path:\ Path,\ include_hidden\ =\ no\ ->\ func(->Path?)?)127 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.129 For more, see:130 .BR Tomo-Path.each_child (3)133 .TP134 .BI Path.exists\ :\ func(path:\ Path\ ->\ Bool)135 Checks if a file or directory exists at the specified path.137 For more, see:138 .BR Tomo-Path.exists (3)141 .TP142 .BI Path.expand_home\ :\ func(path:\ Path\ ->\ Path)143 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.145 For more, see:146 .BR Tomo-Path.expand_home (3)149 .TP150 .BI Path.extension\ :\ func(path:\ Path,\ full:\ Bool\ =\ yes\ ->\ Text)151 Returns the file extension of the file at the specified path. Optionally returns the full extension.153 For more, see:154 .BR Tomo-Path.extension (3)157 .TP158 .BI Path.files\ :\ func(path:\ Path,\ include_hidden:\ Bool\ =\ no\ ->\ [Path])159 Returns a list of files within the directory at the specified path. Optionally includes hidden files.161 For more, see:162 .BR Tomo-Path.files (3)165 .TP166 .BI Path.glob\ :\ func(path:\ Path\ ->\ [Path])167 Perform a globbing operation and return a list of matching paths. Some glob specific details: - The paths "." and ".." are *not* included in any globbing results. - Files or directories that begin with "." will not match \fB*\fR, but will match \fB.*\fR. - Globs do support \fB{a,b}\fR syntax for matching files that match any of several choices of patterns. - The shell-style syntax \fB**\fR for matching subdirectories is not supported.169 For more, see:170 .BR Tomo-Path.glob (3)173 .TP174 .BI Path.group\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Text?)175 Get the owning group of a file or directory.177 For more, see:178 .BR Tomo-Path.group (3)181 .TP182 .BI Path.has_extension\ :\ func(path:\ Path,\ extension:\ Text\ ->\ Bool)183 Return whether or not a path has a given file extension.185 For more, see:186 .BR Tomo-Path.has_extension (3)189 .TP190 .BI Path.is_directory\ :\ func(path:\ Path,\ follow_symlinks\ =\ yes\ ->\ Bool)191 Checks if the path represents a directory. Optionally follows symbolic links.193 For more, see:194 .BR Tomo-Path.is_directory (3)197 .TP198 .BI Path.is_file\ :\ func(path:\ Path,\ follow_symlinks\ =\ yes\ ->\ Bool)199 Checks if the path represents a file. Optionally follows symbolic links.201 For more, see:202 .BR Tomo-Path.is_file (3)205 .TP206 .BI Path.is_socket\ :\ func(path:\ Path,\ follow_symlinks\ =\ yes\ ->\ Bool)207 Checks if the path represents a socket. Optionally follows symbolic links.209 For more, see:210 .BR Tomo-Path.is_socket (3)213 .TP214 .BI Path.is_symlink\ :\ func(path:\ Path\ ->\ Bool)215 Checks if the path represents a symbolic link.217 For more, see:218 .BR Tomo-Path.is_symlink (3)221 .TP222 .BI Path.lines\ :\ func(path:\ Path\ ->\ [Text]?)223 Returns a list with the lines of text in a file or returns none if the file could not be opened.225 For more, see:226 .BR Tomo-Path.lines (3)229 .TP230 .BI Path.matches_glob\ :\ func(path:\ Path,\ glob:\ Text\ ->\ Bool)231 Return whether or not a path matches a given glob.233 For more, see:234 .BR Tomo-Path.matches_glob (3)237 .TP238 .BI Path.modified\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Int64?)239 Gets the file modification time of a file.241 For more, see:242 .BR Tomo-Path.modified (3)245 .TP246 .BI Path.move\ :\ func(path:\ Path,\ dest:\ Path,\ allow_overwriting\ =\ no\ ->\ Result)247 Moves the file or directory from one location to another.249 For more, see:250 .BR Tomo-Path.move (3)253 .TP254 .BI Path.owner\ :\ func(path:\ Path,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Text?)255 Get the owning user of a file or directory.257 For more, see:258 .BR Tomo-Path.owner (3)261 .TP262 .BI Path.parent\ :\ func(path:\ Path\ ->\ Path?)263 Returns the parent directory of the file or directory at the specified path.265 For more, see:266 .BR Tomo-Path.parent (3)269 .TP270 .BI Path.read\ :\ func(path:\ Path\ ->\ Text?)271 Reads the contents of the file at the specified path or none if the file could not be read.273 For more, see:274 .BR Tomo-Path.read (3)277 .TP278 .BI Path.read_bytes\ :\ func(path:\ Path,\ limit:\ Int?\ =\ none\ ->\ [Byte]?)279 Reads the contents of the file at the specified path or none if the file could not be read.281 For more, see:282 .BR Tomo-Path.read_bytes (3)285 .TP286 .BI Path.relative_to\ :\ func(path:\ Path,\ relative_to\ =\ (./)\ ->\ Path)287 Returns the path relative to a given base path. By default, the base path is the current directory.289 For more, see:290 .BR Tomo-Path.relative_to (3)293 .TP294 .BI Path.remove\ :\ func(path:\ Path,\ ignore_missing\ =\ no\ ->\ Result)295 Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.297 For more, see:298 .BR Tomo-Path.remove (3)301 .TP302 .BI Path.resolved\ :\ func(path:\ Path,\ relative_to\ =\ (./)\ ->\ Path)303 Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.305 For more, see:306 .BR Tomo-Path.resolved (3)309 .TP310 .BI Path.set_owner\ :\ func(path:\ Path,\ owner:\ Text?\ =\ none,\ group:\ Text?\ =\ none,\ follow_symlinks:\ Bool\ =\ yes\ ->\ Result)311 Set the owning user and/or group for a path.313 For more, see:314 .BR Tomo-Path.set_owner (3)317 .TP318 .BI Path.sibling\ :\ func(path:\ Path,\ name:\ Text\ ->\ Path)319 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)\fR321 For more, see:322 .BR Tomo-Path.sibling (3)325 .TP326 .BI Path.subdirectories\ :\ func(path:\ Path,\ include_hidden\ =\ no\ ->\ [Path])327 Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.329 For more, see:330 .BR Tomo-Path.subdirectories (3)333 .TP334 .BI Path.unique_directory\ :\ func(path:\ Path\ ->\ Path)335 Generates a unique directory path based on the given path. Useful for creating temporary directories.337 For more, see:338 .BR Tomo-Path.unique_directory (3)341 .TP342 .BI Path.walk\ :\ func(path:\ Path,\ include_hidden\ =\ no,\ follow_symlinks:\ Bool\ =\ no\ ->\ func(->Path?))343 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.345 For more, see:346 .BR Tomo-Path.walk (3)349 .TP350 .BI Path.write\ :\ func(path:\ Path,\ text:\ Text,\ permissions\ =\ Int32(0o644)\ ->\ Result)351 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.353 For more, see:354 .BR Tomo-Path.write (3)357 .TP358 .BI Path.write_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte],\ permissions\ =\ Int32(0o644)\ ->\ Result)359 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.361 For more, see:362 .BR Tomo-Path.write_bytes (3)365 .TP366 .BI Path.write_unique\ :\ func(path:\ Path,\ text:\ Text\ ->\ Path)367 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.369 For more, see:370 .BR Tomo-Path.write_unique (3)373 .TP374 .BI Path.write_unique_bytes\ :\ func(path:\ Path,\ bytes:\ [Byte]\ ->\ Path)375 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.377 For more, see:378 .BR Tomo-Path.write_unique_bytes (3)381 .TP382 .BI Path.writer\ :\ func(path:\ Path,\ append:\ Bool\ =\ no,\ permissions:\ Int32\ =\ Int32(0o644)\ ->\ func(text:Text,\ close:Bool=no\ ->\ Result))383 Returns a function that can be used to repeatedly write to the same file.385 For more, see:386 .BR Tomo-Path.writer (3)