Represents a path to a file or directory on the filesystem.

CanonicalizeErr a : [PathCanonicalizeErr {}]a

Represents an error that can happen when canonicalizing a path.

fromStr : Str -> Path

Note that the path may not be valid depending on the filesystem where it is used. For example, paths containing : are valid on ext4 and NTFS filesystems, but not on FAT ones. So if you have multiple disks on the same machine, but they have different filesystems, then this path could be valid on one but invalid on another!

It's safest to assume paths are invalid (even syntactically) until given to an operation which uses them to open a file. If that operation succeeds, then the path was valid (at the time). Otherwise, error handling can happen for that operation rather than validating up front for a false sense of security (given symlinks, parts of a path being renamed, etc.).

fromBytes : List U8 -> Path

Not all filesystems use Unicode paths. This function can be used to create a path which is not valid Unicode (like a Str is), but which is valid for a particular filesystem.

Note that if the list contains any 0 bytes, sending this path to any file operations (e.g. or WriteStream.openPath) will fail.

display : Path -> Str

Unfortunately, operating system paths do not include information about which charset they were originally encoded with. It's most common (but not guaranteed) that they will have been encoded with the same charset as the operating system's curent locale (which typically does not change after it is set during installation of the OS), so this should convert a Path to a valid string as long as the path was created with the given Charset. (Use Env.charset to get the current system charset.)

For a conversion to Str that is lossy but does not return a Result, see display. toInner : Path -> Str Str, Bytes (List U8) Assumes a path is encoded as UTF-8, and converts it to a string using Str.display.

This conversion is lossy because the path may contain invalid UTF-8 bytes. If that happens, any invalid bytes will be replaced with the Unicode replacement character instead of returning an error. As such, it's rarely a good idea to use the Str returned by this function for any purpose other than displaying it to a user.

When you don't know for sure what a path's encoding is, UTF-8 is a popular guess because it's the default on UNIX and also is the encoding used in Roc strings. This platform also automatically runs applications under the UTF-8 code page on Windows.

Converting paths to strings can be an unreliable operation, because operating systems don't record the paths' encodings. This means it's possible for the path to have been encoded with a different character set than UTF-8 even if UTF-8 is the system default, which means when display converts them to a string, the string may include gibberish. Here is an example.

If you happen to know the Charset that was used to encode the path, you can use toStrUsingCharset instead of display.


Represents a attributes of a path such as a parent directory, the current directory for use when transforming a path.

WindowsRoot : []

Represents the root path on Windows operating system, which refers to the current disk drive.

withExtension : Path, Str -> Path

If the last component of this path has no ., appends . followed by the given string. Otherwise, replaces everything after the last . with the given string.

# Each of these gives "foo/bar/baz.txt"
Path.fromStr "foo/bar/baz" |> Path.withExtension "txt"
Path.fromStr "foo/bar/baz." |> Path.withExtension "txt"
Path.fromStr "foo/bar/baz.xz" |> Path.withExtension "txt"