code / tomo

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