std/fs/lib

The path the operation was about.

What went wrong, in the operating system's or the decoder's own words.

{path}: {message}.

Opens an existing file for reading.

Creates the file, or empties it if it is there. The counterpart of open, for the writing side.

The rest of the file as text, from wherever the cursor is. Fails if the bytes are not UTF-8.

Releases the operating system handle. Synchronous and cannot fail, as every Close promises.

The file as a stream of byte chunks of at most size, each read on a thread of the blocking pool so the worker goes on meanwhile. Everything above it (lines, framing, decoding) is a Stage and therefore ordinary TorbScript.

The lines of the file, as a stream. A read failure ends the stream and the reader sees it, because it is in the type - it can never be swallowed halfway through.

The writing end. A File is a Sink<Bytes, IoError>, so addText, addLine and fill are all there.

Flushes to the operating system and reports what a buffered write could only report now.

A String is always valid UTF-8, so bytes that are not are an IoError and never a replacement character.

Creates or empties path and writes text into it in one call - the writing counterpart of readText.

The whole file as bytes, synchronously: for what fits in memory, and for code that cannot wait for a task - a tool, a test, the top level of a program. read is the same for a task, and chunks() reads a file of any size.

fn sizeOf(path: String): Result<Int, IoError> {
  const bytes = File.readBytes(path)?
  Ok bytes.length()
}

Creates or empties path and writes bytes into it in one call, synchronously - the counterpart of readBytes.

The whole file as bytes, read chunk by chunk on a thread of the blocking pool so the worker goes on meanwhile: what readBytes is for a task. The counterpart of write, which takes a source: Source.from([bytes]) is one.

Creates path and writes everything source delivers into it, of any size and without holding it in memory: File.write(path, response.body.mapFailure(IoError.from)).await()?

Replaces path whole or not at all: the bytes go into a new file beside it, which is flushed to the disk and then moved over path in one step. A reader - or the program after a crash - finds the old content or the new one and never a part of either, which writeBytes cannot promise. A file that was there keeps its permissions, and where this fails nothing is left behind.

fn saveIndex(path: String, entries: List<String>): Result<Void, IoError> {
  File.writeTextAtomically path, entries.joined(separator: "\n")
}

• On Windows a file that another program holds open without allowing its deletion cannot be replaced, and the call fails; the old content stays.

File.writeBytesAtomically for text, which is always UTF-8.

The path as an absolute path, with . and .. resolved against the working directory. The file does not have to exist: this is text arithmetic, not a lookup, so it does not follow links either.

Whether something exists at path, file or directory. A symbolic link counts as what it points at.

Whether path is a directory rather than a file.

Creates the directory and every directory above it that is missing, and does nothing where it is already there - so a caller that only wants a place to write does not have to ask first.

The names of the entries of a directory, sorted.

• The directory cannot be read, or the name of one of its entries is not valid UTF-8. A String is always UTF-8, so such an entry has no name to answer: the message shows its bytes, and no replacement character is invented.

Every entry below the directory, as a path relative to it with / between the names: a directory comes before what is in it, and the entries of one directory come in the order list answers them. A symbolic link is an entry and is never followed, so a link that points back up cannot make the walk endless.

fn sources(root: String): Result<List<String>, IoError> {
  const entries = File.walk(root)?
  Ok entries.filter({ _.endsWith ".trb" }).toList()
}

Removes one file, one symbolic link - the link, never what it points at - or one empty directory. A read-only file is removed as well, on Windows too. Fails where nothing is there.

Removes the directory and everything in it, and does nothing where nothing is there - the counterpart of createDirectory, which does nothing where the directory is already there. A symbolic link inside is removed and never followed, so nothing outside the directory is touched; path itself being a link removes the link.

• path is a file, or something inside cannot be removed. What was removed before that stays removed.

Moves path to to in one step, replacing a file that is at to - which is what makes it the last step of every replacement that must not be seen half done. Both have to be on one volume: across volumes a move is a copy and a remove, and no system does that in one step.

Copies the content and the permissions of the file path to to, which is created or replaced. A symbolic link is followed; a directory is refused.

What path is, how large, when it was last written and who may do what with it - of what a symbolic link points at, the way every other function here follows one. linkMetadata describes the link itself.

fn isNewer(first: String, second: String): Result<Bool, IoError> {
  const one = File.metadata(first)?
  const other = File.metadata(second)?
  Ok(one.modified > other.modified)
}

File.metadata of a symbolic link itself rather than of what it points at: the one way to see that a path is a link.

Sets the permission bits of path. On Windows only the owner's write bit counts: without it the file is read-only, and with it it is not.

Creates a symbolic link at path whose target is target, stored exactly as written: a relative target is read from the directory of the link, not from the working directory.

• Windows lets a program create one only in developer mode or with the privilege to; without either this fails with Operation not permitted, and a program that must run everywhere copies instead.

The target of the symbolic link at path as it was stored, with / between its names on every system.

Creates a new, empty file with a name nobody else has - prefix and twelve letters and digits - and answers its path. It is created where nothing was, so no other program can have it too, and on POSIX only its owner may read it. It lives in inside, or in the system's directory for temporary files; removing it is the caller's.

fn scratch(content: String): Result<String, IoError> {
  const path = File.createTemporaryFile(prefix: "report-")?
  File.writeText(path, content)?
  Ok path
}

Creates a new, empty directory with a name nobody else has, the way File.createTemporaryFile creates a file, and answers its path. removeDirectory removes it with everything that was put into it.