1 % API
   2 
   3 # Builtins
   4 
   5 # Path
   6 ## Path.accessed
   7 
   8 ```tomo
   9 Path.accessed : func(path: Path, follow_symlinks: Bool = yes -> Int64?)
  10 ```
  11 
  12 Gets the file access time of a file.
  13 
  14 Argument | Type | Description | Default
  15 ---------|------|-------------|---------
  16 path | `Path` | The path of the file whose access time you want.  | -
  17 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
  18 
  19 **Return:** A 64-bit unix epoch timestamp representing when the file or directory was last accessed, or `none` if no such file or directory exists.
  20 
  21 
  22 **Example:**
  23 ```tomo
  24 assert (./file.txt).accessed() == Int64(1704221100)
  25 assert (./not-a-file).accessed() == none
  26 
  27 ```
  28 ## Path.append
  29 
  30 ```tomo
  31 Path.append : func(path: Path, text: Text, permissions: Int32 = Int32(0o644) -> Result)
  32 ```
  33 
  34 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.
  35 
  36 Argument | Type | Description | Default
  37 ---------|------|-------------|---------
  38 path | `Path` | The path of the file to append to.  | -
  39 text | `Text` | The text to append to the file.  | -
  40 permissions | `Int32` | The permissions to set on the file if it is being created.  | `Int32(0o644)`
  41 
  42 **Return:** Either `Success` or `Failure(reason)`.
  43 
  44 
  45 **Example:**
  46 ```tomo
  47 (./log.txt).append("extra line\n")!
  48 
  49 ```
  50 ## Path.append_bytes
  51 
  52 ```tomo
  53 Path.append_bytes : func(path: Path, bytes: [Byte], permissions: Int32 = Int32(0o644) -> Result)
  54 ```
  55 
  56 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.
  57 
  58 Argument | Type | Description | Default
  59 ---------|------|-------------|---------
  60 path | `Path` | The path of the file to append to.  | -
  61 bytes | `[Byte]` | The bytes to append to the file.  | -
  62 permissions | `Int32` | The permissions to set on the file if it is being created.  | `Int32(0o644)`
  63 
  64 **Return:** Either `Success` or `Failure(reason)`.
  65 
  66 
  67 **Example:**
  68 ```tomo
  69 (./log.txt).append_bytes([104, 105])!
  70 
  71 ```
  72 ## Path.base_name
  73 
  74 ```tomo
  75 Path.base_name : func(path: Path -> Text)
  76 ```
  77 
  78 Returns the base name of the file or directory at the specified path.
  79 
  80 Argument | Type | Description | Default
  81 ---------|------|-------------|---------
  82 path | `Path` | The path of the file or directory.  | -
  83 
  84 **Return:** The base name of the file or directory.
  85 
  86 
  87 **Example:**
  88 ```tomo
  89 assert (./path/to/file.txt).base_name() == "file.txt"
  90 
  91 ```
  92 ## Path.by_line
  93 
  94 ```tomo
  95 Path.by_line : func(path: Path -> func(->Text?)?)
  96 ```
  97 
  98 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.
  99 
 100 Argument | Type | Description | Default
 101 ---------|------|-------------|---------
 102 path | `Path` | The path of the file.  | -
 103 
 104 **Return:** An iterator that can be used to get lines from a file one at a time or none if the file couldn't be read.
 105 
 106 
 107 **Example:**
 108 ```tomo
 109 # Safely handle file not being readable:
 110 if lines := (./file.txt).by_line()
 111     for line in lines
 112         say(line.upper())
 113 else
 114     say("Couldn't read file!")
 115 
 116 # Assume the file is readable and error if that's not the case:
 117 for line in (/dev/stdin).by_line()!
 118     say(line.upper())
 119 
 120 ```
 121 ## Path.byte_writer
 122 
 123 ```tomo
 124 Path.byte_writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(bytes:[Byte], close:Bool=no -> Result))
 125 ```
 126 
 127 Returns a function that can be used to repeatedly write bytes to the same file.
 128 
 129 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.
 130 
 131 Argument | Type | Description | Default
 132 ---------|------|-------------|---------
 133 path | `Path` | The path of the file to write to.  | -
 134 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`
 135 permissions | `Int32` | The permissions to set on the file if it is created.  | `Int32(0o644)`
 136 
 137 **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.
 138 
 139 
 140 **Example:**
 141 ```tomo
 142 write := (./file.txt).byte_writer()
 143 write("Hello\n".utf8())!
 144 write("world\n".utf8(), close=yes)!
 145 
 146 ```
 147 ## Path.can_execute
 148 
 149 ```tomo
 150 Path.can_execute : func(path: Path -> Bool)
 151 ```
 152 
 153 Returns whether or not a file can be executed by the current user/group.
 154 
 155 Argument | Type | Description | Default
 156 ---------|------|-------------|---------
 157 path | `Path` | The path of the file to check.  | -
 158 
 159 **Return:** `yes` if the file or directory exists and the current user has execute permissions, otherwise `no`.
 160 
 161 
 162 **Example:**
 163 ```tomo
 164 assert (/bin/sh).can_execute() == yes
 165 assert (/usr/include/stdlib.h).can_execute() == no
 166 assert (/non/existant/file).can_execute() == no
 167 
 168 ```
 169 ## Path.can_read
 170 
 171 ```tomo
 172 Path.can_read : func(path: Path -> Bool)
 173 ```
 174 
 175 Returns whether or not a file can be read by the current user/group.
 176 
 177 Argument | Type | Description | Default
 178 ---------|------|-------------|---------
 179 path | `Path` | The path of the file to check.  | -
 180 
 181 **Return:** `yes` if the file or directory exists and the current user has read permissions, otherwise `no`.
 182 
 183 
 184 **Example:**
 185 ```tomo
 186 assert (/usr/include/stdlib.h).can_read() == yes
 187 assert (/etc/shadow).can_read() == no
 188 assert (/non/existant/file).can_read() == no
 189 
 190 ```
 191 ## Path.can_write
 192 
 193 ```tomo
 194 Path.can_write : func(path: Path -> Bool)
 195 ```
 196 
 197 Returns whether or not a file can be written by the current user/group.
 198 
 199 Argument | Type | Description | Default
 200 ---------|------|-------------|---------
 201 path | `Path` | The path of the file to check.  | -
 202 
 203 **Return:** `yes` if the file or directory exists and the current user has write permissions, otherwise `no`.
 204 
 205 
 206 **Example:**
 207 ```tomo
 208 assert (/tmp).can_write() == yes
 209 assert (/etc/passwd).can_write() == no
 210 assert (/non/existant/file).can_write() == no
 211 
 212 ```
 213 ## Path.changed
 214 
 215 ```tomo
 216 Path.changed : func(path: Path, follow_symlinks: Bool = yes -> Int64?)
 217 ```
 218 
 219 Gets the file change time of a file.
 220 
 221 This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, which is _not_ the file creation time.
 222 
 223 Argument | Type | Description | Default
 224 ---------|------|-------------|---------
 225 path | `Path` | The path of the file whose change time you want.  | -
 226 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 227 
 228 **Return:** A 64-bit unix epoch timestamp representing when the file or directory was last changed, or `none` if no such file or directory exists.
 229 
 230 
 231 **Example:**
 232 ```tomo
 233 assert (./file.txt).changed() == Int64(1704221100)
 234 assert (./not-a-file).changed() == none
 235 
 236 ```
 237 ## Path.child
 238 
 239 ```tomo
 240 Path.child : func(path: Path, child: Text -> Path)
 241 ```
 242 
 243 Return a path that is a child of another path.
 244 
 245 Argument | Type | Description | Default
 246 ---------|------|-------------|---------
 247 path | `Path` | The path of a directory.  | -
 248 child | `Text` | The name of a child file or directory.  | -
 249 
 250 **Return:** A new path representing the child.
 251 
 252 
 253 **Example:**
 254 ```tomo
 255 assert (./directory).child("file.txt") == (./directory/file.txt)
 256 
 257 ```
 258 ## Path.children
 259 
 260 ```tomo
 261 Path.children : func(path: Path, include_hidden = no -> [Path])
 262 ```
 263 
 264 Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. Child ordering is not specified.
 265 
 266 Argument | Type | Description | Default
 267 ---------|------|-------------|---------
 268 path | `Path` | The path of the directory.  | -
 269 include_hidden | `` | Whether to include hidden files (those starting with a `.`).  | `no`
 270 
 271 **Return:** A list of paths for the children.
 272 
 273 
 274 **Example:**
 275 ```tomo
 276 assert (./directory).children(include_hidden=yes) == [(./directory/.git), (./directory/foo.txt)]
 277 
 278 ```
 279 ## Path.create_directory
 280 
 281 ```tomo
 282 Path.create_directory : func(path: Path, permissions = Int32(0o755), recursive = yes -> Result)
 283 ```
 284 
 285 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.
 286 
 287 
 288 Argument | Type | Description | Default
 289 ---------|------|-------------|---------
 290 path | `Path` | The path of the directory to create.  | -
 291 permissions | `` | The permissions to set on the new directory.  | `Int32(0o755)`
 292 recursive | `` | If set to `yes`, then recursively create any parent directories if they don't exist, otherwise fail if the parent directory does not exist. When set to `yes`, this function behaves like `mkdir -p`.  | `yes`
 293 
 294 **Return:** Either `Success` or `Failure(reason)`.
 295 
 296 
 297 **Example:**
 298 ```tomo
 299 (./new_directory).create_directory()!
 300 
 301 ```
 302 ## Path.current_dir
 303 
 304 ```tomo
 305 Path.current_dir : func(-> Path)
 306 ```
 307 
 308 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.
 309 
 310 
 311 **Return:** The absolute path of the current directory.
 312 
 313 
 314 **Example:**
 315 ```tomo
 316 assert Path.current_dir() == (/home/user/tomo)
 317 
 318 ```
 319 ## Path.each_child
 320 
 321 ```tomo
 322 Path.each_child : func(path: Path, include_hidden = no -> func(->Path?)?)
 323 ```
 324 
 325 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.
 326 
 327 Argument | Type | Description | Default
 328 ---------|------|-------------|---------
 329 path | `Path` | The path of the directory.  | -
 330 include_hidden | `` | Whether to include hidden files (those starting with a `.`).  | `no`
 331 
 332 **Return:** An iterator over the children in a directory or `none` if the path is not a directory or a symlink to a directory.
 333 
 334 
 335 **Example:**
 336 ```tomo
 337 for child in (/dir).each_child()
 338     say("Child: $child")
 339 
 340 ```
 341 ## Path.exists
 342 
 343 ```tomo
 344 Path.exists : func(path: Path -> Bool)
 345 ```
 346 
 347 Checks if a file or directory exists at the specified path.
 348 
 349 Argument | Type | Description | Default
 350 ---------|------|-------------|---------
 351 path | `Path` | The path to check.  | -
 352 
 353 **Return:** `True` if the file or directory exists, `False` otherwise.
 354 
 355 
 356 **Example:**
 357 ```tomo
 358 assert (/).exists() == yes
 359 
 360 ```
 361 ## Path.expand_home
 362 
 363 ```tomo
 364 Path.expand_home : func(path: Path -> Path)
 365 ```
 366 
 367 For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory.
 368 
 369 Argument | Type | Description | Default
 370 ---------|------|-------------|---------
 371 path | `Path` | The path to expand.  | -
 372 
 373 **Return:** If the path does not start with a `~`, then return it unmodified. Otherwise, replace the `~` with an absolute path to the user's home directory.
 374 
 375 
 376 **Example:**
 377 ```tomo
 378 # Assume current user is 'user'
 379 assert (~/foo).expand_home() == (/home/user/foo)
 380 # No change
 381 assert (/foo).expand_home() == (/foo)
 382 
 383 ```
 384 ## Path.extension
 385 
 386 ```tomo
 387 Path.extension : func(path: Path, full: Bool = yes -> Text)
 388 ```
 389 
 390 Returns the file extension of the file at the specified path. Optionally returns the full extension.
 391 
 392 Argument | Type | Description | Default
 393 ---------|------|-------------|---------
 394 path | `Path` | The path of the file.  | -
 395 full | `Bool` | Whether to return everything after the first `.` in the base name, or only the last part of the extension.  | `yes`
 396 
 397 **Return:** The file extension (not including the leading `.`) or an empty text if there is no file extension.
 398 
 399 
 400 **Example:**
 401 ```tomo
 402 assert (./file.tar.gz).extension() == "tar.gz"
 403 assert (./file.tar.gz).extension(full=no) == "gz"
 404 assert (/foo).extension() == ""
 405 assert (./.git).extension() == ""
 406 
 407 ```
 408 ## Path.files
 409 
 410 ```tomo
 411 Path.files : func(path: Path, include_hidden: Bool = no -> [Path])
 412 ```
 413 
 414 Returns a list of files within the directory at the specified path. Optionally includes hidden files.
 415 
 416 Argument | Type | Description | Default
 417 ---------|------|-------------|---------
 418 path | `Path` | The path of the directory.  | -
 419 include_hidden | `Bool` | Whether to include hidden files (those starting with a `.`).  | `no`
 420 
 421 **Return:** A list of file paths.
 422 
 423 
 424 **Example:**
 425 ```tomo
 426 assert (./directory).files(include_hidden=yes) == [(./directory/file1.txt), (./directory/file2.txt)]
 427 
 428 ```
 429 ## Path.glob
 430 
 431 ```tomo
 432 Path.glob : func(path: Path -> [Path])
 433 ```
 434 
 435 Perform a globbing operation and return a list of matching paths. Some glob specific details:
 436 - The paths "." and ".." are *not* included in any globbing results.
 437 - Files or directories that begin with "." will not match `*`, but will match `.*`.
 438 - Globs do support `{a,b}` syntax for matching files that match any of several
 439   choices of patterns.
 440 
 441 - The shell-style syntax `**` for matching subdirectories is not supported.
 442 
 443 Argument | Type | Description | Default
 444 ---------|------|-------------|---------
 445 path | `Path` | The path of the directory which may contain special globbing characters like `*`, `?`, or `{...}`  | -
 446 
 447 **Return:** A list of file paths that match the glob.
 448 
 449 
 450 **Example:**
 451 ```tomo
 452 # Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden
 453 assert (./*).glob() == [(./foo.txt), (./baz.txt), (./qux.jpg)]
 454 assert (./*.txt).glob() == [(./foo.txt), (./baz.txt)]
 455 assert (./*.{txt,jpg}).glob() == [(./foo.txt), (./baz.txt), (./qux.jpg)]
 456 assert (./.*).glob() == [(./.hidden)]
 457 
 458 # Globs with no matches return an empty list:
 459 assert (./*.xxx).glob() == []
 460 
 461 ```
 462 ## Path.group
 463 
 464 ```tomo
 465 Path.group : func(path: Path, follow_symlinks: Bool = yes -> Text?)
 466 ```
 467 
 468 Get the owning group of a file or directory.
 469 
 470 Argument | Type | Description | Default
 471 ---------|------|-------------|---------
 472 path | `Path` | The path whose owning group to get.  | -
 473 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 474 
 475 **Return:** The name of the group which owns the file or directory, or `none` if the path does not exist.
 476 
 477 
 478 **Example:**
 479 ```tomo
 480 assert (/bin).group() == "root"
 481 assert (/non/existent/file).group() == none
 482 
 483 ```
 484 ## Path.has_extension
 485 
 486 ```tomo
 487 Path.has_extension : func(path: Path, extension: Text -> Bool)
 488 ```
 489 
 490 Return whether or not a path has a given file extension.
 491 
 492 Argument | Type | Description | Default
 493 ---------|------|-------------|---------
 494 path | `Path` | A path.  | -
 495 extension | `Text` | A file extension (leading `.` is optional). If empty, the check will test if the file does not have any file extension.  | -
 496 
 497 **Return:** Whether or not the path has the given extension.
 498 
 499 
 500 **Example:**
 501 ```tomo
 502 assert (/foo.txt).has_extension("txt") == yes
 503 assert (/foo.txt).has_extension(".txt") == yes
 504 assert (/foo.tar.gz).has_extension("gz") == yes
 505 assert (/foo.tar.gz).has_extension("zip") == no
 506 
 507 ```
 508 ## Path.is_directory
 509 
 510 ```tomo
 511 Path.is_directory : func(path: Path, follow_symlinks = yes -> Bool)
 512 ```
 513 
 514 Checks if the path represents a directory. Optionally follows symbolic links.
 515 
 516 Argument | Type | Description | Default
 517 ---------|------|-------------|---------
 518 path | `Path` | The path to check.  | -
 519 follow_symlinks | `` | Whether to follow symbolic links.  | `yes`
 520 
 521 **Return:** `True` if the path is a directory, `False` otherwise.
 522 
 523 
 524 **Example:**
 525 ```tomo
 526 assert (./directory/).is_directory() == yes
 527 assert (./file.txt).is_directory() == no
 528 
 529 ```
 530 ## Path.is_file
 531 
 532 ```tomo
 533 Path.is_file : func(path: Path, follow_symlinks = yes -> Bool)
 534 ```
 535 
 536 Checks if the path represents a file. Optionally follows symbolic links.
 537 
 538 Argument | Type | Description | Default
 539 ---------|------|-------------|---------
 540 path | `Path` | The path to check.  | -
 541 follow_symlinks | `` | Whether to follow symbolic links.  | `yes`
 542 
 543 **Return:** `True` if the path is a file, `False` otherwise.
 544 
 545 
 546 **Example:**
 547 ```tomo
 548 assert (./file.txt).is_file() == yes
 549 assert (./directory/).is_file() == no
 550 
 551 ```
 552 ## Path.is_socket
 553 
 554 ```tomo
 555 Path.is_socket : func(path: Path, follow_symlinks = yes -> Bool)
 556 ```
 557 
 558 Checks if the path represents a socket. Optionally follows symbolic links.
 559 
 560 Argument | Type | Description | Default
 561 ---------|------|-------------|---------
 562 path | `Path` | The path to check.  | -
 563 follow_symlinks | `` | Whether to follow symbolic links.  | `yes`
 564 
 565 **Return:** `True` if the path is a socket, `False` otherwise.
 566 
 567 
 568 **Example:**
 569 ```tomo
 570 assert (./socket).is_socket() == yes
 571 
 572 ```
 573 ## Path.is_symlink
 574 
 575 ```tomo
 576 Path.is_symlink : func(path: Path -> Bool)
 577 ```
 578 
 579 Checks if the path represents a symbolic link.
 580 
 581 Argument | Type | Description | Default
 582 ---------|------|-------------|---------
 583 path | `Path` | The path to check.  | -
 584 
 585 **Return:** `True` if the path is a symbolic link, `False` otherwise.
 586 
 587 
 588 **Example:**
 589 ```tomo
 590 assert (./link).is_symlink() == yes
 591 
 592 ```
 593 ## Path.lines
 594 
 595 ```tomo
 596 Path.lines : func(path: Path -> [Text]?)
 597 ```
 598 
 599 Returns a list with the lines of text in a file or returns none if the file could not be opened.
 600 
 601 Argument | Type | Description | Default
 602 ---------|------|-------------|---------
 603 path | `Path` | The path of the file.  | -
 604 
 605 **Return:** A list of the lines in a file or none if the file couldn't be read.
 606 
 607 
 608 **Example:**
 609 ```tomo
 610 lines := (./file.txt).lines()!
 611 
 612 ```
 613 ## Path.matches_glob
 614 
 615 ```tomo
 616 Path.matches_glob : func(path: Path, glob: Text -> Bool)
 617 ```
 618 
 619 Return whether or not a path matches a given glob.
 620 
 621 Argument | Type | Description | Default
 622 ---------|------|-------------|---------
 623 path | `Path` | The path to check.  | -
 624 glob | `Text` | The glob pattern to check.  | -
 625 
 626 **Return:** Whether or not the path matches the given glob.
 627 
 628 
 629 **Example:**
 630 ```tomo
 631 assert (./file.txt).matches_glob("*.txt")
 632 assert (./file.c).matches_glob("*.{c,h}")
 633 
 634 ```
 635 ## Path.modified
 636 
 637 ```tomo
 638 Path.modified : func(path: Path, follow_symlinks: Bool = yes -> Int64?)
 639 ```
 640 
 641 Gets the file modification time of a file.
 642 
 643 Argument | Type | Description | Default
 644 ---------|------|-------------|---------
 645 path | `Path` | The path of the file whose modification time you want.  | -
 646 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 647 
 648 **Return:** A 64-bit unix epoch timestamp representing when the file or directory was last modified, or `none` if no such file or directory exists.
 649 
 650 
 651 **Example:**
 652 ```tomo
 653 assert (./file.txt).modified() == Int64(1704221100)
 654 assert (./not-a-file).modified() == none
 655 
 656 ```
 657 ## Path.move
 658 
 659 ```tomo
 660 Path.move : func(path: Path, dest: Path, allow_overwriting = no -> Result)
 661 ```
 662 
 663 Moves the file or directory from one location to another.
 664 
 665 Argument | Type | Description | Default
 666 ---------|------|-------------|---------
 667 path | `Path` | The path to move.  | -
 668 dest | `Path` | The destination to move the path to.  | -
 669 allow_overwriting | `` | Whether to permit overwriting the destination if it is an existing file or directory.  | `no`
 670 
 671 **Return:** Either `Success` or `Failure(reason)`.
 672 
 673 
 674 **Example:**
 675 ```tomo
 676 (./file.txt).move(/tmp/renamed.txt)!
 677 
 678 ```
 679 ## Path.owner
 680 
 681 ```tomo
 682 Path.owner : func(path: Path, follow_symlinks: Bool = yes -> Text?)
 683 ```
 684 
 685 Get the owning user of a file or directory.
 686 
 687 Argument | Type | Description | Default
 688 ---------|------|-------------|---------
 689 path | `Path` | The path whose owner to get.  | -
 690 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 691 
 692 **Return:** The name of the user who owns the file or directory, or `none` if the path does not exist.
 693 
 694 
 695 **Example:**
 696 ```tomo
 697 assert (/bin).owner() == "root"
 698 assert (/non/existent/file).owner() == none
 699 
 700 ```
 701 ## Path.parent
 702 
 703 ```tomo
 704 Path.parent : func(path: Path -> Path?)
 705 ```
 706 
 707 Returns the parent directory of the file or directory at the specified path.
 708 
 709 Argument | Type | Description | Default
 710 ---------|------|-------------|---------
 711 path | `Path` | The path of the file or directory.  | -
 712 
 713 **Return:** The path of the parent directory or `none` if the path is `(/)` (the file root).
 714 
 715 
 716 **Example:**
 717 ```tomo
 718 assert (./path/to/file.txt).parent() == (./path/to/)
 719 
 720 ```
 721 ## Path.read
 722 
 723 ```tomo
 724 Path.read : func(path: Path -> Text?)
 725 ```
 726 
 727 Reads the contents of the file at the specified path or none if the file could not be read.
 728 
 729 Argument | Type | Description | Default
 730 ---------|------|-------------|---------
 731 path | `Path` | The path of the file to read.  | -
 732 
 733 **Return:** The contents of the file. If the file could not be read, none will be returned. If the file can be read, but is not valid UTF8 data, an error will be raised.
 734 
 735 
 736 **Example:**
 737 ```tomo
 738 assert (./hello.txt).read() == "Hello"
 739 assert (./nosuchfile.xxx).read() == none
 740 
 741 ```
 742 ## Path.read_bytes
 743 
 744 ```tomo
 745 Path.read_bytes : func(path: Path, limit: Int? = none -> [Byte]?)
 746 ```
 747 
 748 Reads the contents of the file at the specified path or none if the file could not be read.
 749 
 750 Argument | Type | Description | Default
 751 ---------|------|-------------|---------
 752 path | `Path` | The path of the file to read.  | -
 753 limit | `Int?` | A limit to how many bytes should be read.  | `none`
 754 
 755 **Return:** The byte contents of the file. If the file cannot be read, none will be returned.
 756 
 757 
 758 **Example:**
 759 ```tomo
 760 assert (./hello.txt).read_bytes()! == [72, 101, 108, 108, 111]
 761 assert (./nosuchfile.xxx).read_bytes() == none
 762 
 763 ```
 764 ## Path.relative_to
 765 
 766 ```tomo
 767 Path.relative_to : func(path: Path, relative_to = (./) -> Path)
 768 ```
 769 
 770 Returns the path relative to a given base path. By default, the base path is the current directory.
 771 
 772 Argument | Type | Description | Default
 773 ---------|------|-------------|---------
 774 path | `Path` | The path to convert.  | -
 775 relative_to | `` | The base path for the relative path.  | `(./)`
 776 
 777 **Return:** A relative path from the reference point to the given path.
 778 
 779 
 780 **Example:**
 781 ```tomo
 782 assert (./path/to/file.txt).relative_to((./path)) == (./to/file.txt)
 783 assert (/tmp/foo).relative_to((/tmp)) == (./foo)
 784 
 785 ```
 786 ## Path.remove
 787 
 788 ```tomo
 789 Path.remove : func(path: Path, ignore_missing = no -> Result)
 790 ```
 791 
 792 Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
 793 
 794 Argument | Type | Description | Default
 795 ---------|------|-------------|---------
 796 path | `Path` | The path to remove.  | -
 797 ignore_missing | `` | Whether to ignore errors if the file or directory does not exist.  | `no`
 798 
 799 **Return:** Either `Success` or `Failure(reason)`.
 800 
 801 
 802 **Example:**
 803 ```tomo
 804 (./file.txt).remove()!
 805 
 806 ```
 807 ## Path.resolved
 808 
 809 ```tomo
 810 Path.resolved : func(path: Path, relative_to = (./) -> Path)
 811 ```
 812 
 813 Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
 814 
 815 Argument | Type | Description | Default
 816 ---------|------|-------------|---------
 817 path | `Path` | The path to resolve.  | -
 818 relative_to | `` | The base path for resolution.  | `(./)`
 819 
 820 **Return:** The resolved absolute path.
 821 
 822 
 823 **Example:**
 824 ```tomo
 825 assert (~/foo).resolved() == (/home/user/foo)
 826 assert (./path/to/file.txt).resolved(relative_to=(/foo)) == (/foo/path/to/file.txt)
 827 
 828 ```
 829 ## Path.set_owner
 830 
 831 ```tomo
 832 Path.set_owner : func(path: Path, owner: Text? = none, group: Text? = none, follow_symlinks: Bool = yes -> Result)
 833 ```
 834 
 835 Set the owning user and/or group for a path.
 836 
 837 Argument | Type | Description | Default
 838 ---------|------|-------------|---------
 839 path | `Path` | The path to change the permissions for.  | -
 840 owner | `Text?` | If non-none, the new user to assign to be the owner of the file.  | `none`
 841 group | `Text?` | If non-none, the new group to assign to be the owner of the file.  | `none`
 842 follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 843 
 844 **Return:** Either `Success` or `Failure(reason)`.
 845 
 846 
 847 **Example:**
 848 ```tomo
 849 (./file.txt).set_owner(owner="root", group="wheel")!
 850 
 851 ```
 852 ## Path.sibling
 853 
 854 ```tomo
 855 Path.sibling : func(path: Path, name: Text -> Path)
 856 ```
 857 
 858 Return a path that is a sibling of another path (i.e. has the same parent, but a different name). This is equivalent to `.parent().child(name)`
 859 
 860 Argument | Type | Description | Default
 861 ---------|------|-------------|---------
 862 path | `Path` | A path.  | -
 863 name | `Text` | The name of a sibling file or directory.  | -
 864 
 865 **Return:** A new path representing the sibling.
 866 
 867 
 868 **Example:**
 869 ```tomo
 870 assert (/foo/baz).sibling("doop") == (/foo/doop)
 871 
 872 ```
 873 ## Path.subdirectories
 874 
 875 ```tomo
 876 Path.subdirectories : func(path: Path, include_hidden = no -> [Path])
 877 ```
 878 
 879 Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
 880 
 881 Argument | Type | Description | Default
 882 ---------|------|-------------|---------
 883 path | `Path` | The path of the directory.  | -
 884 include_hidden | `` | Whether to include hidden subdirectories (those starting with a `.`)  | `no`
 885 
 886 **Return:** A list of subdirectory paths.
 887 
 888 
 889 **Example:**
 890 ```tomo
 891 assert (./directory).subdirectories() == [(./directory/subdir1), (./directory/subdir2)]
 892 assert (./directory).subdirectories(include_hidden=yes) == [(./directory/.git), (./directory/subdir1), (./directory/subdir2)]
 893 
 894 ```
 895 ## Path.unique_directory
 896 
 897 ```tomo
 898 Path.unique_directory : func(path: Path -> Path)
 899 ```
 900 
 901 Generates a unique directory path based on the given path. Useful for creating temporary directories.
 902 
 903 Argument | Type | Description | Default
 904 ---------|------|-------------|---------
 905 path | `Path` | The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`.  | -
 906 
 907 **Return:** A unique directory path after creating the directory.
 908 
 909 
 910 **Example:**
 911 ```tomo
 912 created := (/tmp/my-dir.XXXXXX).unique_directory()
 913 assert created.is_directory() == yes
 914 created.remove()!
 915 
 916 ```
 917 ## Path.walk
 918 
 919 ```tomo
 920 Path.walk : func(path: Path, include_hidden = no, follow_symlinks: Bool = no -> func(->Path?))
 921 ```
 922 
 923 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.
 924 
 925 The path itself is always included in the iteration.
 926 
 927 Argument | Type | Description | Default
 928 ---------|------|-------------|---------
 929 path | `Path` | The path to begin the walk.  | -
 930 include_hidden | `` | Whether to include hidden files (those starting with a `.`)  | `no`
 931 follow_symlinks | `Bool` | Whether to follow symbolic links. Caution: if set to 'yes', it is possible for this iterator to get stuck in a loop, using increasingly large amounts of memory.  | `no`
 932 
 933 **Return:** An iterator that recursively walks over every file and subdirectory.
 934 
 935 
 936 **Example:**
 937 ```tomo
 938 for p in (/tmp).walk()
 939     say("File or dir: $p")
 940 
 941 # The path itself is always included:
 942 assert [p for p in (./file.txt).walk()] == [(./file.txt)]
 943 
 944 ```
 945 ## Path.write
 946 
 947 ```tomo
 948 Path.write : func(path: Path, text: Text, permissions = Int32(0o644) -> Result)
 949 ```
 950 
 951 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.
 952 
 953 Argument | Type | Description | Default
 954 ---------|------|-------------|---------
 955 path | `Path` | The path of the file to write to.  | -
 956 text | `Text` | The text to write to the file.  | -
 957 permissions | `` | The permissions to set on the file if it is created.  | `Int32(0o644)`
 958 
 959 **Return:** Either `Success` or `Failure(reason)`.
 960 
 961 
 962 **Example:**
 963 ```tomo
 964 (./file.txt).write("Hello, world!")!
 965 
 966 ```
 967 ## Path.write_bytes
 968 
 969 ```tomo
 970 Path.write_bytes : func(path: Path, bytes: [Byte], permissions = Int32(0o644) -> Result)
 971 ```
 972 
 973 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.
 974 
 975 Argument | Type | Description | Default
 976 ---------|------|-------------|---------
 977 path | `Path` | The path of the file to write to.  | -
 978 bytes | `[Byte]` | A list of bytes to write to the file.  | -
 979 permissions | `` | The permissions to set on the file if it is created.  | `Int32(0o644)`
 980 
 981 **Return:** Either `Success` or `Failure(reason)`.
 982 
 983 
 984 **Example:**
 985 ```tomo
 986 (./file.txt).write_bytes([104, 105])!
 987 
 988 ```
 989 ## Path.write_unique
 990 
 991 ```tomo
 992 Path.write_unique : func(path: Path, text: Text -> Path)
 993 ```
 994 
 995 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.
 996 
 997 Argument | Type | Description | Default
 998 ---------|------|-------------|---------
 999 path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name.  | -
1000 text | `Text` | The text to write to the file.  | -
1001 
1002 **Return:** The path of the newly created unique file.
1003 
1004 
1005 **Example:**
1006 ```tomo
1007 created := (./file-XXXXXX.txt).write_unique("Hello, world!")!
1008 assert created == (./file-27QHtq.txt)
1009 assert created.read()! == "Hello, world!"
1010 created.remove()!
1011 
1012 ```
1013 ## Path.write_unique_bytes
1014 
1015 ```tomo
1016 Path.write_unique_bytes : func(path: Path, bytes: [Byte] -> Path)
1017 ```
1018 
1019 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.
1020 
1021 Argument | Type | Description | Default
1022 ---------|------|-------------|---------
1023 path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name.  | -
1024 bytes | `[Byte]` | The bytes to write to the file.  | -
1025 
1026 **Return:** The path of the newly created unique file.
1027 
1028 
1029 **Example:**
1030 ```tomo
1031 created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3])!
1032 assert created == (./file-27QHtq.txt)
1033 assert created.read_bytes()! == [1, 2, 3]
1034 created.remove()!
1035 
1036 ```
1037 ## Path.writer
1038 
1039 ```tomo
1040 Path.writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(text:Text, close:Bool=no -> Result))
1041 ```
1042 
1043 Returns a function that can be used to repeatedly write to the same file.
1044 
1045 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.
1046 
1047 Argument | Type | Description | Default
1048 ---------|------|-------------|---------
1049 path | `Path` | The path of the file to write to.  | -
1050 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`
1051 permissions | `Int32` | The permissions to set on the file if it is created.  | `Int32(0o644)`
1052 
1053 **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.
1054 
1055 
1056 **Example:**
1057 ```tomo
1058 write := (./file.txt).writer()
1059 write("Hello\n")!
1060 write("world\n", close=yes)!
1061 
1062 ```