Path of some base and type.

The type variables are:

• b — base, the base location of the path; absolute or relative.
• t — type, whether file or directory.

Internally is a string. The string can be of two formats only:

1. File format: file.txt, foo/bar.txt, /foo/bar.txt
2. Directory format: foo/, /foo/bar/

All directories end in a trailing separator. There are no duplicate path separators //, no .., no ./, no ~/, etc.

An absolute path.

A relative path; one without a root. Note that a .. path component to represent the parent directory is not allowed by this library.

A file path.

A directory path.

Exceptions that can occur during path operations.

Since: 0.6.0

Construct a Path Abs Dir using QuasiQuotes.

[absdir|/|]

[absdir|/home/chris|]

Remember: due to the nature of absolute paths a path like [absdir|/home/chris|] may compile on your platform, but it may not compile on another platform (Windows).

Since: 0.5.13

Construct a Path Rel Dir using QuasiQuotes.

[absdir|/home|]</>[reldir|chris|]

Since: 0.5.13

Construct a Path Abs File using QuasiQuotes.

[absfile|/home/chris/foo.txt|]

Remember: due to the nature of absolute paths a path like [absdir|/home/chris/foo.txt|] may compile on your platform, but it may not compile on another platform (Windows).

Since: 0.5.13

Construct a Path Rel File using QuasiQuotes.

[absdir|/home/chris|]</>[relfile|foo.txt|]

Since: 0.5.13

Append two paths.

The following cases are valid and the equalities hold:

$(mkAbsDir x) </> $(mkRelDir y) = $(mkAbsDir (x ++ "/" ++ y))

$(mkAbsDir x) </> $(mkRelFile y) = $(mkAbsFile (x ++ "/" ++ y))

$(mkRelDir x) </> $(mkRelDir y) = $(mkRelDir (x ++ "/" ++ y))

$(mkRelDir x) </> $(mkRelFile y) = $(mkRelFile (x ++ "/" ++ y))

The following are proven not possible to express:

$(mkAbsFile …) </> x

$(mkRelFile …) </> x

x </> $(mkAbsFile …)

x </> $(mkAbsDir …)

If the directory in the first argument is a proper prefix of the path in the second argument strip it from the second argument, generating a path relative to the directory. Throws NotAProperPrefix if the directory is not a proper prefix of the path.

The following properties hold:

stripProperPrefix x (x </> y) = y

Cases which are proven not possible:

stripProperPrefix (a :: Path Abs …) (b :: Path Rel …)

stripProperPrefix (a :: Path Rel …) (b :: Path Abs …)

In other words the bases must match.

Since: 0.6.0

Determines if the path in the first parameter is a proper prefix of the path in the second parameter.

The following properties hold:

not (x `isProperPrefixOf` x)

x `isProperPrefixOf` (x </> y)

Since: 0.6.0

Take the parent path component from a path.

The following properties hold:

parent (x </> y) == x
parent "/x" == "/"
parent "x" == "."

On the root (absolute or relative), getting the parent is idempotent:

parent "/" = "/"
parent "." = "."

Extract the file part of a path.

The following properties hold:

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

Extract the last directory name of a path.

The following properties hold:

dirname $(mkRelDir ".") == $(mkRelDir ".")

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

Add extension to given file path.

>>> addExtension ".foo"   $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo"    )
>>> addExtension ".foo."  $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo."   )
>>> addExtension ".foo.." $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo.."  )
>>> addExtension ".foo"   $(mkRelFile "name.bar" ) == Just $(mkRelFile "name.bar.foo")
>>> addExtension ".foo"   $(mkRelFile ".name"    ) == Just $(mkRelFile ".name.foo"   )
>>> addExtension ".foo"   $(mkRelFile "name."    ) == Just $(mkRelFile "name..foo"   )
>>> addExtension ".foo"   $(mkRelFile "..."      ) == Just $(mkRelFile "....foo"     )

Throws an InvalidExtension exception if the extension is not valid. A valid extension starts with a . followed by one or more characters not including . followed by zero or more . in trailing position. Moreover, an extension must be a valid filename, notably it cannot include path separators. Particularly, .foo.bar is an invalid extension, instead you have to first set .foo and then .bar individually. Some examples of invalid extensions are:

>>> addExtension "foo"      $(mkRelFile "name")
>>> addExtension "..foo"    $(mkRelFile "name")
>>> addExtension ".foo.bar" $(mkRelFile "name")
>>> addExtension ".foo/bar" $(mkRelFile "name")

Since: 0.7.0

splitExtension is the inverse of addExtension. It splits the given file path into a valid filename and a valid extension.

>>> splitExtension $(mkRelFile "name.foo"     ) == Just ($(mkRelFile "name"    ), ".foo"  )
>>> splitExtension $(mkRelFile "name.foo."    ) == Just ($(mkRelFile "name"    ), ".foo." )
>>> splitExtension $(mkRelFile "name.foo.."   ) == Just ($(mkRelFile "name"    ), ".foo..")
>>> splitExtension $(mkRelFile "name.bar.foo" ) == Just ($(mkRelFile "name.bar"), ".foo"  )
>>> splitExtension $(mkRelFile ".name.foo"    ) == Just ($(mkRelFile ".name"   ), ".foo"  )
>>> splitExtension $(mkRelFile "name..foo"    ) == Just ($(mkRelFile "name."   ), ".foo"  )
>>> splitExtension $(mkRelFile "....foo"      ) == Just ($(mkRelFile "..."     ), ".foo"  )

Throws HasNoExtension exception if the filename does not have an extension or in other words it cannot be split into a valid filename and a valid extension. The following cases throw an exception, please note that "." and ".." are not valid filenames:

>>> splitExtension $(mkRelFile "name"   )
>>> splitExtension $(mkRelFile "name."  )
>>> splitExtension $(mkRelFile "name.." )
>>> splitExtension $(mkRelFile ".name"  )
>>> splitExtension $(mkRelFile "..name" )
>>> splitExtension $(mkRelFile "...name")

splitExtension and addExtension are inverses of each other, the following laws hold:

uncurry addExtension . swap >=> splitExtension == return
splitExtension >=> uncurry addExtension . swap == return

Since: 0.7.0

Get extension from given file path. Throws HasNoExtension exception if the file does not have an extension. The following laws hold:

flip addExtension file >=> fileExtension == return
fileExtension == (fmap snd) . splitExtension

Since: 0.5.11

If the file has an extension replace it with the given extension otherwise add the new extension to it. Throws an InvalidExtension exception if the new extension is not a valid extension (see fileExtension for validity rules).

The following law holds:

(fileExtension >=> flip replaceExtension file) file == return file

Since: 0.7.0

Convert an absolute FilePath to a normalized absolute dir Path.

Throws: InvalidAbsDir when the supplied path:

• is not an absolute path
• contains a .. path component representing the parent directory
• is not a valid path (See isValid)

Convert a relative FilePath to a normalized relative dir Path.

Throws: InvalidRelDir when the supplied path:

• is not a relative path
• is ""
• contains a .. path component representing the parent directory
• is not a valid path (See isValid)
• is all path separators

Convert an absolute FilePath to a normalized absolute file Path.

Throws: InvalidAbsFile when the supplied path:

• is not an absolute path

• is a directory path i.e.

  • has a trailing path separator
  • is . or ends in /.
• contains a .. path component representing the parent directory
• is not a valid path (See isValid)

Convert a relative FilePath to a normalized relative file Path.

Throws: InvalidRelFile when the supplied path:

• is not a relative path
• is ""

• is a directory path i.e.

  • has a trailing path separator
  • is . or ends in /.
• contains a .. path component representing the parent directory
• is not a valid path (See isValid)

Convert to a FilePath type.

All directories have a trailing slash, so if you want no trailing slash, you can use dropTrailingPathSeparator from the filepath package.

Convert absolute path to directory to FilePath type.

Convert relative path to directory to FilePath type.

Convert absolute path to file to FilePath type.

Convert relative path to file to FilePath type.

Make a Path Abs Dir.

Remember: due to the nature of absolute paths this (e.g. /home/foo) may compile on your platform, but it may not compile on another platform (Windows).

Make a Path Rel Dir.

Make a Path Abs File.

Remember: due to the nature of absolute paths this (e.g. /home/foo) may compile on your platform, but it may not compile on another platform (Windows).

Make a Path Rel File.

Same as PathException.

Same as stripProperPrefix.

Same as isProperPrefixOf.

Add extension to given file path. Throws if the resulting filename does not parse.

>>> addFileExtension "txt $(mkRelFile "foo")
"foo.txt"
>>> addFileExtension "symbols" $(mkRelFile "Data.List")
"Data.List.symbols"
>>> addFileExtension ".symbols" $(mkRelFile "Data.List")
"Data.List.symbols"
>>> addFileExtension "symbols" $(mkRelFile "Data.List.")
"Data.List..symbols"
>>> addFileExtension ".symbols" $(mkRelFile "Data.List.")
"Data.List..symbols"
>>> addFileExtension "evil/" $(mkRelFile "Data.List")
*** Exception: InvalidRelFile "Data.List.evil/"

Since: 0.6.1

A synonym for addFileExtension in the form of an infix operator. See more examples there.

>>> $(mkRelFile "Data.List") <.> "symbols"
"Data.List.symbols"
>>> $(mkRelFile "Data.List") <.> "evil/"
*** Exception: InvalidRelFile "Data.List.evil/"

Since: 0.6.1

Replace/add extension to given file path. Throws if the resulting filename does not parse.

Since: 0.5.11

A synonym for setFileExtension in the form of an operator.

Since: 0.6.0