A type representing file system paths on Posix.

A PosixPath is validated before construction unless unsafe constructors are used to create it. For validations performed by the safe construction methods see the fromChars function.

Note that in some cases the file system may perform unicode normalization on paths (e.g. Apple HFS), it may cause surprising results as the path used by the user may not have the same bytes as later returned by the file system.

If the type a b is a member of IsPath it means we know how to convert the type b to and from the base type a.

Convert a path type to another path type. This operation may fail with a PathException when converting a less restrictive path type to a more restrictive one. This can be used to upgrade or downgrade type safety.

Unsafe, truncates the Char to Word8 on Posix and Word16 on Windows.

Unsafe, should be a valid character.

Checks whether the filepath is valid; i.e., whether the operating system permits such a path for listing or creating files. These validations are operating system specific and file system independent. Throws an exception with a detailed explanation if the path is invalid.

>>> isValid = isJust . Path.validatePath . Path.encodeString

Validations:

>>> isValid ""
False
>>> isValid "\0"
False

Other than these there may be maximum path component length and maximum path length restrictions enforced by the OS as well as the filesystem which we do not validate.

Returns True if the filepath is valid:

>>> isValidPath = isJust . Path.validatePath

Convert an encoded array of Word8 into a value of type PosixPath. The path is validated using validatePath.

Each Word8 should be encoded such that:

• The input does not contain a NUL word.
• Values from 1-128 are assumed to be ASCII characters.

Apart from the above, there are no restrictions on the encoding.

To bypass path validation checks, use unsafeFromArray.

Throws InvalidPath if validatePath fails on the resulting path.

Unsafe: The user is responsible to make sure that the path is valid as per validatePath.

Like fromString but a streaming operation.

>>> fromString = Path.fromChars . Stream.fromList

We do not sanitize the path i.e. we do not remove duplicate separators, redundant . segments, trailing separators etc because that would require unnecessary checks and modifications to the path which may not be used ever for any useful purpose, it is only needed for path equality and can be done during the equality check.

Unicode normalization is not done. If normalization is needed the user can normalize it and then use the fromArray API.

Encode a Unicode character string to PosixPath using strict UTF-8 encoding. The path is validated using validatePath.

• Throws InvalidPath if validatePath fails on the path
• Fails if the stream contains invalid unicode characters

Like fromString but a pure and partial function that throws an InvalidPath exception.

Create an array from a path string using strict UTF-8 encoding. The path is not validated, therefore, it may not be valid according to validatePath.

Same as toArray . unsafeFromString.

Like fromString but does not perform any validations mentioned under validatePath. Fails only if unicode encoding fails.

Generates a Haskell expression of type PosixPath from a String. Equivalent to using fromString on the string passed.

Convert the path to an array.

Decode the path to a stream of Unicode chars using strict UTF-8 decoding.

Decode the path to a stream of Unicode chars using lax UTF-8 decoding.

Decode the path to a Unicode string using strict UTF-8 decoding.

Use the path as a pinned CString. Useful for using a PosixPath in system calls on Posix.

Decode the path to a Unicode string using lax UTF-8 decoding.

Show the path as raw characters without any specific decoding.

See also: readArray.

The primary path separator word: / on POSIX and \ on Windows. Windows also supports / as a valid separator. Use isSeparator to check for any valid path separator.

On POSIX, only / is a path separator, whereas on Windows both / and \ are valid separators.

File extension separator word.

Remove all trailing path separators from the given Path.

Instead of this operation you may want to use eqPath with ignoreTrailingSeparators option.

This operation is careful not to alter the semantic meaning of the path. For example, on Windows:

• Dropping the separator from "C:/" would change the meaning of the path from referring to the root of the C: drive to the current directory on C:.
• If a path ends with a separator immediately after a colon (e.g., "C:/"), the separator will not be removed.

If the input path is invalid, the behavior is not fully guaranteed:

• The separator may still be dropped.
• In some cases, dropping the separator may make an invalid path valid (e.g., "C:\\" or "C:\/").

This operation may convert a path that implicitly refers to a directory into one that does not.

Typically, if the path is dir//, the result is dir. Special cases include:

• On POSIX: dropping from "//" yields "/".
• On Windows: dropping from "C://" results in "C:/".

Examples:

>>> f = Path.toString . Path.dropTrailingSeparators . Path.fromString_
>>> f "./"
"."

> f "//"  -- On POSIX

"/"

Returns True if the path ends with a trailing separator.

This typically indicates that the path is a directory, though this is not guaranteed in all cases.

Example:

>>> Path.hasTrailingSeparator (Path.fromString_ "foo/")
True

>>> Path.hasTrailingSeparator (Path.fromString_ "foo")
False

Add a trailing path separator to a path if it doesn't already have one.

Instead of this operation you may want to use eqPath with ignoreTrailingSeparators option.

This function avoids modifying the path if doing so would change its meaning or make it invalid. For example, on Windows:

• Adding a separator to "C:" would change it from referring to the current directory on the C: drive to the root directory.
• Adding a separator to "\" could turn it into a UNC share path, which may not be intended.
• If the path ends with a colon (e.g., "C:"), a separator is not added.

This operation typically makes the path behave like an implicit directory path.

A path that is attached to a root e.g. "/x" or "./x" are rooted paths. "/" is considered an absolute root and "." as a dynamic root. ".." is not considered a root, "../x" or "x/y" are not rooted paths.

>>> isRooted = Path.isRooted . Path.fromString_

>>> isRooted "/"
True
>>> isRooted "/x"
True
>>> isRooted "."
True
>>> isRooted "./x"
True

A path that is not attached to a root e.g. a/b/c or ../b/c.

>>> isUnrooted = not . Path.isRooted

>>> isUnrooted = Path.isUnrooted . Path.fromString_

>>> isUnrooted "x"
True
>>> isUnrooted "x/y"
True
>>> isUnrooted ".."
True
>>> isUnrooted "../x"
True

Append a separator followed by the supplied string to a path.

Throws InvalidPath if the resulting path is not a valid path as per validatePath.

Like join but does not check if the second path is rooted.

>>> f a b = Path.toString $ Path.unsafeJoin (Path.fromString_ a) (Path.fromString_ b)

>>> f "x" "y"
"x/y"
>>> f "x/" "y"
"x/y"
>>> f "x" "/y"
"x/y"
>>> f "x/" "/y"
"x/y"

Append a separator and a CString to the Array. This is like unsafeJoin but always inserts a separator between the two paths even if the first path has a trailing separator or second path has a leading separator.

Like joinCStr but creates a pinned path.

Append a separator followed by another path to a PosixPath. Fails if the second path is a rooted path. Use unsafeJoin to avoid failure if you know it is ok to append the rooted path.

>>> f a b = Path.toString $ Path.join a b

>>> f [path|/usr|] [path|bin|]
"/usr/bin"
>>> f [path|/usr/|] [path|bin|]
"/usr/bin"
>>> fails (f [path|/usr|] [path|/bin|])
True

A stricter version of join which requires the first path to be a directory like path i.e. having a trailing separator.

>>> f a b = Path.toString $ Path.joinDir a b

>>> fails $ f [path|/usr|] [path|bin|]
True

Join paths by path separator. Does not check if the paths being appended are rooted or branches. Note that splitting and joining may not give exactly the original path but an equivalent path.

Unimplemented

If a path is rooted then separate the root and the remaining path, otherwise return Nothing. The non-root part is guaranteed to NOT start with a separator.

Some filepath package equivalent idioms:

>>> splitDrive = Path.splitRoot
>>> joinDrive = Path.unsafeJoin
>>> takeDrive = fmap fst . Path.splitRoot
>>> dropDrive x = Path.splitRoot x >>= snd
>>> hasDrive = isJust . Path.splitRoot
>>> isDrive = isNothing . dropDrive

>>> toList (a,b) = (Path.toString a, fmap Path.toString b)
>>> split = fmap toList . Path.splitRoot . Path.fromString_

>>> split "/"
Just ("/",Nothing)

>>> split "."
Just (".",Nothing)

>>> split "./"
Just ("./",Nothing)

>>> split "/home"
Just ("/",Just "home")

>>> split "//"
Just ("//",Nothing)

>>> split "./home"
Just ("./",Just "home")

>>> split "home"
Nothing

Split the path components keeping separators between path components attached to the dir part. Redundant separators are removed, only the first one is kept. Separators are not added either e.g. "." and ".." may not have trailing separators if the original path does not.

>>> split = Stream.toList . fmap Path.toString . Path.splitPath . Path.fromString_

>>> split "."
["."]

>>> split "././"
["./"]

>>> split "./a/b/."
["./","a/","b/"]

>>> split ".."
[".."]

>>> split "../"
["../"]

>>> split "a/.."
["a/",".."]

>>> split "/"
["/"]

>>> split "//"
["/"]

>>> split "/x"
["/","x"]

>>> split "/./x/"
["/","x/"]

>>> split "/x/./y"
["/","x/","y"]

>>> split "/x/../y"
["/","x/","../","y"]

>>> split "/x///y"
["/","x/","y"]

>>> split "/x/\\y"
["/","x/","\\y"]

Split a path into components separated by the path separator. "." components in the path are ignored except when in the leading position. Trailing separators in non-root components are dropped.

>>> split = Stream.toList . fmap Path.toString . Path.splitPath_ . Path.fromString_

>>> split "."
["."]

>>> split "././"
["."]

>>> split ".//"
["."]

>>> split "//"
["/"]

>>> split "//x/y/"
["/","x","y"]

>>> split "./a"
[".","a"]

>>> split "a/."
["a"]

>>> split "/"
["/"]

>>> split "/x"
["/","x"]

>>> split "/./x/"
["/","x"]

>>> split "/x/./y"
["/","x","y"]

>>> split "/x/../y"
["/","x","..","y"]

>>> split "/x///y"
["/","x","y"]

>>> split "/x/\\y"
["/","x","\\y"]

If the path does not look like a directory then return Just (Maybe dir, file) otherwise return Nothing. The path is not a directory if:

• the path does not end with a separator
• the path does not end with a . or .. component

Splits a single component path into Just (Nothing, path) if it does not look like a dir.

>>> toList (a,b) = (fmap Path.toString a, Path.toString b)
>>> split = fmap toList . Path.splitFile . Path.fromString_

>>> split "/"
Nothing

>>> split "."
Nothing

>>> split "/."
Nothing

>>> split ".."
Nothing

> split "//" -- Posix

Nothing

>>> split "/home"
Just (Just "/","home")

>>> split "./home"
Just (Just "./","home")

>>> split "home"
Just (Nothing,"home")

>>> split "x/"
Nothing

>>> split "x/y"
Just (Just "x/","y")

>>> split "x//y"
Just (Just "x//","y")

>>> split "x/./y"
Just (Just "x/./","y")

Split the path into the first component and rest of the path. Treats the entire root or share name, if present, as the first component.

Unimplemented

Split the path into the last component and rest of the path. Treats the entire root or share name, if present, as the first component.

>>> basename = snd . Path.splitLast -- Posix basename
>>> dirname = fst . Path.splitLast -- Posix dirname

Unimplemented

Returns Just(filename, extension) if an extension is present otherwise returns Nothing.

A file name is considered to have an extension if the file name can be split into a non-empty filename followed by the extension separator "." followed by a non-empty extension with at least one character in addition to the extension separator. The shortest suffix obtained by this rule, starting with the extension separator, is returned as the extension and the remaining prefix part as the filename.

A directory name does not have an extension.

If you want a splitExtensions, you can use splitExtension until the extension returned is Nothing. dropExtensions, isExtensionOf can be implemented similarly.

>>> toList (a,b) = (Path.toString a, Path.toString b)
>>> split = fmap toList . Path.splitExtension . Path.fromString_

>>> split "/"
Nothing

>>> split "."
Nothing

>>> split ".."
Nothing

>>> split "x"
Nothing

>>> split "/x"
Nothing

>>> split "x/"
Nothing

>>> split "./x"
Nothing

>>> split "x/."
Nothing

>>> split "x/y."
Nothing

>>> split "/x.y"
Just ("/x",".y")

>>> split "/x.y."
Nothing

>>> split "/x.y.."
Nothing

>>> split "x/.y"
Nothing

>>> split ".x"
Nothing

>>> split "x."
Nothing

>>> split ".x.y"
Just (".x",".y")

>>> split "x/y.z"
Just ("x/y",".z")

>>> split "x.y.z"
Just ("x.y",".z")

>>> split "x..y"
Just ("x.",".y")

>>> split "..."
Nothing

>>> split "..x"
Just (".",".x")

>>> split "...x"
Just ("..",".x")

>>> split "x/y.z/"
Nothing

>>> split "x/y"
Nothing

Drop the extension of a file if it has one.

>>> dropExtension p = maybe p fst $ Path.splitExtension p

>>> Path.toString $ Path.dropExtension [path|/home/user/file.txt|]
"/home/user/file"

Add an extension to a file path. If a non-empty extension does not start with a leading dot then a dot is inserted, otherwise the extension is concatenated with the path.

It is an error to add an extension to a path with a trailing separator.

Unimplemented

Extracts the file name component (with extension) from a PosixPath, if present.

>>> takeFileName = fmap snd . Path.splitFile
>>> replaceDirectory p x = fmap (flip Path.join x) (takeFileName p)

>>> fmap Path.toString $ Path.takeFileName [path|/home/user/file.txt|]
Just "file.txt"
>>> fmap Path.toString $ Path.takeFileName [path|/home/user/|]
Nothing

See splitFile for more examples.

Returns the parent directory of the given PosixPath, if any.

>>> takeDirectory x = Path.splitFile x >>= fst
>>> replaceFileName p x = fmap (flip Path.join x) (takeDirectory p)

To get an equivalent to takeDirectory from filepath use dropTrailingSeparators on the result.

>>> fmap Path.toString $ Path.takeDirectory [path|/home/user/file.txt|]
Just "/home/user/"
>>> fmap Path.toString $ Path.takeDirectory [path|file.txt|]
Nothing

Take the extension of a file if it has one.

>>> takeExtension = fmap snd . Path.splitExtension
>>> hasExtension = isJust . Path.splitExtension

>>> fmap Path.toString $ Path.takeExtension [path|/home/user/file.txt|]
Just ".txt"

See splitExtension for more examples.

Extracts the file name dropping the extension, if any, from a PosixPath.

>>> takeFileBase = fmap Path.dropExtension . Path.takeFileName

>>> fmap Path.toString $ Path.takeFileBase [path|/home/user/file.txt|]
Just "file"
>>> fmap Path.toString $ Path.takeFileBase [path|/home/user/file|]
Just "file"
>>> fmap Path.toString $ Path.takeFileBase [path|/home/user/.txt|]
Just ".txt"
>>> fmap Path.toString $ Path.takeFileBase [path|/home/user/|]
Nothing

See splitFile for more examples.

Options for path comparison operation. By default path comparison uses a strict criteria for equality. The following options are provided to control the strictness.

The default configuration is as follows:

>>> :{
defaultMod = ignoreTrailingSeparators False
           . ignoreCase False
           . allowRelativeEquality False
:}

When set to False (default):

>>> cfg = Path.ignoreTrailingSeparators False
>>> eq a b = Path.eqPath cfg (Path.fromString_ a) (Path.fromString_ b)

>>> eq "x/"  "x"
False

When set to True:

>>> cfg = Path.ignoreTrailingSeparators True
>>> eq a b = Path.eqPath cfg (Path.fromString_ a) (Path.fromString_ b)

>>> eq "x/"  "x"
True

Default: False

When set to False, comparison is case sensitive.

Posix Default: False

Windows Default: True

Allow relative paths to be treated as equal. When this is False relative paths will never match even if they are literally equal e.g. "./x" will not match "./x" because the meaning of "." in both cases could be different depending on what the user meant by current directory in each case.

When set to False (default):

>>> cfg = Path.allowRelativeEquality False
>>> eq a b = Path.eqPath cfg (Path.fromString_ a) (Path.fromString_ b)
>>> eq "."  "."
False
>>> eq "./x"  "./x"
False
>>> eq "./x"  "x"
False

When set to False (default):

>>> cfg = Path.allowRelativeEquality True
>>> eq a b = Path.eqPath cfg (Path.fromString_ a) (Path.fromString_ b)
>>> eq "."  "."
True
>>> eq "./x"  "./x"
True
>>> eq "./x"  "x"
True

>>> eq "./x"  "././x"
True

Default: False

Checks whether two paths are logically equal. This function takes a configuration modifier to customize the notion of equality. For using the default configuration pass id as the modifier. For details about the defaults, see EqCfg.

eqPath performs some normalizations on the paths before comparing them, specifically it drops redundant path separators between path segments and redundant "/./" components between segments.

Default config options use strict equality, for strict equality both the paths must be absolute or both must be path segments without a leading root component (e.g. x/y). Also, both must be files or both must be directories.

In addition to the default config options, the following equality semantics are used:

• An absolute path and a path relative to "." may be equal depending on the meaning of ".", however this routine treats them as unequal, it does not resolve the "." to a concrete path.
• Two paths having ".." components may be equal after processing the ".." components even if we determined them to be unequal. However, if we determined them to be equal then they must be equal.

Using default config with case sensitive comparision, if eqPath returns equal then the paths are definitely equal, if it returns unequal then the paths may still be equal under some relaxed equality criterion.

>>> :{
 eq a b = Path.eqPath id (Path.fromString_ a) (Path.fromString_ b)
:}

>>> eq "x"  "x"
True
>>> eq ".."  ".."
True

Non-trailing separators and non-leading "." segments are ignored:

>>> eq "/x"  "//x"
True
>>> eq "x//y"  "x/y"
True
>>> eq "x/./y"  "x/y"
True
>>> eq "x/y/."  "x/y"
True

Leading dot, relative paths are not equal by default:

>>> eq "."  "."
False
>>> eq "./x"  "./x"
False
>>> eq "./x"  "x"
False

Trailing separators are significant by default:

>>> eq "x/"  "x"
False

Match is case sensitive by default:

>>> eq "x"  "X"
False

Check two paths for byte level equality. This is the most strict path equality check.

>>> eqPath a b = Path.eqPathBytes (Path.fromString_ a) (Path.fromString_ b)

>>> eqPath "x//y"  "x//y"
True

>>> eqPath "x//y"  "x/y"
False

>>> eqPath "x/./y"  "x/y"
False

>>> eqPath "x\\y" "x/y"
False

>>> eqPath "./file"  "file"
False

>>> eqPath "file/"  "file"
False

Convert the path to an equivalent but standard format for reliable comparison. This can be implemented if required. Usually, the equality operations should be enough and this may not be needed.

Unimplemented