Path.accessed:
  short: access time
  description: >
    Gets the file access time of a file.
  return:
    type: 'Int64?'
    description: >
      A 64-bit unix epoch timestamp representing when the file or directory was last
      accessed, or `none` if no such file or directory exists.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file whose access time you want.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./file.txt).accessed() == Int64(1704221100)
    assert (./not-a-file).accessed() == none

Path.append:
  short: append to a file
  description: >
    Appends the given text to the file at the specified path, creating the file if
    it doesn't already exist. Failure to write will result in a runtime error.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to append to.
    text:
      type: 'Text'
      description: >
        The text to append to the file.
    permissions:
      type: 'Int32'
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is being created.
  example: |
    (./log.txt).append("extra line\n")!

Path.append_bytes:
  short: append bytes to a file
  description: >
    Appends the given bytes to the file at the specified path, creating the file if
    it doesn't already exist. Failure to write will result in a runtime error.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to append to.
    bytes:
      type: '[Byte]'
      description: >
        The bytes to append to the file.
    permissions:
      type: 'Int32'
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is being created.
  example: |
    (./log.txt).append_bytes([104, 105])!

Path.base_name:
  short: base name of a file
  description: >
    Returns the base name of the file or directory at the specified path.
  return:
    type: 'Text'
    description: >
      The base name of the file or directory.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file or directory.
  example: |
    assert (./path/to/file.txt).base_name() == "file.txt"

Path.by_line:
  short: iterate by line
  description: >
    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.
  return:
    type: 'func(->Text?)?'
    description: >
      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.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file.
  example: |
    # Safely handle file not being readable:
    if lines := (./file.txt).by_line()
        for line in lines
            say(line.upper())
    else
        say("Couldn't read file!")

    # Assume the file is readable and error if that's not the case:
    for line in (/dev/stdin).by_line()!
        say(line.upper())

Path.components:
  short: Get the components of a path
  description: >
    Returns a list of the file components of a path.
  return:
    type: '[Text]'
    description: >
      Each of the file components of the path in a list. Note: for absolute
      paths, the first component will be "/". Trailing slashes are ignored.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file or directory.
  example: |
    assert (./foo/baz.txt).components() == [".", "foo", "baz.txt"]
    assert (/absolute/path/).components() == ["/", "absolute", "path"]

Path.lines:
  short: return the lines in a file
  description: >
    Returns a list with the lines of text in a file or returns none if the file
    could not be opened.
  return:
    type: '[Text]?'
    description: >
      A list of the lines in a file or none if the file couldn't be read.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file.
  example: |
    lines := (./file.txt).lines()!

Path.can_execute:
  short: check execute permissions
  description: >
    Returns whether or not a file can be executed by the current user/group.
  return:
    type: 'Bool'
    description: >
      `yes` if the file or directory exists and the current user has execute permissions, otherwise `no`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to check.
  example: |
    assert (/bin/sh).can_execute() == yes
    assert (/usr/include/stdlib.h).can_execute() == no
    assert (/non/existant/file).can_execute() == no

Path.can_read:
  short: check read permissions
  description: >
    Returns whether or not a file can be read by the current user/group.
  return:
    type: 'Bool'
    description: >
      `yes` if the file or directory exists and the current user has read permissions, otherwise `no`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to check.
  example: |
    assert (/usr/include/stdlib.h).can_read() == yes
    assert (/etc/shadow).can_read() == no
    assert (/non/existant/file).can_read() == no

Path.can_write:
  short: check write permissions
  description: >
    Returns whether or not a file can be written by the current user/group.
  return:
    type: 'Bool'
    description: >
      `yes` if the file or directory exists and the current user has write permissions, otherwise `no`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to check.
  example: |
    assert (/tmp).can_write() == yes
    assert (/etc/passwd).can_write() == no
    assert (/non/existant/file).can_write() == no

Path.changed:
  short: get the last changed time
  description: >
    Gets the file change time of a file.
  note: >
    This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file,
    which is _not_ the file creation time.
  return:
    type: 'Int64?'
    description: >
      A 64-bit unix epoch timestamp representing when the file or directory was last
      changed, or `none` if no such file or directory exists.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file whose change time you want.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./file.txt).changed() == Int64(1704221100)
    assert (./not-a-file).changed() == none

Path.child:
  short: append a child to a path
  description: >
    Return a path that is a child of another path.
  return:
    type: 'Path'
    description: >
      A new path representing the child.
  args:
    path:
      type: 'Path'
      description: >
        The path of a directory.
    child:
      type: 'Text'
      description: >
        The name of a child file or directory.
  example: |
    assert (./directory).child("file.txt") == (./directory/file.txt)

Path.children:
  short: get children of a directory
  description: >
    Returns a list of children (files and directories) within the directory at
    the specified path. Optionally includes hidden files. Child ordering is not
    specified.
  return:
    type: '[Path]'
    description: >
      A list of paths for the children.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory.
    include_hidden:
      default: 'no'
      description: >
        Whether to include hidden files (those starting with a `.`).
  example: |
    assert (./directory).children(include_hidden=yes) == [(./directory/.git), (./directory/foo.txt)]

Path.copy_to:
  short: copy a file or directory
  description: >
    Copies the file or directory from one location to another. This is the same
    behavior as `cp -r -T src dest` or `cp -rf -T src dest` (if `overwrite` is
    enabled).
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path to copy.
    dest:
      type: 'Path'
      description: >
        The destination to copy the path to.
    overwrite:
      default: 'no'
      description: >
        Whether to permit overwriting the destination if it is an existing file or directory.
  example: |
    (./file.txt).move(/tmp/renamed.txt)!

Path.create_directory:
  short: make a directory
  description: >
    Creates a new directory at the specified path with the given permissions. If
    any of the parent directories do not exist, they will be created as needed.
  note: >
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory to create.
    permissions:
      default: 'Int32(0o755)'
      description: >
        The permissions to set on the new directory.
    recursive:
      default: 'yes'
      description: >
        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`.
  example: |
    (./new_directory).create_directory()!

Path.current_dir:
  short: get current directory
  description: >
    Creates a new directory at the specified path with the given permissions. If
    any of the parent directories do not exist, they will be created as needed.
  return:
    type: 'Path'
    description: >
      The absolute path of the current directory.
  args:
  example: |
    assert Path.current_dir() == (/home/user/tomo)

Path.each_child:
  short: iterate over children of a directory
  description: >
    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.
  return:
    type: 'func(->Path?)?'
    description: >
      An iterator over the children in a directory or `none` if the path is not
      a directory or a symlink to a directory.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory.
    include_hidden:
      default: 'no'
      description: >
        Whether to include hidden files (those starting with a `.`).
  example: |
    for child in (/dir).each_child()
        say("Child: $child")

Path.exists:
  short: check if a path exists
  description: >
    Checks if a file or directory exists at the specified path.
  return:
    type: 'Bool'
    description: >
      `True` if the file or directory exists, `False` otherwise.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
  example: |
    assert (/).exists() == yes

Path.expand_home:
  short: 'expand ~ to $HOME'
  description: >
    For home-based paths (those starting with `~`), expand the path to replace the
    tilde with and absolute path to the user's `$HOME` directory.
  return:
    type: 'Path'
    description: >
      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.
  args:
    path:
      type: 'Path'
      description: >
        The path to expand.
  example: |
    # Assume current user is 'user'
    assert (~/foo).expand_home() == (/home/user/foo)
    # No change
    assert (/foo).expand_home() == (/foo)

Path.extension:
  short: get file extension
  description: >
    Returns the file extension of the file at the specified path. Optionally returns the full extension.
  return:
    type: 'Text'
    description: >
      The file extension (not including the leading `.`) or an empty text if there is
      no file extension.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file.
    full:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to return everything after the first `.` in the base name, or
        only the last part of the extension.
  example: |
    assert (./file.tar.gz).extension() == "tar.gz"
    assert (./file.tar.gz).extension(full=no) == "gz"
    assert (/foo).extension() == ""
    assert (./.git).extension() == ""

Path.files:
  short: list files in a directory
  description: >
    Returns a list of files within the directory at the specified path. Optionally includes hidden files.
  return:
    type: '[Path]'
    description: >
      A list of file paths.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory.
    include_hidden:
      type: 'Bool'
      default: 'no'
      description: >
        Whether to include hidden files (those starting with a `.`).
  example: |
    assert (./directory).files(include_hidden=yes) == [(./directory/file1.txt), (./directory/file2.txt)]

Path.glob:
  short: perform file globbing
  description: >
    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 `*`, but will match `.*`.

    - Globs do support `{a,b}` syntax for matching files that match any of several
      choices of patterns.

    - The shell-style syntax `**` for matching subdirectories is not supported.
  return:
    type: '[Path]'
    description: >
      A list of file paths that match the glob.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory which may contain special globbing characters
        like `*`, `?`, or `{...}`
  example: |
    # Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden
    assert (./*).glob() == [(./foo.txt), (./baz.txt), (./qux.jpg)]
    assert (./*.txt).glob() == [(./foo.txt), (./baz.txt)]
    assert (./*.{txt,jpg}).glob() == [(./foo.txt), (./baz.txt), (./qux.jpg)]
    assert (./.*).glob() == [(./.hidden)]

    # Globs with no matches return an empty list:
    assert (./*.xxx).glob() == []

Path.group:
  short: get the owning group
  description: >
    Get the owning group of a file or directory.
  return:
    type: 'Text?'
    description: >
      The name of the group which owns the file or directory, or `none` if the path does not exist.
  args:
    path:
      type: 'Path'
      description: >
        The path whose owning group to get.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (/bin).group() == "root"
    assert (/non/existent/file).group() == none

Path.has_extension:
  short: check if a path has a given extension
  description: >
    Return whether or not a path has a given file extension.
  return:
    type: 'Bool'
    description: >
      Whether or not the path has the given extension.
  args:
    path:
      type: 'Path'
      description: >
        A path.
    extension:
      type: 'Text'
      description: >
        A file extension (leading `.` is optional). If empty, the check will
        test if the file does not have any file extension.
  example: |
    assert (/foo.txt).has_extension("txt") == yes
    assert (/foo.txt).has_extension(".txt") == yes
    assert (/foo.tar.gz).has_extension("gz") == yes
    assert (/foo.tar.gz).has_extension("zip") == no

Path.is_directory:
  short: check if a path is a directory
  description: >
    Checks if the path represents a directory. Optionally follows symbolic links.
  return:
    type: 'Bool'
    description: >
      `True` if the path is a directory, `False` otherwise.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
    follow_symlinks:
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./directory/).is_directory() == yes
    assert (./file.txt).is_directory() == no

Path.is_file:
  short: check if a path is a file
  description: >
    Checks if the path represents a file. Optionally follows symbolic links.
  return:
    type: 'Bool'
    description: >
      `True` if the path is a file, `False` otherwise.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
    follow_symlinks:
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./file.txt).is_file() == yes
    assert (./directory/).is_file() == no

Path.is_socket:
  short: check if a path is a socket
  description: >
    Checks if the path represents a socket. Optionally follows symbolic links.
  return:
    type: 'Bool'
    description: >
      `True` if the path is a socket, `False` otherwise.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
    follow_symlinks:
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./socket).is_socket() == yes

Path.is_symlink:
  short: check if a path is a symbolic link
  description: >
    Checks if the path represents a symbolic link.
  return:
    type: 'Bool'
    description: >
      `True` if the path is a symbolic link, `False` otherwise.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
  example: |
    assert (./link).is_symlink() == yes

Path.matches_glob:
  short: check if a path matches a glob
  description: >
    Return whether or not a path matches a given glob.
  return:
    type: 'Bool'
    description: >
      Whether or not the path matches the given glob.
  args:
    path:
      type: 'Path'
      description: >
        The path to check.
    glob:
      type: 'Text'
      description: >
        The glob pattern to check.
  example: |
    assert (./file.txt).matches_glob("*.txt")
    assert (./file.c).matches_glob("*.{c,h}")

Path.modified:
  short: get file modification time
  description: >
    Gets the file modification time of a file.
  return:
    type: 'Int64?'
    description: >
      A 64-bit unix epoch timestamp representing when the file or directory was last
      modified, or `none` if no such file or directory exists.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file whose modification time you want.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (./file.txt).modified() == Int64(1704221100)
    assert (./not-a-file).modified() == none

Path.move:
  short: move a file or directory
  description: >
    Moves the file or directory from one location to another.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path to move.
    dest:
      type: 'Path'
      description: >
        The destination to move the path to.
    overwrite:
      default: 'no'
      description: >
        Whether to permit overwriting the destination if it is an existing file or directory.
  example: |
    (./file.txt).move(/tmp/renamed.txt)!

Path.owner:
  short: get file owner
  description: >
    Get the owning user of a file or directory.
  return:
    type: 'Text?'
    description: >
      The name of the user who owns the file or directory, or `none` if the path does not exist.
  args:
    path:
      type: 'Path'
      description: >
        The path whose owner to get.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    assert (/bin).owner() == "root"
    assert (/non/existent/file).owner() == none

Path.parent:
  short: get parent directory
  description: >
    Returns the parent directory of the file or directory at the specified path.
  return:
    type: 'Path?'
    description: >
      The path of the parent directory or `none` if the path is `(/)` (the file root).
  args:
    path:
      type: 'Path'
      description: >
        The path of the file or directory.
  example: |
    assert (./path/to/file.txt).parent() == (./path/to/)

Path.read:
  short: read file contents
  description: >
    Reads the contents of the file at the specified path or none if the file
    could not be read.
  return:
    type: 'Text?'
    description: >
      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.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to read.
  example: |
    assert (./hello.txt).read() == "Hello"
    assert (./nosuchfile.xxx).read() == none

Path.read_bytes:
  short: read file contents as bytes
  description: >
    Reads the contents of the file at the specified path or none if the file
    could not be read.
  return:
    type: '[Byte]?'
    description: >
      The byte contents of the file. If the file cannot be read, none will be
      returned.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to read.
    limit:
      type: 'Int?'
      default: 'none'
      description: >
        A limit to how many bytes should be read.
  example: |
    assert (./hello.txt).read_bytes()! == [72, 101, 108, 108, 111]
    assert (./nosuchfile.xxx).read_bytes() == none

Path.relative_to:
  short: apply a relative path to another
  description: >
    Returns the path relative to a given base path. By default, the base path is the current directory.
  return:
    type: 'Path'
    description: >
      A relative path from the reference point to the given path.
  args:
    path:
      type: 'Path'
      description: >
        The path to convert.
    relative_to:
      default: '(./)'
      description: >
        The base path for the relative path.
  example: |
    assert (./path/to/file.txt).relative_to((./path)) == (./to/file.txt)
    assert (/tmp/foo).relative_to((/tmp)) == (./foo)

Path.remove:
  short: remove a file or directory
  description: >
    Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path to remove.
    ignore_missing:
      default: 'no'
      description: >
        Whether to ignore errors if the file or directory does not exist.
  example: |
    (./file.txt).remove()!

Path.resolved:
  short: resolve a path
  description: >
    Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
  return:
    type: 'Path'
    description: >
      The resolved absolute path.
  args:
    path:
      type: 'Path'
      description: >
        The path to resolve.
    relative_to:
      default: '(./)'
      description: >
        The base path for resolution.
  example: |
    assert (~/foo).resolved() == (/home/user/foo)
    assert (./path/to/file.txt).resolved(relative_to=(/foo)) == (/foo/path/to/file.txt)

Path.set_owner:
  short: set the owner
  description: >
    Set the owning user and/or group for a path.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path to change the permissions for.
    owner:
      type: 'Text?'
      default: 'none'
      description: >
        If non-none, the new user to assign to be the owner of the file.
    group:
      type: 'Text?'
      default: 'none'
      description: >
        If non-none, the new group to assign to be the owner of the file.
    follow_symlinks:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to follow symbolic links.
  example: |
    (./file.txt).set_owner(owner="root", group="wheel")!

Path.sibling:
  short: get another path in the same directory
  description: >
    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)`
  return:
    type: 'Path'
    description: >
      A new path representing the sibling.
  args:
    path:
      type: 'Path'
      description: >
        A path.
    name:
      type: 'Text'
      description: >
        The name of a sibling file or directory.
  example: |
    assert (/foo/baz).sibling("doop") == (/foo/doop)

Path.subdirectories:
  short: get subdirectories
  description: >
    Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
  return:
    type: '[Path]'
    description: >
      A list of subdirectory paths.
  args:
    path:
      type: 'Path'
      description: >
        The path of the directory.
    include_hidden:
      default: 'no'
      description: >
        Whether to include hidden subdirectories (those starting with a `.`)
  example: |
    assert (./directory).subdirectories() == [(./directory/subdir1), (./directory/subdir2)]
    assert (./directory).subdirectories(include_hidden=yes) == [(./directory/.git), (./directory/subdir1), (./directory/subdir2)]

Path.unique_directory:
  short: create a directory with a unique name
  description: >
    Generates a unique directory path based on the given path. Useful for creating temporary directories.
  return:
    type: 'Path'
    description: >
      A unique directory path after creating the directory.
  args:
    path:
      type: 'Path'
      description: >
        The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`.
  example: |
    created := (/tmp/my-dir.XXXXXX).unique_directory()
    assert created.is_directory() == yes
    created.remove()!

Path.walk:
  short: walk a filetree
  description: >
    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.
  note: >
    The path itself is always included in the iteration.
  return:
    type: 'func(->Path?)'
    description: >
      An iterator that recursively walks over every file and subdirectory.
  args:
    path:
      type: 'Path'
      description: >
        The path to begin the walk.
    include_hidden:
      default: 'no'
      description: >
        Whether to include hidden files (those starting with a `.`)
    follow_symlinks:
      type: 'Bool'
      default: 'no'
      description: >
        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.
  example: |
    for p in (/tmp).walk()
        say("File or dir: $p")

    # The path itself is always included:
    assert [p for p in (./file.txt).walk()] == [(./file.txt)]

Path.write:
  short: write to a file
  description: >
    Writes the given text to the file at the specified path, creating the file if
    it doesn't already exist. Sets the file permissions as specified. If the file
    writing cannot be successfully completed, a runtime error is raised.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to write to.
    text:
      type: 'Text'
      description: >
        The text to write to the file.
    permissions:
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is created.
  example: |
    (./file.txt).write("Hello, world!")!

Path.writer:
  short: create a file writer
  description: >
    Returns a function that can be used to repeatedly write to the same file.
  note: >
    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.
  return:
    type: 'func(text:Text, close:Bool=no -> Result)'
    description: >
      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.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to write to.
    append:
      type: 'Bool'
      default: 'no'
      description: >
        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.
    permissions:
      type: 'Int32'
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is created.
  example: |
    write := (./file.txt).writer()
    write("Hello\n")!
    write("world\n", close=yes)!

Path.byte_writer:
  short: create a byte-based file writer
  description: >
    Returns a function that can be used to repeatedly write bytes to the same
    file.
  note: >
    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.
  return:
    type: 'func(bytes:[Byte], close:Bool=no -> Result)'
    description: >
      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.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to write to.
    append:
      type: 'Bool'
      default: 'no'
      description: >
        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.
    permissions:
      type: 'Int32'
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is created.
  example: |
    write := (./file.txt).byte_writer()
    write("Hello\n".utf8())!
    write("world\n".utf8(), close=yes)!


Path.write_bytes:
  short: write bytes to a file
  description: >
    Writes the given bytes to the file at the specified path, creating the file if
    it doesn't already exist. Sets the file permissions as specified. If the file
    writing cannot be successfully completed, a runtime error is raised.
  return:
    type: 'Result'
    description: >
      Either `Success` or `Failure(reason)`.
  args:
    path:
      type: 'Path'
      description: >
        The path of the file to write to.
    bytes:
      type: '[Byte]'
      description: >
        A list of bytes to write to the file.
    permissions:
      default: 'Int32(0o644)'
      description: >
        The permissions to set on the file if it is created.
  example: |
    (./file.txt).write_bytes([104, 105])!

Path.write_unique:
  short: write to a uniquely named file
  description: >
    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.
  return:
    type: 'Path'
    description: >
      The path of the newly created unique file.
  args:
    path:
      type: 'Path'
      description: >
        The base path for generating the unique file. This path must include
        the string `XXXXXX` in the file base name.
    text:
      type: 'Text'
      description: >
        The text to write to the file.
  example: |
    created := (./file-XXXXXX.txt).write_unique("Hello, world!")!
    assert created == (./file-27QHtq.txt)
    assert created.read()! == "Hello, world!"
    created.remove()!

Path.write_unique_bytes:
  short: write bytes to a uniquely named file
  description: >
    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.
  return:
    type: 'Path'
    description: >
      The path of the newly created unique file.
  args:
    path:
      type: 'Path'
      description: >
        The base path for generating the unique file. This path must include
        the string `XXXXXX` in the file base name.
    bytes:
      type: '[Byte]'
      description: >
        The bytes to write to the file.
  example: |
    created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3])!
    assert created == (./file-27QHtq.txt)
    assert created.read_bytes()! == [1, 2, 3]
    created.remove()!