Documentation

ReadErr

Tag union of possible errors when reading a file or directory.

WriteErr

Tag union of possible errors when writing a file or directory.

write : Path, val, fmt -> Task {} [FileWriteErr Path WriteErr] where val implements Encoding, fmt implements EncoderFormatting

Write data to a file.

First encode a val using a given fmt which implements the ability Encode.EncoderFormatting.

For example, suppose you have a Json.toCompactUtf8 which implements Encode.EncoderFormatting. You can use this to write JSON data to a file like this:

# Writes `{"some":"json stuff"}` to the file `output.json`:
File.write
    (Path.fromStr "output.json")
    { some: "json stuff" }
    Json.toCompactUtf8

This opens the file first and closes it after writing to it. If writing to the file fails, for example because of a file permissions issue, the task fails with WriteErr.

To write unformatted bytes to a file, you can use File.writeBytes instead.

writeBytes : Path, List U8 -> Task {} [FileWriteErr Path WriteErr]

Writes bytes to a file.

# Writes the bytes 1, 2, 3 to the file `myfile.dat`.
File.writeBytes (Path.fromStr "myfile.dat") [1, 2, 3]

This opens the file first and closes it after writing to it.

To format data before writing it to a file, you can use File.write instead.

writeUtf8 : Path, Str -> Task {} [FileWriteErr Path WriteErr]

Writes a Str to a file, encoded as UTF-8.

# Writes "Hello!" encoded as UTF-8 to the file `myfile.txt`.
File.writeUtf8 (Path.fromStr "myfile.txt") "Hello!"

This opens the file first and closes it after writing to it.

To write unformatted bytes to a file, you can use File.writeBytes instead.

delete : Path -> Task {} [FileWriteErr Path WriteErr]

Deletes a file from the filesystem.

Performs a DeleteFile on Windows and unlink on UNIX systems. On Windows, this will fail when attempting to delete a readonly file; the file's readonly permission must be disabled before it can be successfully deleted.

# Deletes the file named
File.delete (Path.fromStr "myfile.dat") [1, 2, 3]

This does not securely erase the file's contents from disk; instead, the operating system marks the space it was occupying as safe to write over in the future. Also, the operating system may not immediately mark the space as free; for example, on Windows it will wait until the last file handle to it is closed, and on UNIX, it will not remove it until the last hard link to it has been deleted.

readBytes : Path -> Task (List U8) [FileReadErr Path ReadErr]

Reads all the bytes in a file.

# Read all the bytes in `myfile.txt`.
File.readBytes (Path.fromStr "myfile.txt")

This opens the file first and closes it after reading its contents.

To read and decode data from a file, you can use File.read instead.

readUtf8 : Path -> Task Str [ FileReadErr Path ReadErr, FileReadUtf8Err Path ]

Reads a Str from a file containing UTF-8-encoded text.

# Reads UTF-8 encoded text into a Str from the file "myfile.txt"
File.readUtf8 (Path.fromStr "myfile.txt")

This opens the file first and closes it after writing to it. The task will fail with FileReadUtf8Err if the given file contains invalid UTF-8.

To read unformatted bytes from a file, you can use File.readBytes instead.

writeErrToStr : WriteErr -> Str

Converts a WriteErr to a Str.

readErrToStr : ReadErr -> Str

Converts a ReadErr to a Str.