The main Path type.

The type variable b is either:

• Abs -- absolute path (starting with a "/")
• Rel -- relative path (not starting with a "/")

Internally it is a ByteString. The path is guaranteed to be normalised and contain no trailing Path separators, except for the "/" root path.

There are no duplicate path separators "//", no "..", no "./", etc.

Two special paths exist:

• "/" -- the rootPath (absolute)
• "." -- the pwdPath (relative)

The constructor is not exposed. Instead, use the smart constructors parseAbs, parseRel and parseAny.

An absolute path.

A relative path; one without a root.

Exception when parsing a location.

Get a location for an absolute path. Produces a normalised path.

Throws: PathParseException

>>> parseAbs "/abc"
"/abc"
>>> parseAbs "/"
"/"
>>> parseAbs "/abc/def"
"/abc/def"
>>> parseAbs "/abc/def/.///"
"/abc/def"
>>> parseAbs "abc"
*** Exception: InvalidAbs "abc"
>>> parseAbs ""
*** Exception: InvalidAbs ""
>>> parseAbs "/abc/../foo"
*** Exception: InvalidAbs "/abc/../foo"

Get a location for a relative path. Produces a normalised path.

Note that filepath may contain any number of ./, but not a single .. anywhere.

Throws: PathParseException

>>> parseRel "abc"
"abc"
>>> parseRel "def/"
"def"
>>> parseRel "abc/def"
"abc/def"
>>> parseRel "abc/def/."
"abc/def"
>>> parseRel "/abc"
*** Exception: InvalidRel "/abc"
>>> parseRel ""
*** Exception: InvalidRel ""
>>> parseRel "abc/../foo"
*** Exception: InvalidRel "abc/../foo"
>>> parseRel "."
"."
>>> parseRel "././././."
"."
>>> parseRel "./..."
"..."
>>> parseRel ".."
*** Exception: InvalidRel ".."

Parses a path, whether it's relative or absolute.

Throws: PathParseException

>>> parseAny "/abc"
Left "/abc"
>>> parseAny "..."
Right "..."
>>> parseAny "abc/def"
Right "abc/def"
>>> parseAny "abc/def/."
Right "abc/def"
>>> parseAny "/abc"
Left "/abc"
>>> parseAny ""
*** Exception: InvalidRel ""
>>> parseAny "abc/../foo"
*** Exception: InvalidRel "abc/../foo"
>>> parseAny "."
Right "."
>>> parseAny ".."
*** Exception: InvalidRel ".."

The "/" root path.

The "." pwd path.

Convert an absolute Path to a ByteString type.

Convert a relative Path to a ByteString type.

Convert any Path to a ByteString type.

Append two paths.

The second argument must always be a relative path, which ensures that undefinable things like `"abc" <> "/def"` cannot happen.

Technically, the first argument can be a path that points to a non-directory, because this library is IO-agnostic and makes no assumptions about file types.

>>> [abs|/|] </> [rel|file|]
"/file"
>>> [abs|/path/to|] </> [rel|file|]
"/path/to/file"
>>> [abs|/|] </> [rel|file/lal|]
"/file/lal"
>>> [abs|/|] </> [rel|.|]
"/"
>>> [rel|.|] </> [rel|.|]
"."

Extract the file part of a path.

The following properties hold:

basename (p </> a) == basename a

Throws: PathException if given the root path "/"

>>> basename [abs|/abc/def/dod|]
"dod"
>>> basename [rel|abc/def/dod|]
"dod"
>>> basename [rel|dod|]
"dod"
>>> basename [rel|.|]
"."
>>> basename [abs|/|]
*** Exception: RootDirHasNoBasename

Extract the file part of a relative path.

The following properties hold:

basename' (p </> a) == basename' a

>>> basename' [rel|abc/def/dod|]
"dod"
>>> basename' [rel|dod|]
"dod"
>>> basename' [rel|.|]
"."

Extract the directory name of a path.

>>> dirname [abs|/abc/def/dod|]
"/abc/def"
>>> dirname [abs|/|]
"/"

Get all parents of a path.

>>> getAllParents [abs|/abs/def/dod|]
["/abs/def","/abs","/"]
>>> getAllParents [abs|/foo|]
["/"]
>>> getAllParents [abs|/|]
[]

Gets all path components.

>>> getAllComponents [rel|abs/def/dod|]
["abs","def","dod"]
>>> getAllComponents [rel|abs|]
["abs"]
>>> getAllComponents [rel|.|]
["."]

Gets all path components after the "/" root directory.

>>> getAllComponentsAfterRoot [abs|/abs/def/dod|]
["abs","def","dod"]
>>> getAllComponentsAfterRoot [abs|/abs|]
["abs"]

Strip directory from path, making it relative to that directory. Throws Couldn'tStripPrefixDir if directory is not a parent of the path.

The bases must match.

>>> [abs|/lal/lad|]     `stripDir` [abs|/lal/lad/fad|]
"fad"
>>> [rel|lal/lad|]      `stripDir` [rel|lal/lad/fad|]
"fad"
>>> [abs|/|]            `stripDir` [abs|/|]
"."
>>> [abs|/lal/lad/fad|] `stripDir` [abs|/lal/lad|]
*** Exception: Couldn'tStripPrefixTPS "/lal/lad/fad" "/lal/lad"
>>> [abs|/abs|]         `stripDir` [abs|/lal/lad|]
*** Exception: Couldn'tStripPrefixTPS "/abs" "/lal/lad"
>>> [rel|fad|]          `stripDir` [rel|fad|]
"."
>>> [rel|.|]            `stripDir` [rel|.|]
"."
>>> [rel|.|]            `stripDir` [rel|.foo|]
*** Exception: Couldn'tStripPrefixTPS "." ".foo"

Is p a parent of the given location? Implemented in terms of stripDir. The bases must match.

>>> [abs|/lal/lad|]     `isParentOf` [abs|/lal/lad/fad|]
True
>>> [rel|lal/lad|]      `isParentOf` [rel|lal/lad/fad|]
True
>>> [abs|/|]            `isParentOf` [abs|/|]
False
>>> [abs|/lal/lad/fad|] `isParentOf` [abs|/lal/lad|]
False
>>> [rel|fad|]          `isParentOf` [rel|fad|]
False
>>> [rel|.|]            `isParentOf` [rel|.foo|]
False

Check whether the given Path is the root "/" path.

>>> isRootPath [abs|/lal/lad|]
False
>>> isRootPath [abs|/|]
True

Check whether the given Path is the pwd "." path.

>>> isPwdPath [rel|lal/lad|]
False
>>> isPwdPath [rel|.|]
True

Quasiquote an absolute Path. This accepts Unicode Chars and will encode as UTF-8.

>>> [abs|/etc/profile|] :: Path Abs
"/etc/profile"
>>> [abs|/|] :: Path Abs
"/"
>>> [abs|/|] :: Path Abs
"/\239\131\144"

Quasiquote a relative Path. This accepts Unicode Chars and will encode as UTF-8.

>>> [rel|etc|] :: Path Rel
"etc"
>>> [rel|bar/baz|] :: Path Rel
"bar/baz"
>>> [rel||] :: Path Rel
"\239\131\144"