Path

:= [
    Utf8(Str),
    UnixBytes(List(U8)),
    WindowsU16s(List(U16)),
]

Construct and operate on byte-preserving paths. Native Unix bytes and Windows UTF-16 units are preserved across host effects; use display only when a lossy human-readable representation is appropriate.

Quoted literals create UTF-8 paths, and join appends one path component:

Path.create_all!("config")?
config_file = Path.join("config", "app.json")
Path.write_utf8!(config_file, "{}")?
from_os_str : OsStr -> Path

Create a path from an OS string value, preserving raw OS units.

to_os_str : Path -> OsStr

Convert a path to an OS string value, preserving raw OS units.

is_file! : Path => Try(Bool, [PathErr(IOErr, Path)])

Returns True if the path exists on disk and is pointing at a regular file.

This function does not traverse symbolic links; symbolic links (including broken ones) return False. Sockets, FIFOs, devices, and other special filesystem objects also return False.

is_dir! : Path => Try(Bool, [PathErr(IOErr, Path)])

Returns True if the path exists on disk and is pointing at a directory.

This function does not traverse symbolic links; symbolic links (including broken ones) return False. Sockets, FIFOs, devices, and other special filesystem objects also return False.

is_sym_link! : Path => Try(Bool, [PathErr(IOErr, Path)])

Returns True if the path exists on disk and is pointing at a symbolic link.

This function will not traverse symbolic links - it checks whether the path itself is a symlink. Sockets, FIFOs, devices, and other special filesystem objects return False.

exists! : Path => Try(Bool, [PathErr(IOErr, Path)])

Returns True if the path exists on disk.

type! : Path => Try([IsFile, IsDir, IsSymLink, IsOther], [PathErr(IOErr, Path)])

Return the type of the path if the path exists on disk.

IsOther represents sockets, FIFOs, block and character devices, and any platform-specific object that is not a regular file, directory, or symbolic link. On Windows this includes unrecognized reparse-point types.

absolute! : Path => Try(Path, [PathErr(IOErr, Path)])

Make a path absolute without requiring it to exist. This does not resolve symlinks.

canonicalize! : Path => Try(Path, [PathErr(IOErr, Path)])

Resolve an existing path, including symbolic links, to its absolute native path.

copy! : Path, Path => Try({}, [CopyErr({ operation : Str, source : Path, destination : Path, error : IOErr })])

Copy a regular file and its permissions, replacing the destination file. Rejects same-file copies (including hard-link aliases) and special files.

copy_dir! : Path, Path => Try({}, [CopyErr({ operation : Str, source : Path, destination : Path, error : IOErr })])

Copy a directory tree into a new destination, following symbolic links. Missing destination parent directories are created. Permissions are preserved; timestamps, ownership, ACLs and other metadata are not. Errors may leave a partial destination. Cycles and overlapping source/destination trees are rejected.

copy_dir_with! : Path, Path, { symlinks : [Follow, Preserve], destination : [RequireNew, Merge] } => Try({}, [CopyErr({ operation : Str, source : Path, destination : Path, error : IOErr })])

Choose whether to preserve links and whether to merge an existing destination tree. Merge replaces regular files. Existing destination directory symlinks are rejected.

read_bytes! : Path => Try(List(U8), [PathErr(IOErr, Path)])

Read all bytes from a file at this path.

write_bytes! : Path, List(U8) => Try({}, [PathErr(IOErr, Path)])

Write bytes to a file at this path, replacing any existing contents.

read_utf8! : Path => Try(Str, [PathErr(IOErr, Path)])

Read a UTF-8 file at this path.

write_utf8! : Path, Str => Try({}, [PathErr(IOErr, Path)])

Write a UTF-8 file at this path, replacing any existing contents.

append_bytes! : Path, List(U8) => Try({}, [PathErr(IOErr, Path)])

Append bytes to the end of the file at this path, creating the file if it does not exist. Missing parent directories are not created.

Existing contents are never truncated or overwritten: the file is opened in append mode, so the operating system places the bytes at the current end of the file even when other writers are appending to it. The bytes are handed to the operating system in one write, which keeps appends from concurrent writers from interleaving in the common case, but this is not guaranteed for large contents or on network filesystems.

The append is not atomic or durable: a failure mid-write can leave part of the bytes appended, and nothing is flushed to the storage device before this returns.

append_utf8! : Path, Str => Try({}, [PathErr(IOErr, Path)])

Append UTF-8 text to the end of the file at this path, creating the file if it does not exist. No newline is added.

Path.append_utf8!("events.log", "started\n")?

This has the same creation, concurrency and failure behavior as [append_bytes!].

replace_utf8! : Path, Str, Str => Try({}, [PathErr(IOErr, Path)])

Replace every occurrence of pattern with replacement in the UTF-8 file at this path.

This reads the whole file, substitutes, and writes it back, so it is not atomic: a failure mid-write can leave the file partially written, exactly as a bare [write_utf8!] would.

delete! : Path => Try({}, [PathErr(IOErr, Path)])

Delete a file at this path.

size_in_bytes! : Path => Try(U64, [PathErr(IOErr, Path)])

Return the size of the file at this path in bytes.

is_executable! : Path => Try(Bool, [PathErr(IOErr, Path)])

Check whether the file at this path has any executable bit set.

is_readable! : Path => Try(Bool, [PathErr(IOErr, Path)])

Check whether the file at this path has a readable owner permission bit set.

is_writable! : Path => Try(Bool, [PathErr(IOErr, Path)])

Check whether the file at this path has a writable owner permission bit set.

time_accessed! : Path => Try(Utc, [PathErr(IOErr, Path)])

Return when the file at this path was last accessed.

Times before 1970 are returned as negative instants, not errors.

time_modified! : Path => Try(Utc, [PathErr(IOErr, Path)])

Return when the file at this path was last modified.

Times before 1970 are returned as negative instants, not errors.

stale = Utc.now!().since(path.time_modified!()?) > Duration.minutes(5)
time_created! : Path => Try(Utc, [PathErr(IOErr, Path)])

Return when the file at this path was created.

Times before 1970 are returned as negative instants, not errors. Fails with Unsupported where the filesystem does not record a creation time.

hard_link! : Path, Path => Try({}, [PathErr(IOErr, Path)])

Create a hard link at link pointing to original.

Errors report original, which is what a missing-file failure refers to. Some failures concern link instead, such as AlreadyExists.

rename! : Path, Path => Try({}, [PathErr(IOErr, Path)])

Rename a file from from to to.

Errors report from; a failure may still concern to, such as its parent directory not existing.

create_dir! : Path => Try({}, [PathErr(IOErr, Path)])

Create a directory at this path.

create_all! : Path => Try({}, [PathErr(IOErr, Path)])

Create a directory and any missing parent directories at this path.

delete_empty! : Path => Try({}, [PathErr(IOErr, Path)])

Delete an empty directory at this path.

delete_all! : Path => Try({}, [PathErr(IOErr, Path)])

Delete a directory and all contents at this path.

list! : Path => Try(List(Path), [PathErr(IOErr, Path)])

List the entries in the directory at this path.

The result is all-or-nothing: if any entry cannot be read while the directory is being listed, an error is returned instead of a partial list.

utf8 : Str -> Path

Create a UTF-8 path from a dynamic Str. String literals can be used directly wherever a Path is expected.

from_quote : Str -> Try(Path, [BadQuotedBytes(Str)])

Create a UTF-8 text path from a quoted literal.

from_interpolation : List(Str) -> Try(List(Str) -> Path, [InvalidInterpolation(Str)])

Create a UTF-8 path from an interpolated string literal. This performs textual concatenation; use join for path-component joining.

parser_for : _

Parse and encode every path representation as a lossless tagged value.

unix : Str -> Path

Create a Unix path from a Roc string by storing its UTF-8 bytes.

unix_bytes : List(U8) -> Path

Create a Unix path from raw bytes without validating UTF-8.

windows : Str -> Path

Create a Windows path from a Roc string by storing its UTF-16 code units.

to_str : Path -> Try(Str, [InvalidStr(U64)])

Convert a path to a string if its raw representation is valid text.

display : Path -> Str

Convert a path to a best-effort display string, replacing invalid text with U+FFFD. This representation is lossy and must not be used for roundtripping.

to_inspect : Path -> Str

Render a path for debugging without losing raw OS units.

is_eq : Path, Path -> Bool

Compare paths by content, whichever representation holds it.

A string literal is stored as UTF-8, while the operating system hands back native units, so Path.list!("src")?.contains("src/main.roc") compares text with native units. The rules are those of OsStr.is_eq: valid Unicode is equal when it is the same text, and invalid native units equal only identical units of the same kind.

Paths are not normalized. a/b and a\b, ./a and a, and names that differ in case or Unicode normal form are all unequal, even where the file system would treat them as one file.

filename : Path -> Try(Path, [IsDirPath, EndsInDots])

Returns everything after the last directory separator.

ext : Path -> Try(Path, [IsDirPath, EndsInDots])

Returns everything after the first dot in the filename that is not a leading dot: txt for notes.txt, tar.gz for archive.tar.gz, and nothing for .gitignore.

join : Path, Str -> Path

Adds a separator and a string component to the path.

to_raw : Path -> [Utf8(Str), UnixBytes(List(U8)), WindowsU16s(List(U16))]

Expose the raw OS-specific representation.

from_raw : [Utf8(Str), UnixBytes(List(U8)), WindowsU16s(List(U16))] -> Path

Build a path from the raw OS-specific representation.