System.Posix.FilePath

The equivalent of System.FilePath on raw (byte string) file paths.

Not all functions of System.FilePath are implemented yet. Feel free to contribute!

Separator predicates

pathSeparator :: Word8

Path separator character

isPathSeparator :: Word8 -> Bool

Check if a character is the path separator

\n ->  (_chr n == '/') == isPathSeparator n

searchPathSeparator :: Word8

Search path separator

isSearchPathSeparator :: Word8 -> Bool

Check if a character is the search path separator

\n -> (_chr n == ':') == isSearchPathSeparator n

extSeparator :: Word8

File extension separator

isExtSeparator :: Word8 -> Bool

Check if a character is the file extension separator

\n -> (_chr n == '.') == isExtSeparator n

$PATH methods

splitSearchPath :: ByteString -> [RawFilePath]

Take a ByteString, split it on the searchPathSeparator. Blank items are converted to ..

Follows the recommendations in http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html

>>> splitSearchPath "File1:File2:File3"
["File1","File2","File3"]
>>> splitSearchPath "File1::File2:File3"
["File1",".","File2","File3"]
>>> splitSearchPath ""
["."]

getSearchPath :: IO [RawFilePath]

Get a list of RawFilePaths in the $PATH variable.

Extension functions

splitExtension :: RawFilePath -> (RawFilePath, ByteString)

Split a RawFilePath into a path+filename and extension

>>> splitExtension "file.exe"
("file",".exe")
>>> splitExtension "file"
("file","")
>>> splitExtension "/path/file.tar.gz"
("/path/file.tar",".gz")

\path -> uncurry (BS.append) (splitExtension path) == path

takeExtension :: RawFilePath -> ByteString

Get the final extension from a RawFilePath

>>> takeExtension "file.exe"
".exe"
>>> takeExtension "file"
""
>>> takeExtension "/path/file.tar.gz"
".gz"

replaceExtension :: RawFilePath -> ByteString -> RawFilePath

Change a file's extension

\path -> let ext = takeExtension path in replaceExtension path ext == path

dropExtension :: RawFilePath -> RawFilePath

Drop the final extension from a RawFilePath

>>> dropExtension "file.exe"
"file"
>>> dropExtension "file"
"file"
>>> dropExtension "/path/file.tar.gz"
"/path/file.tar"

addExtension :: RawFilePath -> ByteString -> RawFilePath

Add an extension to a RawFilePath

>>> addExtension "file" ".exe"
"file.exe"
>>> addExtension "file.tar" ".gz"
"file.tar.gz"
>>> addExtension "/path/" ".ext"
"/path/.ext"

hasExtension :: RawFilePath -> Bool

Check if a RawFilePath has an extension

>>> hasExtension "file"
False
>>> hasExtension "file.tar"
True
>>> hasExtension "/path.part1/"
False

(<.>) :: RawFilePath -> ByteString -> RawFilePath

Operator version of addExtension

splitExtensions :: RawFilePath -> (RawFilePath, ByteString)

Split a RawFilePath on the first extension.

>>> splitExtensions "/path/file.tar.gz"
("/path/file",".tar.gz")

\path -> uncurry addExtension (splitExtensions path) == path

dropExtensions :: RawFilePath -> RawFilePath

Remove all extensions from a RawFilePath

>>> dropExtensions "/path/file.tar.gz"
"/path/file"

takeExtensions :: RawFilePath -> ByteString

Take all extensions from a RawFilePath

>>> takeExtensions "/path/file.tar.gz"
".tar.gz"

stripExtension :: ByteString -> RawFilePath -> Maybe RawFilePath

Drop the given extension from a FilePath, and the "." preceding it. Returns Nothing if the FilePath does not have the given extension, or Just and the part before the extension if it does.

This function can be more predictable than dropExtensions, especially if the filename might itself contain . characters.

>>> stripExtension "hs.o" "foo.x.hs.o"
Just "foo.x"
>>> stripExtension "hi.o" "foo.x.hs.o"
Nothing
>>> stripExtension ".c.d" "a.b.c.d"
Just "a.b"
>>> stripExtension ".c.d" "a.b..c.d"
Just "a.b."
>>> stripExtension "baz"  "foo.bar"
Nothing
>>> stripExtension "bar"  "foobar"
Nothing

\path -> stripExtension "" path == Just path

\path -> dropExtension path  == fromJust (stripExtension (takeExtension path) path)

\path -> dropExtensions path == fromJust (stripExtension (takeExtensions path) path)

Filename/directory functions

splitFileName :: RawFilePath -> (RawFilePath, RawFilePath)

Split a RawFilePath into (path,file). combine is the inverse

>>> splitFileName "path/file.txt"
("path/","file.txt")
>>> splitFileName "path/"
("path/","")
>>> splitFileName "file.txt"
("./","file.txt")

\path -> uncurry combine (splitFileName path) == path || fst (splitFileName path) == "./"

takeFileName :: RawFilePath -> RawFilePath

Get the file name

>>> takeFileName "path/file.txt"
"file.txt"
>>> takeFileName "path/"
""

replaceFileName :: RawFilePath -> ByteString -> RawFilePath

Change the file name

\path -> replaceFileName path (takeFileName path) == path

dropFileName :: RawFilePath -> RawFilePath

Drop the file name

>>> dropFileName "path/file.txt"
"path/"
>>> dropFileName "file.txt"
"./"

takeBaseName :: RawFilePath -> ByteString

Get the file name, without a trailing extension

>>> takeBaseName "path/file.tar.gz"
"file.tar"
>>> takeBaseName ""
""

replaceBaseName :: RawFilePath -> ByteString -> RawFilePath

Change the base name

>>> replaceBaseName "path/file.tar.gz" "bob"
"path/bob.gz"

\path -> replaceBaseName path (takeBaseName path) == path

takeDirectory :: RawFilePath -> RawFilePath

Get the directory, moving up one level if it's already a directory

>>> takeDirectory "path/file.txt"
"path"
>>> takeDirectory "file"
"."
>>> takeDirectory "/path/to/"
"/path/to"
>>> takeDirectory "/path/to"
"/path"

replaceDirectory :: RawFilePath -> ByteString -> RawFilePath

Change the directory component of a RawFilePath

\path -> replaceDirectory path (takeDirectory path) `equalFilePath` path || takeDirectory path == "."

combine :: RawFilePath -> RawFilePath -> RawFilePath

Join two paths together

>>> combine "/" "file"
"/file"
>>> combine "/path/to" "file"
"/path/to/file"
>>> combine "file" "/absolute/path"
"/absolute/path"

(</>) :: RawFilePath -> RawFilePath -> RawFilePath

Operator version of combine

splitPath :: RawFilePath -> [RawFilePath]

Split a path into a list of components:

>>> splitPath "/path/to/file.txt"
["/","path/","to/","file.txt"]

\path -> BS.concat (splitPath path) == path

joinPath :: [RawFilePath] -> RawFilePath

Join a split path back together

\path -> joinPath (splitPath path) == path

>>> joinPath ["path","to","file.txt"]
"path/to/file.txt"

splitDirectories :: RawFilePath -> [RawFilePath]

Like splitPath, but without trailing slashes

>>> splitDirectories "/path/to/file.txt"
["/","path","to","file.txt"]
>>> splitDirectories ""
[]

Trailing slash functions

hasTrailingPathSeparator :: RawFilePath -> Bool

Check if the last character of a RawFilePath is /.

>>> hasTrailingPathSeparator "/path/"
True
>>> hasTrailingPathSeparator "/"
True
>>> hasTrailingPathSeparator "/path"
False

addTrailingPathSeparator :: RawFilePath -> RawFilePath

Add a trailing path separator.

>>> addTrailingPathSeparator "/path"
"/path/"
>>> addTrailingPathSeparator "/path/"
"/path/"
>>> addTrailingPathSeparator "/"
"/"

dropTrailingPathSeparator :: RawFilePath -> RawFilePath

Remove a trailing path separator

>>> dropTrailingPathSeparator "/path/"
"/path"
>>> dropTrailingPathSeparator "/path////"
"/path"
>>> dropTrailingPathSeparator "/"
"/"
>>> dropTrailingPathSeparator "//"
"/"

File name manipulations

normalise :: RawFilePath -> RawFilePath

Normalise a file.

>>> normalise "/file/\\test////"
"/file/\\test/"
>>> normalise "/file/./test"
"/file/test"
>>> normalise "/test/file/../bob/fred/"
"/test/file/../bob/fred/"
>>> normalise "../bob/fred/"
"../bob/fred/"
>>> normalise "./bob/fred/"
"bob/fred/"
>>> normalise "./bob////.fred/./...///./..///#."
"bob/.fred/.../../#."
>>> normalise "."
"."
>>> normalise "./"
"./"
>>> normalise "./."
"./"
>>> normalise "/./"
"/"
>>> normalise "/"
"/"
>>> normalise "bob/fred/."
"bob/fred/"
>>> normalise "//home"
"/home"

makeRelative :: RawFilePath -> RawFilePath -> RawFilePath

Contract a filename, based on a relative path. Note that the resulting path will never introduce .. paths, as the presence of symlinks means ../b may not reach a/b if it starts from a/c. For a worked example see this blog post.

>>> makeRelative "/directory" "/directory/file.ext"
"file.ext"
>>> makeRelative "/Home" "/home/bob"
"/home/bob"
>>> makeRelative "/home/" "/home/bob/foo/bar"
"bob/foo/bar"
>>> makeRelative "/fred" "bob"
"bob"
>>> makeRelative "/file/test" "/file/test/fred"
"fred"
>>> makeRelative "/file/test" "/file/test/fred/"
"fred/"
>>> makeRelative "some/path" "some/path/a/b/c"
"a/b/c"

\p -> makeRelative p p == "."

\p -> makeRelative (takeDirectory p) p `equalFilePath` takeFileName p

prop x y -> equalFilePath x y || (isRelative x && makeRelative y x == x) || equalFilePath (y / makeRelative y x) x

equalFilePath :: RawFilePath -> RawFilePath -> Bool

Equality of two filepaths. The filepaths are normalised and trailing path separators are dropped.

>>> equalFilePath "foo" "foo"
True
>>> equalFilePath "foo" "foo/"
True
>>> equalFilePath "foo" "./foo"
True
>>> equalFilePath "" ""
True
>>> equalFilePath "foo" "/foo"
False
>>> equalFilePath "foo" "FOO"
False
>>> equalFilePath "foo" "../foo"
False

\p -> equalFilePath p p

isRelative :: RawFilePath -> Bool

Check if a path is relative

\path -> isRelative path /= isAbsolute path

isAbsolute :: RawFilePath -> Bool

Check if a path is absolute

>>> isAbsolute "/path"
True
>>> isAbsolute "path"
False
>>> isAbsolute ""
False

isValid :: RawFilePath -> Bool

Is a FilePath valid, i.e. could you create a file like it?

>>> isValid ""
False
>>> isValid "\0"
False
>>> isValid "/random_ path:*"
True

makeValid :: RawFilePath -> RawFilePath

Take a FilePath and make it valid; does not change already valid FilePaths.

>>> makeValid ""
"_"
>>> makeValid "file\0name"
"file_name"

\p -> if isValid p then makeValid p == p else makeValid p /= p

\p -> isValid (makeValid p)

isFileName :: RawFilePath -> Bool

Is the given path a valid filename? This includes "." and "..".

>>> isFileName "lal"
True
>>> isFileName "."
True
>>> isFileName ".."
True
>>> isFileName ""
False
>>> isFileName "\0"
False
>>> isFileName "/random_ path:*"
False

hasParentDir :: RawFilePath -> Bool

Check if the filepath has any parent directories in it.

>>> hasParentDir "/.."
True
>>> hasParentDir "foo/bar/.."
True
>>> hasParentDir "foo/../bar/."
True
>>> hasParentDir "foo/bar"
False
>>> hasParentDir "foo"
False
>>> hasParentDir ""
False
>>> hasParentDir ".."
False

hiddenFile :: RawFilePath -> Bool

Whether the file is a hidden file.

>>> hiddenFile ".foo"
True
>>> hiddenFile "..foo.bar"
True
>>> hiddenFile "some/path/.bar"
True
>>> hiddenFile "..."
True
>>> hiddenFile "dod.bar"
False
>>> hiddenFile "."
False
>>> hiddenFile ".."
False
>>> hiddenFile ""
False

module System.Posix.ByteString.FilePath