| Haskell Core Libraries (Cabal package) | Contents | Index

Distribution.Compat.FilePath

Contents

File path
Search path
Separators
Filename extensions

Synopsis

FilePath
splitFileName :: FilePath -> (String, String)
splitFileExt :: FilePath -> (String, String)
splitFilePath :: FilePath -> (String, String, String)
joinFileName :: String -> String -> FilePath
joinFileExt :: String -> String -> FilePath
joinPaths :: FilePath -> FilePath -> FilePath
changeFileExt :: FilePath -> String -> FilePath
isRootedPath :: FilePath -> Bool
isAbsolutePath :: FilePath -> Bool
dropAbsolutePrefix :: FilePath -> FilePath
pathParents :: FilePath -> [FilePath]
commonParent :: [FilePath] -> Maybe FilePath
parseSearchPath :: String -> [FilePath]
mkSearchPath :: [FilePath] -> String
isPathSeparator :: Char -> Bool
pathSeparator :: Char
searchPathSeparator :: Char
exeExtension :: String
objExtension :: String
dllExtension :: String

File path
FilePath
splitFileName :: FilePath -> (String, String)

Split the path into directory and file name

Examples:

[Posix]

     splitFileName "/"            == ("/",    ".")
     splitFileName "/foo/bar.ext" == ("/foo", "bar.ext")
     splitFileName "bar.ext"      == (".",    "bar.ext")
     splitFileName "/foo/."       == ("/foo", ".")
     splitFileName "/foo/.."      == ("/foo", "..")

[Windows]

     splitFileName "\\"               == ("\\",      "")
     splitFileName "c:\\foo\\bar.ext" == ("c:\\foo", "bar.ext")
     splitFileName "bar.ext"          == (".",       "bar.ext")
     splitFileName "c:\\foo\\."       == ("c:\\foo", ".")
     splitFileName "c:\\foo\\.."      == ("c:\\foo", "..")

The first case in the Windows examples returns an empty file name. This is a special case because the "\\" path doesn't refer to an object (file or directory) which resides within a directory.

splitFileExt :: FilePath -> (String, String)

Split the path into file name and extension. If the file doesn't have extension, the function will return empty string. The extension doesn't include a leading period.

Examples:

     splitFileExt "foo.ext" == ("foo", "ext")
     splitFileExt "foo"     == ("foo", "")
     splitFileExt "."       == (".",   "")
     splitFileExt ".."      == ("..",  "")
     splitFileExt "foo.bar."== ("foo.bar.", "")

splitFilePath :: FilePath -> (String, String, String)

Split the path into directory, file name and extension. The function is an optimized version of the following equation:

     splitFilePath path = (dir,name,ext)
       where
         (dir,basename) = splitFileName path
         (name,ext)     = splitFileExt  basename

joinFileName :: String -> String -> FilePath

The `joinFileName` function is the opposite of `splitFileName`. It joins directory and file names to form a complete file path.

The general rule is:

     dir `joinFileName` basename == path
       where
         (dir,basename) = splitFileName path

There might be an exceptions to the rule but in any case the reconstructed path will refer to the same object (file or directory). An example exception is that on Windows some slashes might be converted to backslashes.

joinFileExt :: String -> String -> FilePath

The `joinFileExt` function is the opposite of `splitFileExt`. It joins a file name and an extension to form a complete file path.

The general rule is:

     filename `joinFileExt` ext == path
       where
         (filename,ext) = splitFileExt path

joinPaths :: FilePath -> FilePath -> FilePath
Given a directory path "dir" and a file/directory path "rel", returns a merged path "full" with the property that (cd dir; do_something_with rel) is equivalent to (do_something_with full). If the "rel" path is an absolute path then the returned path is equal to "rel"
changeFileExt

:: FilePath | The path information to modify.
-> String | The new extension (without a leading period). Specify an empty string to remove an existing extension from path.
-> FilePath | A string containing the modified path information.
Changes the extension of a file path.

isRootedPath :: FilePath -> Bool
On Unix and Macintosh the `isRootedPath` function is a synonym to `isAbsolutePath`. The difference is important only on Windows. The rooted path must start from the root directory but may not include the drive letter while the absolute path always includes the drive letter and the full file path.
isAbsolutePath :: FilePath -> Bool
Returns `True` if this path's meaning is independent of any OS "working directory", or `False` if it isn't.
dropAbsolutePrefix :: FilePath -> FilePath
If the function is applied to an absolute path then it returns a local path droping the absolute prefix in the path. Under Windows the prefix is "\", "c:" or "c:\". Under Unix the prefix is always "/".
pathParents :: FilePath -> [FilePath]

Gets this path and all its parents. The function is useful in case if you want to create some file but you aren't sure whether all directories in the path exist or if you want to search upward for some file.

Some examples:

[Posix]

      pathParents "/"          == ["/"]
      pathParents "/dir1"      == ["/", "/dir1"]
      pathParents "/dir1/dir2" == ["/", "/dir1", "/dir1/dir2"]
      pathParents "dir1"       == [".", "dir1"]
      pathParents "dir1/dir2"  == [".", "dir1", "dir1/dir2"]

[Windows]

      pathParents "c:"             == ["c:."]
      pathParents "c:\\"           == ["c:\\"]
      pathParents "c:\\dir1"       == ["c:\\", "c:\\dir1"]
      pathParents "c:\\dir1\\dir2" == ["c:\\", "c:\\dir1", "c:\\dir1\\dir2"]
      pathParents "c:dir1"         == ["c:.","c:dir1"]
      pathParents "dir1\\dir2"     == [".", "dir1", "dir1\\dir2"]

Note that if the file is relative then the current directory (".") will be explicitly listed.

commonParent :: [FilePath] -> Maybe FilePath
Given a list of file paths, returns the longest common parent.
Search path
parseSearchPath :: String -> [FilePath]
The function splits the given string to substrings using the `searchPathSeparator`.
mkSearchPath :: [FilePath] -> String
The function concatenates the given paths to form a single string where the paths are separated with `searchPathSeparator`.
Separators
isPathSeparator :: Char -> Bool
Checks whether the character is a valid path separator for the host platform. The valid character is a `pathSeparator` but since the Windows operating system also accepts a slash ("/") since DOS 2, the function checks for it on this platform, too.
pathSeparator :: Char
Provides a platform-specific character used to separate directory levels in a path string that reflects a hierarchical file system organization. The separator is a slash (`"/"`) on Unix and Macintosh, and a backslash (`"\"`) on the Windows operating system.
searchPathSeparator :: Char
A platform-specific character used to separate search path strings in environment variables. The separator is a colon (":") on Unix and Macintosh, and a semicolon (";") on the Windows operating system.
Filename extensions
exeExtension :: String
Extension for executable files (typically `""` on Unix and `"exe"` on Windows or OS/2)
objExtension :: String
Extension for object files. For GHC and NHC the extension is `"o"`. Hugs uses either `"o"` or `"obj"` depending on the used C compiler.
dllExtension :: String
Extension for dynamically linked (or shared) libraries (typically `"so"` on Unix and `"dll"` on Windows)
Produced by Haddock version 0.7