Path

:= [
    Utf8(Str),
    Unix(List(U8)),
    Windows(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.

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), ..])

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

This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links this will return Bool.False.

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

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

This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links this will return Bool.False.

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

Returns Bool.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.

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

Returns True if the path exists on disk.

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

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

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

Read all bytes from a file at this path.

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

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

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

Read a UTF-8 file at this path.

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

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

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

Delete a file at this path.

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

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

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

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

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

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

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

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

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

Return the last accessed time as nanoseconds since the Unix epoch.

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

Return the last modified time as nanoseconds since the Unix epoch.

time_created! : Path => Try(U128, [PathErr(IOErr), ..])

Return the creation time as nanoseconds since the Unix epoch.

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

Create a hard link at link pointing to original.

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

Rename a file from from to to.

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

Create a directory at this path.

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

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

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

Delete an empty directory at this path.

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

Delete a directory and all contents at this path.

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

List the entries in the directory at this path.

utf8 : Str -> Path

Create a UTF-8 text path.

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

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

from_interpolation : Str, Iter((Str, Str)) -> Path

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

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.

windows_u16s : List(U16) -> Path

Create a Windows path from raw 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 their exact tagged representation.

to_hash : Path, Hasher -> Hasher

Hash paths consistently with exact tagged equality.

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

Returns everything after the last directory separator.

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

Returns the filename extension without the leading dot.

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.