System.Path.Posix

This module provides type-safe access to filepath manipulations.

Normally you would import System.Path (which will use the default implementation for the host platform) instead of this. However, importing this explicitly allows for manipulation of non-native paths.

The main filepath (& dirpath) abstract type

data Path ar fd

This is the main filepath abstract datatype

Instances

Eq (Path ar fd)

Ord (Path ar fd)

AbsRelClass ar => Read (Path ar fd)

AbsRelClass ar => Show (Path ar fd)

IsString (Path ar fd)

Allow use of OverloadedStrings if desired

Arbitrary (Path ar Dir)

Arbitrary (Path ar File)

Phantom Types

data Abs

Instances

AbsRelClass Abs

Private Abs

data Rel

Instances

AbsRelClass Rel

Private Rel

data File

Instances

FileDirClass File

Private File

Arbitrary (Path ar File)

data Dir

Instances

FileDirClass Dir

Private Dir

Arbitrary (Path ar Dir)

Type Synonyms

type AbsFile = Path Abs File

type RelFile = Path Rel File

type AbsDir = Path Abs Dir

type RelDir = Path Rel Dir

type AbsPath fd = Path Abs fd

type RelPath fd = Path Rel fd

type FilePath ar = Path ar File

type DirPath ar = Path ar Dir

Classes

class Private ar => AbsRelClass ar where

This class allows selective behaviour for absolute and relative paths and is mostly for internal use.

Methods

absRel :: (AbsPath fd -> a) -> (RelPath fd -> a) -> Path ar fd -> a

Instances

AbsRelClass Rel

AbsRelClass Abs

class Private fd => FileDirClass fd where

This class allows selective behaviour for file and directory paths and is mostly for internal use.

Methods

fileDir :: (FilePath ar -> a) -> (DirPath ar -> a) -> Path ar fd -> a

Instances

FileDirClass Dir

FileDirClass File

Path to String conversion

getPathString :: AbsRelClass ar => Path ar fd -> String

Convert the Path into a plain String. This is simply an alias for show.

Constants

rootDir :: AbsDir

currentDir :: RelDir

Unchecked Construction Functions

asPath :: String -> Path ar fd

Use a String as a Path whose type is determined by its context.

> asPath "/tmp" == "/tmp"
> asPath "file.txt" == "file.txt"
> isAbsolute (asPath "/tmp" :: AbsDir) == True
> isAbsolute (asPath "/tmp" :: RelDir) == False
> getPathString (asPath "/tmp" :: AbsDir) == "/tmp"
> getPathString (asPath "/tmp" :: RelDir) == "tmp"

asRelFile :: String -> RelFile

Use a String as a RelFile. No checking is done.

> getPathString (asRelFile "file.txt") == "file.txt"
> getPathString (asRelFile "/file.txt") == "file.txt"
> getPathString (asRelFile "tmp") == "tmp"
> getPathString (asRelFile "/tmp") == "tmp"

asRelDir :: String -> RelDir

Use a String as a RelDir. No checking is done.

> getPathString (asRelDir "file.txt") == "file.txt"
> getPathString (asRelDir "/file.txt") == "file.txt"
> getPathString (asRelDir "tmp") == "tmp"
> getPathString (asRelDir "/tmp") == "tmp"

asAbsFile :: String -> AbsFile

Use a String as an AbsFile. No checking is done.

> getPathString (asAbsFile "file.txt") == "/file.txt"
> getPathString (asAbsFile "/file.txt") == "/file.txt"
> getPathString (asAbsFile "tmp") == "/tmp"
> getPathString (asAbsFile "/tmp") == "/tmp"

asAbsDir :: String -> AbsDir

Use a String as an AbsDir. No checking is done.

> getPathString (asAbsDir "file.txt") == "/file.txt"
> getPathString (asAbsDir "/file.txt") == "/file.txt"
> getPathString (asAbsDir "tmp") == "/tmp"
> getPathString (asAbsDir "/tmp") == "/tmp"

asRelPath :: String -> RelPath fd

Use a String as a 'RelPath fd'. No checking is done.

asAbsPath :: String -> AbsPath fd

Use a String as an 'AbsPath fd'. No checking is done.

asFilePath :: String -> FilePath ar

Use a String as a 'FilePath ar'. No checking is done.

asDirPath :: String -> DirPath ar

Use a String as a 'DirPath ar'. No checking is done.

Checked Construction Functions

mkPathAbsOrRel :: String -> Either (AbsPath fd) (RelPath fd)

Examines the supplied string and constructs an absolute or relative path as appropriate.

> either id (const "fred") (mkPathAbsOrRel "/tmp") == "/tmp"
> either id (const "fred") (mkPathAbsOrRel  "tmp") == "fred"

mkPathFileOrDir :: AbsRelClass ar => String -> IO (Maybe (Either (FilePath ar) (DirPath ar)))

Searches for a file or directory with the supplied path string and returns a File or Dir path as appropriate. If neither exists at the supplied path, Nothing is returned.

mkAbsPath :: AbsDir -> String -> AbsPath fd

Convert a String into an AbsPath by interpreting it as relative to the supplied directory if necessary.

> mkAbsPath "/tmp" "foo.txt" == "/tmp/foo.txt"
> mkAbsPath "/tmp" "/etc/foo.txt" == "/etc/foo.txt"

mkAbsPathFromCwd :: String -> IO (AbsPath fd)

Convert a String into an AbsPath by interpreting it as relative to the cwd if necessary.

Basic Manipulation Functions

(</>) :: DirPath ar -> RelPath fd -> Path ar fd

Join an (absolute or relative) directory path with a relative (file or directory) path to form a new path.

(<.>) :: FilePath ar -> String -> FilePath ar

We only allow files (and not directories) to have extensions added by this function. This is because it's the vastly common case and an attempt to add one to a directory will - more often than not - represent an error. We don't however want to prevent the corresponding operation on directories, and so we provide a function that is more flexible: genericAddExtension.

addExtension :: FilePath ar -> String -> FilePath ar

Add an extension, even if there is already one there. E.g. addExtension "foo.txt" "bat" -> "foo.txt.bat".

> addExtension "file.txt" "bib" == "file.txt.bib"
> addExtension "file." ".bib" == "file..bib"
> addExtension "file" ".bib" == "file.bib"
> takeFileName (addExtension "" "ext") == ".ext"

combine :: DirPath ar -> RelPath fd -> Path ar fd

Join an (absolute or relative) directory path with a relative (file or directory) path to form a new path.

dropExtension :: FilePath ar -> FilePath ar

Remove last extension, and the "." preceding it.

> dropExtension x == fst (splitExtension x)

dropExtensions :: FilePath ar -> FilePath ar

Drop all extensions

> not $ hasAnExtension (dropExtensions x)

dropFileName :: Path ar fd -> DirPath ar

replaceExtension :: FilePath ar -> String -> FilePath ar

Set the extension of a file, overwriting one if already present.

> replaceExtension "file.txt" ".bob" == "file.bob"
> replaceExtension "file.txt" "bob" == "file.bob"
> replaceExtension "file" ".bob" == "file.bob"
> replaceExtension "file.txt" "" == "file"
> replaceExtension "file.fred.bob" "txt" == "file.fred.txt"

replaceBaseName :: Path ar fd -> String -> Path ar fd

replaceDirectory :: Path ar1 fd -> DirPath ar2 -> Path ar2 fd

replaceFileName :: Path ar fd -> String -> Path ar fd

splitExtension :: FilePath ar -> (FilePath ar, String)

Split on the extension. addExtension is the inverse.

> uncurry (<.>) (splitExtension x) == x
> uncurry addExtension (splitExtension x) == x
> splitExtension "file.txt" == ("file",".txt")
> splitExtension "file" == ("file","")
> splitExtension "file/file.txt" == ("file/file",".txt")
> splitExtension "file.txt/boris" == ("file.txt/boris","")
> splitExtension "file.txt/boris.ext" == ("file.txt/boris",".ext")
> splitExtension "file/path.txt.bob.fred" == ("file/path.txt.bob",".fred")

splitExtensions :: FilePath ar -> (FilePath ar, String)

Split on all extensions

> splitExtensions "file.tar.gz" == ("file",".tar.gz")

splitFileName :: Path ar fd -> (DirPath ar, RelPath fd)

takeBaseName :: Path ar fd -> RelPath fd

Get the basename of a file

> takeBaseName "/tmp/somedir/myfile.txt" == "myfile"
> takeBaseName "./myfile.txt" == "myfile"
> takeBaseName "myfile.txt" == "myfile"

takeDirectory :: Path ar fd -> DirPath ar

takeExtension :: FilePath ar -> String

Get the extension of a file, returns "" for no extension, .ext otherwise.

> takeExtension x == snd (splitExtension x)
> takeExtension (addExtension x "ext") == ".ext"
> takeExtension (replaceExtension x "ext") == ".ext"

takeExtensions :: FilePath ar -> String

Get all extensions

> takeExtensions "file.tar.gz" == ".tar.gz"

takeFileName :: Path ar fd -> RelPath fd

Get the filename component of a file path (ie stripping all parent dirs)

> takeFileName "/tmp/somedir/myfile.txt" == "myfile.txt"
> takeFileName "./myfile.txt" == "myfile.txt"
> takeFileName "myfile.txt" == "myfile.txt"

Auxillary Manipulation Functions

equalFilePath :: String -> String -> Bool

Check whether two strings are equal as file paths.

> equalFilePath "/tmp/" "/tmp" == True
> equalFilePath "/tmp"  "tmp"  == False

joinPath :: [String] -> Path ar fd

Constructs a Path from a list of components.

> joinPath ["/tmp","someDir","file.txt"] == "/tmp/someDir/file.txt"
> (joinPath ["/tmp","someDir","file.txt"] :: RelFile) == "tmp/someDir/file.txt"

normalise :: Path ar fd -> Path ar fd

Currently just transforms:

> normalise "/tmp/fred/./jim/./file" == "/tmp/fred/jim/file"

splitPath :: FileDirClass fd => Path ar fd -> ([RelDir], Maybe RelFile)

Deconstructs a path into its components.

> splitPath ("/tmp/someDir/myfile.txt" :: AbsDir)  == (["tmp","someDir","myfile.txt"],Nothing)
> splitPath ("/tmp/someDir/myfile.txt" :: AbsFile) == (["tmp","someDir"],Just "myfile.txt")
> splitPath (asAbsFile "/tmp/someDir/myfile.txt")  == (["tmp","someDir"],Just "myfile.txt")

makeRelative :: AbsDir -> AbsPath fd -> RelPath fd

This function can be used to construct a relative path by removing the supplied AbsDir from the front. It is a runtime error if the supplied AbsPath doesn't start with the AbsDir.

> makeRelative "/tmp/somedir" "/tmp/somedir/anotherdir/file.txt" == "anotherdir/file.txt"

makeAbsolute :: AbsDir -> RelPath fd -> AbsPath fd

Joins an absolute directory with a relative path to construct a new absolute path.

> makeAbsolute "/tmp" "file.txt"      == "/tmp/file.txt"
> makeAbsolute "/tmp" "adir/file.txt" == "/tmp/adir/file.txt"

makeAbsoluteFromCwd :: RelPath fd -> IO (AbsPath fd)

Converts a relative path into an absolute one by prepending the current working directory.

genericMakeAbsolute :: AbsRelClass ar => AbsDir -> Path ar fd -> AbsPath fd

As for makeAbsolute, but for use when the path may already be absolute (in which case it is left unchanged).

> genericMakeAbsolute "/tmp" (asRelFile "file.txt")       == "/tmp/file.txt"
> genericMakeAbsolute "/tmp" (asRelFile "adir/file.txt")  == "/tmp/adir/file.txt"
> genericMakeAbsolute "/tmp" (asAbsFile "adir/file.txt")  == "/adir/file.txt"
> genericMakeAbsolute "/tmp" (asAbsFile "/adir/file.txt") == "/adir/file.txt"

genericMakeAbsoluteFromCwd :: AbsRelClass ar => Path ar fd -> IO (AbsPath fd)

As for makeAbsoluteFromCwd, but for use when the path may already be absolute (in which case it is left unchanged).

pathMap :: (String -> String) -> Path ar fd -> Path ar fd

Map over the components of the path.

> pathMap (map toLower) "/tmp/Reports/SpreadSheets" == "/tmp/reports/spreadsheets"

Path Predicates

isAbsolute :: AbsRelClass ar => Path ar fd -> Bool

Test whether a Path ar fd is absolute.

> isAbsolute (asAbsFile "fred")  == True
> isAbsolute (asRelFile "fred")  == False
> isAbsolute (asAbsFile "/fred") == True
> isAbsolute (asRelFile "/fred") == False

isAbsoluteString :: String -> Bool

Test whether the String would correspond to an absolute path if interpreted as a Path.

isRelative :: AbsRelClass ar => Path ar fd -> Bool

Invariant - this should return True iff arg is of type Path Rel _

 isRelative = not . isAbsolute

isRelativeString :: String -> Bool

Test whether the String would correspond to a relative path if interpreted as a Path.

 isRelativeString = not . isAbsoluteString

hasAnExtension :: FilePath ar -> Bool

Does the given filename have an extension?

> null (takeExtension x) == not (hasAnExtension x)

hasExtension :: String -> FilePath ar -> Bool

Does the given filename have the given extension?

> hasExtension ".hs" "MyCode.hs" == True
> hasExtension ".hs" "MyCode.hs.bak" == False
> hasExtension ".hs" "MyCode.bak.hs" == True

Separators

addTrailingPathSeparator :: String -> String

This is largely for System.FilePath compatability

dropTrailingPathSeparator :: String -> String

This is largely for System.FilePath compatability

extSeparator :: Char

File extension character

> extSeparator == '.'

hasTrailingPathSeparator :: String -> Bool

This is largely for System.FilePath compatability

pathSeparator :: Char

The character that separates directories. In the case where more than one character is possible, pathSeparator is the 'ideal' one.

> isPathSeparator pathSeparator

pathSeparators :: [Char]

The list of all possible separators.

> pathSeparator `elem` pathSeparators

searchPathSeparator :: Char

The character that is used to separate the entries in the $PATH environment variable.

isExtSeparator :: Char -> Bool

Is the character an extension character?

> isExtSeparator a == (a == extSeparator)

isPathSeparator :: Char -> Bool

Rather than using (== pathSeparator), use this. Test if something is a path separator.

> isPathSeparator a == (a `elem` pathSeparators)

isSearchPathSeparator :: Char -> Bool

Is the character a file separator?

> isSearchPathSeparator a == (a == searchPathSeparator)

Generic Manipulation Functions

genericAddExtension :: Path ar fd -> String -> Path ar fd

This is a more flexible variant of addExtension / <.> which can work with files or directories

> genericAddExtension "/" "x" == "/.x"

genericDropExtension :: Path ar fd -> Path ar fd

genericDropExtensions :: Path ar fd -> Path ar fd

genericSplitExtension :: Path ar fd -> (Path ar fd, String)

genericSplitExtensions :: Path ar fd -> (Path ar fd, String)

genericTakeExtension :: Path ar fd -> String

genericTakeExtensions :: Path ar fd -> String