Path
Path
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. File.read 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.
PathComponent
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"