-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Type-safe replacement for System.FilePath etc
--
-- This package provides type-safe access to filepath manipulations.
--
-- System.Path is designed to be used instead of
-- System.FilePath. (It is intended to provide versions of
-- functions from that module which have equivalent functionality but are
-- more typesafe). System.Path.Directory is a companion module
-- providing a type-safe alternative to System.Directory.
--
-- The heart of this module is the Path ar fd abstract
-- type which represents file and directory paths. The idea is that there
-- are two type parameters - the first should be Abs or
-- Rel, and the second File or Dir. A number of type
-- synonyms are provided for common types:
--
--
-- 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
--
--
-- The type of the combine (aka </>) function gives
-- the idea:
--
--
-- (</>) :: DirPath ar -> RelPath fd -> Path ar fd
--
--
-- Together this enables us to give more meaningful types to a lot of the
-- functions, and (hopefully) catch a bunch more errors at compile time.
--
-- You can use the construction functions as follows:
--
--
-- f :: Path.RelFile
-- f = relDir "tmp" </> relFile "someFile" <.> "ext"
--
--
-- or...
--
--
-- f :: Path.RelFile
-- f = dirPath "tmp" </> filePath "someFile" <.> "ext"
--
--
-- or...
--
--
-- f :: Path.RelFile
-- f = path "tmp" </> path "someFile" <.> "ext"
--
--
-- or just...
--
--
-- f :: Path.RelFile
-- f = relFile "tmp/someFile.ext"
--
--
-- The first and the last implementations force the most specific types
-- and thus should be prefered.
--
-- Overloaded string literals are no longer supported, since this
-- extension is intended for alternative text storage types. It would
-- also decrease the type safety if you could omit the path type and let
-- the compiler guess its type.
--
-- You will typically want to import as follows:
--
--
-- import qualified System.Path.Directory as Dir
-- import qualified System.Path.IO as PathIO
-- import qualified System.Path as Path
-- import System.Path ((</>))
--
--
-- System.Path.Generic provides all functions with the OS as type
-- parameter. System.Path.Posix and System.Path.Windows
-- offers only path constructors and destructors fixed to the
-- corresponding operating system. System.Path exports either
-- System.Path.Posix or System.Path.Windows depending on
-- the host system and additionally the manipulation functions from
-- System.Path.Generic. This mix should be appropriate for the
-- average use and should free the user from writing type annotations.
--
-- The basic API (and properties satisfied) are heavily influenced by
-- Neil Mitchell's System.FilePath module.
--
-- Some notes on how to choose proper type parameters:
--
-- The ar and the fd type parameters have quite
-- different meaning. The types Abs and Rel refer to a
-- property of the path, whereas the type File and Dir
-- refers to a property of a disk object. You can decide whether a path
-- is absolute or relative by just watching (the beginning of) the path
-- string. In contrast to that, you have to access the disk in order to
-- check the existence and type of an disk object. Even more, the disk
-- object might change at any time, e.g. the user might delete a file and
-- create a directory of the same name, or the disk object might not
-- exist, and the purpose of the path is to create an according file or
-- directory. That's why even if you have a path of type FilePath
-- ar, every function accessing the file must check that the refered
-- object exists and is a file. Conversely, there is not much sense in
-- checking the disk object type and then chosing the path accordingly.
-- Instead, you must choose the path type according to what type of disk
-- object your application needs. The reality check must be performed and
-- is performed by the standard functions for every access to the object.
-- If an disk object is not of the type required by the path type then
-- this is a runtime exception that must be handled at runtime but it is
-- not a programming error.
--
-- Sometimes you have to change the type of a path as an intermediate
-- step to construct a path for an object of different type. E.g. you may
-- convert the path "pkg" from DirPath to FilePath
-- because in the next step you like to extend it to "pkg.tar.gz". This
-- is valid use of the Path type. E.g. the function
-- dropExtensions reduces the FilePath "pkg.tar.gz" to
-- the new FilePath "pkg" although no-one expects that there is
-- or will be a file with name "pkg". Thus, if a function has a
-- FilePath parameter then there is no warranty that it accesses
-- the according file and does not touch related disk objects. It may
-- well be that the function derives other file and directory names from
-- the path and accesses them. That is, a FilePath or
-- DirPath parameter is mainly for documentation purposes but it
-- cannot prevent you seriously from any damage.
--
-- How to cope with user input? You may get a path from the user, e.g. as
-- command-line argument. It might be either absolute or relative and it
-- might refer to an actual file or directory or to something yet
-- non-existing. In most cases it will not be important whether the path
-- is absolute or relative, thus you should choose the AbsOrRel
-- type parameter. If somewhere in the program an Abs path is
-- needed then you can assert that the path is actually absolutized
-- somewhere e.g. by dynamicMakeAbsolute. If you prevent usage
-- of genericMakeAbsolute then you avoid to absolutize a path
-- that is already absolutized.
--
-- The choice of the fd type parameter follows a different
-- reasoning: Often you have a clear idea of whether the user must pass a
-- file or directory path. The rule is: Just give the path the type you
-- expect but do not perform any checking (unless you want to warn the
-- user earlier about imminent danger). The disk object type must checked
-- for every access to the object, anyway, so there is no point in
-- checking it immediately. With your choice of the fd parameter
-- you just document its intended use.
--
-- It might be that the path is only a base name used to construct other
-- directory and file names. E.g. for an Audacity project named
-- music you have to create the directory music_data
-- and the file music.aup. In this case we recommend to give
-- music the type FilePath. This type warrants that
-- there is at least one final path component in contrast to a directory
-- path that might be empty. You can easily convert a file path to a
-- directory path using Path.dirFromFile. The reverse conversion
-- is partial.
--
-- Some notes on file system links:
--
-- This package does not explicitly handle file system links. We treat a
-- file path containing links like any other file path. The same holds
-- for directory paths. A link is handled like any other path component.
--
-- Some notes on drive-relative paths on Windows:
--
-- We use the Rel type for paths that can be relative to any
-- directory. We use the Abs type for all other paths, i.e. for
-- paths with explicit locations or with restrictions on the set of
-- locations. Windows has a notion of drives and maintains a current
-- directory for every drive. E.g. the path "c:text.txt" refers
-- to the current directory of drive C. Since it cannot be
-- freely combined with other directories we treat this path like an
-- absolute path. This is consistent with the behaviour of the
-- filepath package. E.g. filepath evaluates all of the
-- expressions "\\abs" </> "c:driverel", "c:\\abs"
-- </> "c:driverel", "d:\\abs" </> "c:driverel"
-- to "c:driverel". In our package you would have to use
-- genericMakeAbsolute but we recommend to avoid its use.
--
-- Related packages:
--
--
-- - path: Provides a wrapper type around FilePath and
-- maps to functions from filepath package. This warrants
-- consistency with filepath functions. Requires Template
-- Haskell.
-- - data-filepath: Requires Typeable and Template
-- Haskell.
--
@package pathtype
@version 0.7
-- | This module provides type-safe access to filepath manipulations.
--
-- Normally you would import 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.
module System.Path.Posix
type Path = Path Posix
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
type AbsOrRelFile = Path AbsOrRel File
type AbsOrRelDir = Path AbsOrRel Dir
type AbsFileOrDir = Path Abs FileOrDir
type RelFileOrDir = Path Rel FileOrDir
type AbsOrRelPath fd = Path AbsOrRel fd
type FileOrDirPath ar = Path ar FileOrDir
type AbsOrRelFileOrDir = Path AbsOrRel FileOrDir
-- | Deprecated: Use maybePath, parsePath or path
-- instead.
asPath :: (AbsRelClass ar, FileDirClass fd) => String -> Path ar fd
-- | Deprecated: Use relFile instead.
asRelFile :: String -> RelFile
-- | Deprecated: Use relDir instead.
asRelDir :: String -> RelDir
-- | Deprecated: Use absFile instead.
asAbsFile :: String -> AbsFile
-- | Deprecated: Use absDir instead.
asAbsDir :: String -> AbsDir
-- | Deprecated: Use relPath instead.
asRelPath :: (FileDirClass fd) => String -> RelPath fd
-- | Deprecated: Use absPath instead.
asAbsPath :: (FileDirClass fd) => String -> AbsPath fd
-- | Deprecated: Use filePath instead.
asFilePath :: (AbsRelClass ar) => String -> FilePath ar
-- | Deprecated: Use dirPath instead.
asDirPath :: (AbsRelClass ar) => String -> DirPath ar
path :: (AbsOrRelClass ar, FileOrDirClass fd) => String -> Path ar fd
maybePath :: (AbsOrRelClass ar, FileOrDirClass fd) => String -> Maybe (Path ar fd)
relFile :: String -> RelFile
relDir :: String -> RelDir
absFile :: String -> AbsFile
absDir :: String -> AbsDir
relPath :: (FileOrDirClass fd) => String -> RelPath fd
absPath :: (FileOrDirClass fd) => String -> AbsPath fd
filePath :: (AbsOrRelClass ar) => String -> FilePath ar
dirPath :: (AbsOrRelClass ar) => String -> DirPath ar
rootDir :: AbsDir
currentDir :: RelDir
emptyFile :: RelFile
toString :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> String
isAbsoluteString :: String -> Bool
isRelativeString :: String -> Bool
equalFilePath :: String -> String -> Bool
pathSeparator :: Char
pathSeparators :: [Char]
isPathSeparator :: Char -> Bool
-- | File extension character
--
--
-- > Posix.extSeparator == '.'
--
extSeparator :: Char
-- | Is the character an extension character?
--
--
-- > Posix.isExtSeparator a == (a == Posix.extSeparator)
--
isExtSeparator :: Char -> Bool
-- | The character that is used to separate the entries in the $PATH
-- environment variable.
searchPathSeparator :: Char
-- | Is the character a file separator?
--
--
-- > Posix.isSearchPathSeparator a == (a == Posix.searchPathSeparator)
--
isSearchPathSeparator :: Char -> Bool
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.addTrailingPathSeparator
-- instead.
addTrailingPathSeparator :: String -> String
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.dropTrailingPathSeparator
-- instead.
dropTrailingPathSeparator :: String -> String
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.hasTrailingPathSeparator
-- instead.
hasTrailingPathSeparator :: String -> Bool
testAll :: [(String, IO ())]
instance System.Path.Internal.System System.Path.Posix.Posix
-- | This module provides type-safe access to filepath manipulations.
--
-- Normally you would import 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.
module System.Path.Windows
type Path = Path Windows
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
type AbsOrRelFile = Path AbsOrRel File
type AbsOrRelDir = Path AbsOrRel Dir
type AbsFileOrDir = Path Abs FileOrDir
type RelFileOrDir = Path Rel FileOrDir
type AbsOrRelPath fd = Path AbsOrRel fd
type FileOrDirPath ar = Path ar FileOrDir
type AbsOrRelFileOrDir = Path AbsOrRel FileOrDir
-- | Deprecated: Use maybePath, parsePath or path
-- instead.
asPath :: (AbsRelClass ar, FileDirClass fd) => String -> Path ar fd
-- | Deprecated: Use relFile instead.
asRelFile :: String -> RelFile
-- | Deprecated: Use relDir instead.
asRelDir :: String -> RelDir
-- | Deprecated: Use absFile instead.
asAbsFile :: String -> AbsFile
-- | Deprecated: Use absDir instead.
asAbsDir :: String -> AbsDir
-- | Deprecated: Use relPath instead.
asRelPath :: (FileDirClass fd) => String -> RelPath fd
-- | Deprecated: Use absPath instead.
asAbsPath :: (FileDirClass fd) => String -> AbsPath fd
-- | Deprecated: Use filePath instead.
asFilePath :: (AbsRelClass ar) => String -> FilePath ar
-- | Deprecated: Use dirPath instead.
asDirPath :: (AbsRelClass ar) => String -> DirPath ar
path :: (AbsOrRelClass ar, FileOrDirClass fd) => String -> Path ar fd
maybePath :: (AbsOrRelClass ar, FileOrDirClass fd) => String -> Maybe (Path ar fd)
relFile :: String -> RelFile
relDir :: String -> RelDir
absFile :: String -> AbsFile
absDir :: String -> AbsDir
relPath :: (FileOrDirClass fd) => String -> RelPath fd
absPath :: (FileOrDirClass fd) => String -> AbsPath fd
filePath :: (AbsOrRelClass ar) => String -> FilePath ar
dirPath :: (AbsOrRelClass ar) => String -> DirPath ar
rootDir :: AbsDir
currentDir :: RelDir
emptyFile :: RelFile
toString :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> String
isAbsoluteString :: String -> Bool
isRelativeString :: String -> Bool
equalFilePath :: String -> String -> Bool
pathSeparator :: Char
pathSeparators :: [Char]
isPathSeparator :: Char -> Bool
-- | File extension character
--
--
-- > Posix.extSeparator == '.'
--
extSeparator :: Char
-- | Is the character an extension character?
--
--
-- > Posix.isExtSeparator a == (a == Posix.extSeparator)
--
isExtSeparator :: Char -> Bool
-- | The character that is used to separate the entries in the $PATH
-- environment variable.
searchPathSeparator :: Char
-- | Is the character a file separator?
--
--
-- > Posix.isSearchPathSeparator a == (a == Posix.searchPathSeparator)
--
isSearchPathSeparator :: Char -> Bool
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.addTrailingPathSeparator
-- instead.
addTrailingPathSeparator :: String -> String
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.dropTrailingPathSeparator
-- instead.
dropTrailingPathSeparator :: String -> String
-- | This is largely for FilePath compatibility
-- | Deprecated: Use System.FilePath.hasTrailingPathSeparator
-- instead.
hasTrailingPathSeparator :: String -> Bool
testAll :: [(String, IO ())]
instance System.Path.Internal.System System.Path.Windows.Windows
-- | This module provides type-safe access to filepath manipulations
-- independent from the operating system.
--
-- Normally you would import Path since this contains types fixed
-- to your host system and otherwise generic functions. However,
-- importing this explicitly allows for manipulation of non-native paths.
module System.Path.Generic
-- | This is the main filepath abstract datatype
data Path os ar fd
data Abs
data Rel
data AbsOrRel
data File
data Dir
data FileOrDir
type AbsFile os = Path os Abs File
type RelFile os = Path os Rel File
type AbsDir os = Path os Abs Dir
type RelDir os = Path os Rel Dir
type AbsOrRelFile os = Path os AbsOrRel File
type AbsOrRelDir os = Path os AbsOrRel Dir
type AbsFileOrDir os = Path os Abs FileOrDir
type RelFileOrDir os = Path os Rel FileOrDir
type AbsOrRelFileOrDir os = Path os AbsOrRel FileOrDir
type AbsPath os fd = Path os Abs fd
type RelPath os fd = Path os Rel fd
type FilePath os ar = Path os ar File
type DirPath os ar = Path os ar Dir
type AbsOrRelPath os fd = Path os AbsOrRel fd
type FileOrDirPath os ar = Path os ar FileOrDir
class AbsOrRelClass ar => AbsRelClass ar
switchAbsRel :: AbsRelClass ar => f Abs -> f Rel -> f ar
-- | This class allows selective behaviour for absolute and relative paths
-- and is mostly for internal use.
class Private ar => AbsOrRelClass ar
-- | See https://wiki.haskell.org/Closed_world_instances for the
-- used technique.
switchAbsOrRel :: AbsOrRelClass ar => f Abs -> f Rel -> f AbsOrRel -> f ar
absRel :: (AbsOrRelClass ar) => (AbsPath os fd -> a) -> (RelPath os fd -> a) -> Path os ar fd -> a
-- | This class allows selective behaviour for file and directory paths and
-- is mostly for internal use.
class Private fd => FileOrDirClass fd
switchFileOrDir :: FileOrDirClass fd => f File -> f Dir -> f FileOrDir -> f fd
class FileOrDirClass fd => FileDirClass fd
switchFileDir :: FileDirClass fd => f File -> f Dir -> f fd
fileDir :: (FileDirClass fd) => (FilePath os ar -> a) -> (DirPath os ar -> a) -> Path os ar fd -> a
-- | Synonym of getPathString intended for qualified use.
toString :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => Path os ar fd -> String
-- | Convert the Path into a plain String as required for OS
-- calls.
getPathString :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => Path os ar fd -> String
rootDir :: (System os) => AbsDir os
currentDir :: (System os) => RelDir os
-- | This is a file with path "". You will not be able to create a
-- file with this name. We also forbid parsing "" by
-- relFile. You might only need this file path as intermediate
-- step when manipulating extensions of files like ".bashrc".
emptyFile :: (System os) => RelFile os
-- | This function is intended for checking and parsing paths provided as
-- user input.
--
--
-- > fmap Posix.toString (Posix.maybePath "/" :: Maybe Posix.AbsDir) == Just "/"
-- > fmap Posix.toString (Posix.maybePath "/" :: Maybe Posix.AbsFile) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/" :: Maybe Posix.RelDir) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/" :: Maybe Posix.RelFile) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp" :: Maybe Posix.AbsDir) == Just "/tmp"
-- > fmap Posix.toString (Posix.maybePath "/tmp" :: Maybe Posix.AbsFile) == Just "/tmp"
-- > fmap Posix.toString (Posix.maybePath "/tmp" :: Maybe Posix.RelDir) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp" :: Maybe Posix.RelFile) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp/" :: Maybe Posix.AbsDir) == Just "/tmp"
-- > fmap Posix.toString (Posix.maybePath "/tmp/" :: Maybe Posix.AbsFile) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp/" :: Maybe Posix.RelDir) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp/" :: Maybe Posix.RelFile) == Nothing
-- > fmap Posix.toString (Posix.maybePath "/tmp" :: Maybe Posix.AbsOrRelFileOrDir) == Just "/tmp"
-- > fmap Posix.toString (Posix.maybePath "/tmp/" :: Maybe Posix.AbsOrRelFileOrDir) == Just "/tmp"
-- > fmap Posix.toString (Posix.maybePath "file.txt" :: Maybe Posix.RelFile) == Just "file.txt"
-- > fmap Posix.toString (Posix.maybePath "file.txt" :: Maybe Posix.AbsFile) == Nothing
-- > fmap Windows.toString (Windows.maybePath "\\tmp" :: Maybe Windows.AbsDir) == Just "\\tmp"
-- > fmap Windows.toString (Windows.maybePath "a:\\tmp" :: Maybe Windows.AbsDir) == Just "a:\\tmp"
-- > fmap Windows.toString (Windows.maybePath "a:tmp" :: Maybe Windows.AbsDir) == Just "a:tmp"
-- > fmap Windows.toString (Windows.maybePath "a:\\" :: Maybe Windows.AbsDir) == Just "a:\\"
-- > fmap Windows.toString (Windows.maybePath "a:" :: Maybe Windows.AbsDir) == Just "a:"
-- > fmap Windows.toString (Windows.maybePath "tmp" :: Maybe Windows.RelDir) == Just "tmp"
-- > fmap Windows.toString (Windows.maybePath "\\tmp" :: Maybe Windows.RelDir) == Nothing
-- > fmap Windows.toString (Windows.maybePath "a:\\tmp" :: Maybe Windows.RelDir) == Nothing
-- > fmap Windows.toString (Windows.maybePath "a:tmp" :: Maybe Windows.RelDir) == Nothing
-- > fmap Windows.toString (Windows.maybePath "tmp" :: Maybe Windows.AbsDir) == Nothing
--
maybePath :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => String -> Maybe (Path os ar fd)
parsePath :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => String -> Either String (Path os ar fd)
-- | This function is intended for converting path strings with known
-- content, e.g. string literals, to the Path type.
path :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => String -> Path os ar fd
-- | Construct a RelFile from a String.
--
--
-- > Posix.toString (Posix.relFile "file.txt") == "file.txt"
-- > Posix.toString (Posix.relFile "tmp") == "tmp"
--
relFile :: (System os) => String -> RelFile os
-- | Construct a RelDir from a String.
--
--
-- > Posix.toString (Posix.relDir ".") == "."
-- > Posix.toString (Posix.relDir "file.txt") == "file.txt"
-- > Posix.toString (Posix.relDir "tmp") == "tmp"
--
relDir :: (System os) => String -> RelDir os
-- | Construct an AbsFile from a String.
--
--
-- > Posix.toString (Posix.absFile "/file.txt") == "/file.txt"
-- > Posix.toString (Posix.absFile "/tmp") == "/tmp"
--
absFile :: (System os) => String -> AbsFile os
-- | Construct an AbsDir from a String.
--
--
-- > Posix.toString (Posix.absDir "/file.txt") == "/file.txt"
-- > Posix.toString (Posix.absDir "/tmp") == "/tmp"
--
absDir :: (System os) => String -> AbsDir os
-- | Construct a 'RelPath fd' from a String.
relPath :: (System os, FileOrDirClass fd) => String -> RelPath os fd
-- | Construct an 'AbsPath fd' from a String.
absPath :: (System os, FileOrDirClass fd) => String -> AbsPath os fd
-- | Construct a 'FilePath ar' from a String.
filePath :: (System os, AbsOrRelClass ar) => String -> FilePath os ar
-- | Construct a 'DirPath ar' from a String.
dirPath :: (System os, AbsOrRelClass ar) => String -> DirPath os ar
idAbsOrRel :: AbsOrRelPath os fd -> AbsOrRelPath os fd
idAbs :: AbsPath os fd -> AbsPath os fd
idRel :: RelPath os fd -> RelPath os fd
idFileOrDir :: FileOrDirPath os fd -> FileOrDirPath os fd
idFile :: FilePath os fd -> FilePath os fd
idDir :: DirPath os fd -> DirPath os fd
-- | Use a String as a Path whose type is determined by its
-- context. You should not use this and other as* functions,
-- since they may silently turn a relative path to an absolute one, or
-- vice versa, or they may accept a path as file path although it ends on
-- a slash. If you are certain about the string content then you should
-- use path. If you got the string as user input then use
-- maybePath or parsePath.
--
--
-- > Posix.asPath "/tmp" == Posix.absDir "/tmp"
-- > Posix.asPath "file.txt" == Posix.relFile "file.txt"
-- > Path.isAbsolute (Posix.asAbsDir "/tmp")
-- > Path.isRelative (Posix.asRelDir "/tmp")
-- > Posix.toString (Posix.asPath "/tmp" :: Posix.AbsDir) == "/tmp"
-- > Posix.toString (Posix.asPath "/tmp" :: Posix.RelDir) == "tmp"
-- > Windows.toString (Windows.asPath "\\tmp" :: Windows.AbsDir) == "\\tmp"
-- > Windows.toString (Windows.asPath "a:\\tmp" :: Windows.AbsDir) == "a:\\tmp"
-- > Windows.toString (Windows.asPath "a:tmp" :: Windows.AbsDir) == "a:tmp"
-- > Windows.toString (Windows.asPath "tmp" :: Windows.RelDir) == "tmp"
--
-- | Deprecated: Use maybePath, parsePath or path
-- instead.
asPath :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => String -> Path os ar fd
-- | Use a String as a RelFile. No checking is done.
--
--
-- > Posix.toString (Posix.asRelFile "file.txt") == "file.txt"
-- > Posix.toString (Posix.asRelFile "/file.txt") == "file.txt"
-- > Posix.toString (Posix.asRelFile "tmp") == "tmp"
-- > Posix.toString (Posix.asRelFile "/tmp") == "tmp"
--
-- | Deprecated: Use relFile instead.
asRelFile :: (System os) => String -> RelFile os
-- | Use a String as a RelDir. No checking is done.
--
--
-- > Posix.toString (Posix.asRelDir ".") == "."
-- > Posix.toString (Posix.asRelDir "file.txt") == "file.txt"
-- > Posix.toString (Posix.asRelDir "/file.txt") == "file.txt"
-- > Posix.toString (Posix.asRelDir "tmp") == "tmp"
-- > Posix.toString (Posix.asRelDir "/tmp") == "tmp"
--
-- | Deprecated: Use relDir instead.
asRelDir :: (System os) => String -> RelDir os
-- | Use a String as an AbsFile. No checking is done.
--
--
-- > Posix.toString (Posix.asAbsFile "/file.txt") == "/file.txt"
-- > Posix.toString (Posix.asAbsFile "/tmp") == "/tmp"
--
-- | Deprecated: Use absFile instead.
asAbsFile :: (System os) => String -> AbsFile os
-- | Use a String as an AbsDir. No checking is done.
--
--
-- > Posix.toString (Posix.asAbsDir "/file.txt") == "/file.txt"
-- > Posix.toString (Posix.asAbsDir "/tmp") == "/tmp"
--
-- | Deprecated: Use absDir instead.
asAbsDir :: (System os) => String -> AbsDir os
-- | Use a String as a 'RelPath fd'. No checking is done.
-- | Deprecated: Use relPath instead.
asRelPath :: (System os, FileOrDirClass fd) => String -> RelPath os fd
-- | Use a String as an 'AbsPath fd'. No checking is done.
-- | Deprecated: Use absPath instead.
asAbsPath :: (System os, FileOrDirClass fd) => String -> AbsPath os fd
-- | Use a String as a 'FilePath ar'. No checking is done.
-- | Deprecated: Use filePath instead.
asFilePath :: (System os, AbsOrRelClass ar) => String -> FilePath os ar
-- | Use a String as a 'DirPath ar'. No checking is done.
-- | Deprecated: Use dirPath instead.
asDirPath :: (System os, AbsOrRelClass ar) => String -> DirPath os ar
-- | Examines the supplied string and constructs an absolute or relative
-- path as appropriate.
--
--
-- > Path.mkPathAbsOrRel "/tmp" == Left (Posix.absDir "/tmp")
-- > Path.mkPathAbsOrRel "tmp" == Right (Posix.relDir "tmp")
-- > Path.mkPathAbsOrRel "\\tmp" == Left (Windows.absDir "\\tmp")
-- > Path.mkPathAbsOrRel "d:\\tmp" == Left (Windows.absDir "d:\\tmp")
-- > Path.mkPathAbsOrRel "d:tmp" == Left (Windows.absDir "d:tmp")
-- > Path.mkPathAbsOrRel "tmp" == Right (Windows.relDir "tmp")
--
mkPathAbsOrRel :: (System os, FileOrDirClass fd) => String -> Either (AbsPath os fd) (RelPath os fd)
-- | 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.
mkPathFileOrDir :: (System os, AbsOrRelClass ar) => String -> IO (Maybe (Either (FilePath os ar) (DirPath os ar)))
-- | Convert a String into an AbsPath by interpreting it as
-- relative to the supplied directory if necessary.
--
--
-- > Path.mkAbsPath (absDir "/tmp") "foo.txt" == Posix.absFile "/tmp/foo.txt"
-- > Path.mkAbsPath (absDir "/tmp") "/etc/foo.txt" == Posix.absFile "/etc/foo.txt"
--
mkAbsPath :: (System os, FileOrDirClass fd) => AbsDir os -> String -> AbsPath os fd
-- | Convert a String into an AbsPath by interpreting it as
-- relative to the cwd if necessary.
mkAbsPathFromCwd :: (System os, FileOrDirClass fd) => String -> IO (AbsPath os fd)
-- | Infix variant of combine.
--
--
-- > Posix.toString (Posix.absDir "/tmp" </> Posix.relFile "file.txt") == "/tmp/file.txt"
-- > Posix.toString (Posix.absDir "/tmp" </> Posix.relDir "dir" </> Posix.relFile "file.txt") == "/tmp/dir/file.txt"
-- > Posix.toString (Posix.relDir "dir" </> Posix.relFile "file.txt") == "dir/file.txt"
-- > Windows.toString (Windows.absDir "\\tmp" </> Windows.relFile "file.txt") == "\\tmp\\file.txt"
-- > Windows.toString (Windows.absDir "c:\\tmp" </> Windows.relFile "file.txt") == "c:\\tmp\\file.txt"
-- > Windows.toString (Windows.absDir "c:tmp" </> Windows.relFile "file.txt") == "c:tmp\\file.txt"
-- > Windows.toString (Windows.absDir "c:\\" </> Windows.relDir "tmp" </> Windows.relFile "file.txt") == "c:\\tmp\\file.txt"
-- > Windows.toString (Windows.absDir "c:" </> Windows.relDir "tmp" </> Windows.relFile "file.txt") == "c:tmp\\file.txt"
-- > Windows.toString (Windows.relDir "dir" </> Windows.relFile "file.txt") == "dir\\file.txt"
--
() :: DirPath os ar -> RelPath os fd -> Path os ar fd
-- | Infix variant of addExtension. 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.
(<.>) :: FilePath os ar -> String -> FilePath os ar
(<++>) :: FilePath os ar -> String -> FilePath os ar
-- | Add an extension, even if there is already one there. E.g.
-- addExtension "foo.txt" "bat" -> "foo.txt.bat".
--
--
-- > Path.addExtension (relFile "file.txt") "bib" == Posix.relFile "file.txt.bib"
-- > Path.addExtension (relFile "file.") ".bib" == Posix.relFile "file..bib"
-- > Path.addExtension (relFile "file") ".bib" == Posix.relFile "file.bib"
-- > Path.addExtension Path.emptyFile "bib" == Posix.relFile ".bib"
-- > Path.addExtension Path.emptyFile ".bib" == Posix.relFile ".bib"
-- > Path.takeFileName (Path.addExtension Path.emptyFile "ext") == Posix.relFile ".ext"
--
addExtension :: FilePath os ar -> String -> FilePath os ar
-- | Join an (absolute or relative) directory path with a relative (file or
-- directory) path to form a new path.
combine :: DirPath os ar -> RelPath os fd -> Path os ar fd
-- | Remove last extension, and the "." preceding it.
--
--
-- > Path.dropExtension x == fst (Path.splitExtension x)
--
dropExtension :: FilePath os ar -> FilePath os ar
-- | Drop all extensions
--
--
-- > not $ Path.hasAnExtension (Path.dropExtensions x)
--
dropExtensions :: FilePath os ar -> FilePath os ar
-- | Synonym for takeDirectory
dropFileName :: FilePath os ar -> DirPath os ar
-- | Set the extension of a file, overwriting one if already present.
--
--
-- > Path.replaceExtension (relFile "file.txt") ".bob" == Posix.relFile "file.bob"
-- > Path.replaceExtension (relFile "file.txt") "bob" == Posix.relFile "file.bob"
-- > Path.replaceExtension (relFile "file") ".bob" == Posix.relFile "file.bob"
-- > Path.replaceExtension (relFile "file.txt") "" == Posix.relFile "file"
-- > Path.replaceExtension (relFile "file.fred.bob") "txt" == Posix.relFile "file.fred.txt"
--
replaceExtension :: FilePath os ar -> String -> FilePath os ar
replaceBaseName :: FilePath os ar -> String -> FilePath os ar
replaceDirectory :: FilePath os ar1 -> DirPath os ar2 -> FilePath os ar2
replaceFileName :: FilePath os ar -> String -> FilePath os ar
-- | Split on the extension. addExtension is the inverse.
--
--
-- > uncurry (<.>) (Path.splitExtension x) == x
-- > uncurry Path.addExtension (Path.splitExtension x) == x
-- > Path.splitExtension (relFile "file.txt") == (Posix.relFile "file",".txt")
-- > Path.splitExtension (relFile ".bashrc") == (Posix.emptyFile, ".bashrc")
-- > Path.splitExtension (relFile "file") == (Posix.relFile "file","")
-- > Path.splitExtension (relFile "file/file.txt") == (Posix.relFile "file/file",".txt")
-- > Path.splitExtension (relFile "file.txt/boris") == (Posix.relFile "file.txt/boris","")
-- > Path.splitExtension (relFile "file.txt/boris.ext") == (Posix.relFile "file.txt/boris",".ext")
-- > Path.splitExtension (relFile "file/path.txt.bob.fred") == (Posix.relFile "file/path.txt.bob",".fred")
--
splitExtension :: FilePath os ar -> (FilePath os ar, String)
-- | Split on all extensions
--
--
-- > Path.splitExtensions (relFile "file.tar.gz") == (Posix.relFile "file",".tar.gz")
--
splitExtensions :: FilePath os ar -> (FilePath os ar, String)
splitFileName :: FilePath os ar -> (DirPath os ar, RelFile os)
-- | Get the basename of a file
--
--
-- > Path.takeBaseName (absFile "/tmp/somedir/myfile.txt") == Posix.relFile "myfile"
-- > Path.takeBaseName (relFile "./myfile.txt") == Posix.relFile "myfile"
-- > Path.takeBaseName (relFile "myfile.txt") == Posix.relFile "myfile"
--
takeBaseName :: FilePath os ar -> RelFile os
takeDirectory :: FilePath os ar -> DirPath os ar
-- | Get the extension of a file, returns "" for no extension,
-- .ext otherwise.
--
--
-- > Path.takeExtension x == snd (Path.splitExtension x)
-- > Path.takeExtension (Path.addExtension x "ext") == ".ext"
-- > Path.takeExtension (Path.replaceExtension x "ext") == ".ext"
--
takeExtension :: FilePath os ar -> String
-- | Get all extensions
--
--
-- > Path.takeExtensions (Posix.relFile "file.tar.gz") == ".tar.gz"
--
takeExtensions :: FilePath os ar -> String
-- | Get the filename component of a file path (ie stripping all parent
-- dirs)
--
--
-- > Path.takeFileName (absFile "/tmp/somedir/myfile.txt") == Posix.relFile "myfile.txt"
-- > Path.takeFileName (relFile "./myfile.txt") == Posix.relFile "myfile.txt"
-- > Path.takeFileName (relFile "myfile.txt") == Posix.relFile "myfile.txt"
--
takeFileName :: FilePath os ar -> RelFile os
mapFileName :: (String -> String) -> FilePath os ar -> FilePath os ar
-- | Check whether two strings are equal as file paths.
--
--
-- > Posix.equalFilePath "abc/def" "abc/def"
-- > Posix.equalFilePath "abc/def" "abc//def"
-- > Posix.equalFilePath "/tmp/" "/tmp"
-- > Posix.equalFilePath "/tmp" "//tmp"
-- > Posix.equalFilePath "/tmp" "///tmp"
-- > not $ Posix.equalFilePath "abc" "def"
-- > not $ Posix.equalFilePath "/tmp" "tmp"
-- > Windows.equalFilePath "abc\\def" "abc\\def"
-- > Windows.equalFilePath "abc\\def" "abc\\\\def"
-- > Windows.equalFilePath "file" "File"
-- > Windows.equalFilePath "\\file" "\\\\file"
-- > Windows.equalFilePath "\\file" "\\\\\\file"
-- > not $ Windows.equalFilePath "abc" "def"
-- > not $ Windows.equalFilePath "file" "dir"
--
equalFilePath :: (System os) => Tagged os (String -> String -> Bool)
-- | Constructs a RelPath from a list of components. It is an
-- unchecked error if the path components contain path separators. It is
-- an unchecked error if a RelFile path is empty.
--
--
-- > Path.joinPath ["tmp","someDir","dir"] == Posix.relDir "tmp/someDir/dir"
-- > Path.joinPath ["tmp","someDir","file.txt"] == Posix.relFile "tmp/someDir/file.txt"
--
joinPath :: (FileOrDirClass fd) => [String] -> RelPath os fd
-- | Currently just transforms:
--
--
-- > Path.normalise (absFile "/tmp/fred/./jim/./file") == Posix.absFile "/tmp/fred/jim/file"
--
normalise :: (System os) => Path os ar fd -> Path os ar fd
-- | Deconstructs a path into its components.
--
--
-- > Path.splitPath (Posix.absDir "/tmp/someDir/mydir.dir") == (True, map relDir ["tmp","someDir","mydir.dir"], Nothing)
-- > Path.splitPath (Posix.absFile "/tmp/someDir/myfile.txt") == (True, map relDir ["tmp","someDir"], Just $ relFile "myfile.txt")
--
splitPath :: (AbsOrRelClass ar, FileDirClass fd) => Path os ar fd -> (Bool, [RelDir os], Maybe (RelFile os))
-- | 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.
--
--
-- > Path.makeRelative (absDir "/tmp/somedir") (absFile "/tmp/somedir/anotherdir/file.txt") == Posix.relFile "anotherdir/file.txt"
-- > Path.makeRelative (absDir "/tmp/somedir") (absDir "/tmp/somedir/anotherdir/dir") == Posix.relDir "anotherdir/dir"
-- > Path.makeRelative (absDir "c:\\tmp\\somedir") (absFile "C:\\Tmp\\SomeDir\\AnotherDir\\File.txt") == Windows.relFile "AnotherDir\\File.txt"
-- > Path.makeRelative (absDir "c:\\tmp\\somedir") (absDir "c:\\tmp\\somedir\\anotherdir\\dir") == Windows.relDir "anotherdir\\dir"
-- > Path.makeRelative (absDir "c:tmp\\somedir") (absDir "c:tmp\\somedir\\anotherdir\\dir") == Windows.relDir "anotherdir\\dir"
--
makeRelative :: (System os, FileOrDirClass fd) => AbsDir os -> AbsPath os fd -> RelPath os fd
makeRelativeMaybe :: (System os, FileOrDirClass fd) => AbsDir os -> AbsPath os fd -> Maybe (RelPath os fd)
-- | Joins an absolute directory with a relative path to construct a new
-- absolute path.
--
--
-- > Path.makeAbsolute (absDir "/tmp") (relFile "file.txt") == Posix.absFile "/tmp/file.txt"
-- > Path.makeAbsolute (absDir "/tmp") (relFile "adir/file.txt") == Posix.absFile "/tmp/adir/file.txt"
-- > Path.makeAbsolute (absDir "/tmp") (relDir "adir/dir") == Posix.absDir "/tmp/adir/dir"
--
makeAbsolute :: (System os) => AbsDir os -> RelPath os fd -> AbsPath os fd
-- | Converts a relative path into an absolute one by prepending the
-- current working directory.
makeAbsoluteFromCwd :: (System os) => RelPath os fd -> IO (AbsPath os fd)
dynamicMakeAbsolute :: (System os) => AbsDir os -> AbsOrRelPath os fd -> AbsPath os fd
dynamicMakeAbsoluteFromCwd :: (System os) => AbsOrRelPath os fd -> IO (AbsPath os fd)
-- | As for makeAbsolute, but for use when the path may already be
-- absolute (in which case it is left unchanged). You should avoid the
-- use of genericMakeAbsolute-type functions, because then you
-- avoid to absolutize a path that was already absolutized.
--
--
-- > Path.genericMakeAbsolute (absDir "/tmp") (relFile "file.txt") == Posix.absFile "/tmp/file.txt"
-- > Path.genericMakeAbsolute (absDir "/tmp") (relFile "adir/file.txt") == Posix.absFile "/tmp/adir/file.txt"
-- > Path.genericMakeAbsolute (absDir "/tmp") (absFile "/adir/file.txt") == Posix.absFile "/adir/file.txt"
--
genericMakeAbsolute :: (System os, AbsOrRelClass ar) => AbsDir os -> Path os ar fd -> AbsPath os fd
-- | As for makeAbsoluteFromCwd, but for use when the path may
-- already be absolute (in which case it is left unchanged).
genericMakeAbsoluteFromCwd :: (System os, AbsOrRelClass ar) => Path os ar fd -> IO (AbsPath os fd)
-- | Map over the components of the path.
--
--
-- > Path.pathMap (map toLower) (absDir "/tmp/Reports/SpreadSheets") == Posix.absDir "/tmp/reports/spreadsheets"
--
pathMap :: (FileOrDirClass fd) => (String -> String) -> Path os ar fd -> Path os ar fd
-- | Convert a file to a directory path. Obviously, the corresponding disk
-- object won't change accordingly. The purpose of this function is to be
-- an intermediate step when deriving a directory name from a file name.
dirFromFile :: FilePath os ar -> DirPath os ar
-- | Convert a directory to a file path. The function returns
-- Nothing if the directory path is empty. The purpose of this
-- function is to be an intermediate step when deriving a file name from
-- a directory name.
fileFromDir :: DirPath os ar -> Maybe (FilePath os ar)
toFileOrDir :: (FileOrDirClass fd) => Path os ar fd -> FileOrDirPath os ar
fromFileOrDir :: (FileOrDirClass fd) => FileOrDirPath os ar -> Maybe (Path os ar fd)
fileFromFileOrDir :: FileOrDirPath os ar -> Maybe (FilePath os ar)
dirFromFileOrDir :: FileOrDirPath os ar -> DirPath os ar
-- | Test whether a Path ar fd is absolute.
--
--
-- > Path.isAbsolute (Posix.absFile "/fred")
-- > Path.isAbsolute (Windows.absFile "\\fred")
-- > Path.isAbsolute (Windows.absFile "c:\\fred")
-- > Path.isAbsolute (Windows.absFile "c:fred")
--
isAbsolute :: AbsOrRelClass ar => Path os ar fd -> Bool
-- | Invariant - this should return True iff arg is of type Path
-- Rel _
--
--
-- isRelative = not . isAbsolute
-- > Path.isRelative (Posix.relFile "fred")
-- > Path.isRelative (Windows.relFile "fred")
--
isRelative :: AbsOrRelClass ar => Path os ar fd -> Bool
-- | Test whether the String would correspond to an absolute path if
-- interpreted as a Path.
isAbsoluteString :: (System os) => Tagged os (String -> Bool)
-- | Test whether the String would correspond to a relative path if
-- interpreted as a Path.
--
--
-- isRelativeString = not . isAbsoluteString
--
isRelativeString :: (System os) => Tagged os (String -> Bool)
-- | Does the given filename have an extension?
--
--
-- > null (Path.takeExtension x) == not (Path.hasAnExtension x)
--
hasAnExtension :: FilePath os ar -> Bool
-- | Does the given filename have the given extension?
--
--
-- > Path.hasExtension ".hs" (Posix.relFile "MyCode.hs")
-- > Path.hasExtension ".hs" (Posix.relFile "MyCode.bak.hs")
-- > not $ Path.hasExtension ".hs" (Posix.relFile "MyCode.hs.bak")
--
hasExtension :: String -> FilePath os ar -> Bool
class System os where pathSeparators = (: []) <$> pathSeparator isPathSeparator = flip elem <$> pathSeparators
-- | The character that separates directories. In the case where more than
-- one character is possible, pathSeparator is the 'ideal' one.
--
--
-- > Posix.isPathSeparator Posix.pathSeparator
--
pathSeparator :: System os => Tagged os Char
-- | The list of all possible separators.
--
--
-- > Posix.pathSeparator `elem` Posix.pathSeparators
--
pathSeparators :: System os => Tagged os [Char]
-- | Rather than using (== pathSeparator), use this. Test
-- if something is a path separator.
--
--
-- > Posix.isPathSeparator a == (a `elem` Posix.pathSeparators)
--
isPathSeparator :: System os => Tagged os (Char -> Bool)
splitAbsolute :: System os => Tagged os (State String String)
canonicalize :: System os => Tagged os (String -> String)
splitDrive :: System os => Tagged os (State String String)
genDrive :: System os => Tagged os (Gen String)
-- | File extension character
--
--
-- > Posix.extSeparator == '.'
--
extSeparator :: Char
-- | The character that is used to separate the entries in the $PATH
-- environment variable.
searchPathSeparator :: Char
-- | Is the character an extension character?
--
--
-- > Posix.isExtSeparator a == (a == Posix.extSeparator)
--
isExtSeparator :: Char -> Bool
-- | Is the character a file separator?
--
--
-- > Posix.isSearchPathSeparator a == (a == Posix.searchPathSeparator)
--
isSearchPathSeparator :: Char -> Bool
-- | This is a more flexible variant of addExtension /
-- <.> which can work with files or directories
--
--
-- > Path.genericAddExtension (absDir "/") "x" == Posix.absDir "/.x"
-- > Path.genericAddExtension (absDir "/a") "x" == Posix.absDir "/a.x"
-- > Path.genericAddExtension Path.emptyFile "x" == Posix.relFile ".x"
-- > Path.genericAddExtension Path.emptyFile "" == Posix.emptyFile
--
genericAddExtension :: (FileOrDirClass fd) => Path os ar fd -> String -> Path os ar fd
genericDropExtension :: (FileOrDirClass fd) => Path os ar fd -> Path os ar fd
genericDropExtensions :: (FileOrDirClass fd) => Path os ar fd -> Path os ar fd
genericSplitExtension :: (FileOrDirClass fd) => Path os ar fd -> (Path os ar fd, String)
genericSplitExtensions :: (FileOrDirClass fd) => Path os ar fd -> (Path os ar fd, String)
genericTakeExtension :: (FileOrDirClass fd) => Path os ar fd -> String
genericTakeExtensions :: (FileOrDirClass fd) => Path os ar fd -> String
testAll :: (System os) => os -> [(String, IO ())]
-- | Check internal integrity of the path data structure.
isValid :: (System os, AbsOrRelClass ar, FileOrDirClass fd) => Path os ar fd -> Bool
class System os where pathSeparators = (: []) <$> pathSeparator isPathSeparator = flip elem <$> pathSeparators
module System.Path
-- | This module provides type-safe access to directory manipulations.
--
-- It is designed to be imported instead of System.Directory. (It
-- is intended to provide versions of functions from that module which
-- have equivalent functionality but are more typesafe).
-- System.Path is a companion module providing a type-safe
-- alternative to System.FilePath.
--
-- You will typically want to import as follows:
--
--
-- import Prelude hiding (FilePath)
-- import System.Path
-- import System.Path.Directory
-- import System.Path.IO
--
--
-- Ben Moseley - (c) 2009
module System.Path.Directory
createDirectory :: AbsOrRelClass ar => DirPath ar -> IO ()
createDirectoryIfMissing :: AbsOrRelClass ar => Bool -> DirPath ar -> IO ()
removeDirectory :: AbsOrRelClass ar => DirPath ar -> IO ()
removeDirectoryRecursive :: AbsOrRelClass ar => DirPath ar -> IO ()
renameDirectory :: (AbsOrRelClass ar1, AbsOrRelClass ar2) => DirPath ar1 -> DirPath ar2 -> IO ()
-- | Retrieve the contents of a directory without any directory prefixes.
-- In contrast to getDirectoryContents, exclude special
-- directories "." and "..".
getDirectoryContents :: AbsOrRelClass ar => DirPath ar -> IO [RelFileOrDir]
-- | Retrieve the contents of a directory path (which may be relative) as
-- absolute paths
absDirectoryContents :: AbsOrRelClass ar => DirPath ar -> IO ([AbsDir], [AbsFile])
-- | Returns paths relative to the supplied (abs or relative)
-- directory path. eg (for current working directory of
-- /somewhere/cwd/):
--
--
-- show (relDirectoryContents "d/e/f/") == (["subDir1A","subDir1B"],
-- ["file1A","file1B"])
--
relDirectoryContents :: AbsOrRelClass ar => DirPath ar -> IO ([RelDir], [RelFile])
-- | A convenient alternative to relDirectoryContents if you only
-- want files.
filesInDir :: AbsOrRelClass ar => DirPath ar -> IO [RelFile]
-- | A convenient alternative to relDirectoryContents if you only
-- want directories.
dirsInDir :: AbsOrRelClass ar => DirPath ar -> IO [RelDir]
getCurrentDirectory :: IO AbsDir
setCurrentDirectory :: AbsOrRelClass ar => DirPath ar -> IO ()
getHomeDirectory :: IO AbsDir
getAppUserDataDirectory :: String -> IO AbsDir
getUserDocumentsDirectory :: IO AbsDir
getTemporaryDirectory :: IO AbsDir
removeFile :: AbsOrRelClass ar => FilePath ar -> IO ()
renameFile :: (AbsOrRelClass ar1, AbsOrRelClass ar2) => FilePath ar1 -> FilePath ar2 -> IO ()
copyFile :: (AbsOrRelClass ar1, AbsOrRelClass ar2) => FilePath ar1 -> FilePath ar2 -> IO ()
canonicalizePath :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> IO (AbsPath fd)
makeRelativeToCurrentDirectory :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> IO (RelPath fd)
findExecutable :: String -> IO (Maybe AbsFile)
doesFileExist :: AbsOrRelClass ar => FilePath ar -> IO Bool
doesDirectoryExist :: AbsOrRelClass ar => DirPath ar -> IO Bool
data Permissions :: *
getPermissions :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> IO Permissions
setPermissions :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> Permissions -> IO ()
getModificationTime :: (AbsOrRelClass ar, FileOrDirClass fd) => Path ar fd -> IO UTCTime
-- | This module provides type-safe access to IO operations.
--
-- It is designed to be imported instead of System.IO. (It is
-- intended to provide versions of functions from that module which have
-- equivalent functionality but are more typesafe). System.Path is
-- a companion module providing a type-safe alternative to
-- System.FilePath.
--
-- You will typically want to import as follows:
--
--
-- import Prelude hiding (FilePath)
-- import System.Path
-- import System.Path.Directory
-- import System.Path.IO
--
--
-- Ben Moseley - (c) 2009
module System.Path.IO
withFile :: AbsOrRelClass ar => FilePath ar -> IOMode -> (Handle -> IO r) -> IO r
openFile :: AbsOrRelClass ar => FilePath ar -> IOMode -> IO Handle
readFile :: AbsOrRelClass ar => FilePath ar -> IO String
writeFile :: AbsOrRelClass ar => FilePath ar -> String -> IO ()
appendFile :: AbsOrRelClass ar => FilePath ar -> String -> IO ()
withBinaryFile :: AbsOrRelClass ar => FilePath ar -> IOMode -> (Handle -> IO r) -> IO r
openBinaryFile :: AbsOrRelClass ar => FilePath ar -> IOMode -> IO Handle
openTempFile :: AbsOrRelClass ar => DirPath ar -> RelFile -> IO (AbsFile, Handle)
openBinaryTempFile :: AbsOrRelClass ar => DirPath ar -> RelFile -> IO (AbsFile, Handle)
-- | A value of type IO a is a computation which, when
-- performed, does some I/O before returning a value of type a.
--
-- There is really only one way to "perform" an I/O action: bind it to
-- Main.main in your program. When your program is run, the I/O
-- will be performed. It isn't possible to perform I/O from an arbitrary
-- function, unless that function is itself in the IO monad and
-- called at some point, directly or indirectly, from Main.main.
--
-- IO is a monad, so IO actions can be combined using
-- either the do-notation or the >> and >>=
-- operations from the Monad class.
data IO a :: * -> *
fixIO :: (a -> IO a) -> IO a
-- | Haskell defines operations to read and write characters from and to
-- files, represented by values of type Handle. Each value of
-- this type is a handle: a record used by the Haskell run-time
-- system to manage I/O with file system objects. A handle has at
-- least the following properties:
--
--
-- - whether it manages input or output or both;
-- - whether it is open, closed or
-- semi-closed;
-- - whether the object is seekable;
-- - whether buffering is disabled, or enabled on a line or block
-- basis;
-- - a buffer (whose length may be zero).
--
--
-- Most handles will also have a current I/O position indicating where
-- the next input or output operation will occur. A handle is
-- readable if it manages only input or both input and output;
-- likewise, it is writable if it manages only output or both
-- input and output. A handle is open when first allocated. Once
-- it is closed it can no longer be used for either input or output,
-- though an implementation cannot re-use its storage while references
-- remain to it. Handles are in the Show and Eq classes.
-- The string produced by showing a handle is system dependent; it should
-- include enough information to identify the handle for debugging. A
-- handle is equal according to == only to itself; no attempt is
-- made to compare the internal state of different handles for equality.
data Handle :: *
-- | A handle managing input from the Haskell program's standard input
-- channel.
stdin :: Handle
-- | A handle managing output to the Haskell program's standard output
-- channel.
stdout :: Handle
-- | A handle managing output to the Haskell program's standard error
-- channel.
stderr :: Handle
-- | See openFile
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode
-- | Computation hClose hdl makes handle hdl
-- closed. Before the computation finishes, if hdl is writable
-- its buffer is flushed as for hFlush. Performing hClose
-- on a handle that has already been closed has no effect; doing so is
-- not an error. All other operations on a closed handle will fail. If
-- hClose fails for any reason, any further operations (apart from
-- hClose) on the handle will still fail as if hdl had
-- been successfully closed.
hClose :: Handle -> IO ()
-- | For a handle hdl which attached to a physical file,
-- hFileSize hdl returns the size of that file in 8-bit
-- bytes.
hFileSize :: Handle -> IO Integer
-- | hSetFileSize hdl size truncates the physical
-- file with handle hdl to size bytes.
hSetFileSize :: Handle -> Integer -> IO ()
-- | For a readable handle hdl, hIsEOF hdl returns
-- True if no further input can be taken from hdl or for
-- a physical file, if the current I/O position is equal to the length of
-- the file. Otherwise, it returns False.
--
-- NOTE: hIsEOF may block, because it has to attempt to read from
-- the stream to determine whether there is any more data to be read.
hIsEOF :: Handle -> IO Bool
-- | The computation isEOF is identical to hIsEOF, except
-- that it works only on stdin.
isEOF :: IO Bool
-- | Three kinds of buffering are supported: line-buffering,
-- block-buffering or no-buffering. These modes have the following
-- effects. For output, items are written out, or flushed, from
-- the internal buffer according to the buffer mode:
--
--
-- - line-buffering: the entire output buffer is flushed
-- whenever a newline is output, the buffer overflows, a hFlush is
-- issued, or the handle is closed.
-- - block-buffering: the entire buffer is written out whenever
-- it overflows, a hFlush is issued, or the handle is closed.
-- - no-buffering: output is written immediately, and never
-- stored in the buffer.
--
--
-- An implementation is free to flush the buffer more frequently, but not
-- less frequently, than specified above. The output buffer is emptied as
-- soon as it has been written out.
--
-- Similarly, input occurs according to the buffer mode for the handle:
--
--
-- - line-buffering: when the buffer for the handle is not
-- empty, the next item is obtained from the buffer; otherwise, when the
-- buffer is empty, characters up to and including the next newline
-- character are read into the buffer. No characters are available until
-- the newline character is available or the buffer is full.
-- - block-buffering: when the buffer for the handle becomes
-- empty, the next block of data is read into the buffer.
-- - no-buffering: the next input item is read and returned. The
-- hLookAhead operation implies that even a no-buffered handle may
-- require a one-character buffer.
--
--
-- The default buffering mode when a handle is opened is
-- implementation-dependent and may depend on the file system object
-- which is attached to that handle. For most implementations, physical
-- files will normally be block-buffered and terminals will normally be
-- line-buffered.
data BufferMode :: *
-- | buffering is disabled if possible.
NoBuffering :: BufferMode
-- | line-buffering should be enabled if possible.
LineBuffering :: BufferMode
-- | block-buffering should be enabled if possible. The size of the buffer
-- is n items if the argument is Just n and is
-- otherwise implementation-dependent.
BlockBuffering :: Maybe Int -> BufferMode
-- | Computation hSetBuffering hdl mode sets the mode of
-- buffering for handle hdl on subsequent reads and writes.
--
-- If the buffer mode is changed from BlockBuffering or
-- LineBuffering to NoBuffering, then
--
--
-- - if hdl is writable, the buffer is flushed as for
-- hFlush;
-- - if hdl is not writable, the contents of the buffer is
-- discarded.
--
--
-- This operation may fail with:
--
--
-- - isPermissionError if the handle has already been used for
-- reading or writing and the implementation does not allow the buffering
-- mode to be changed.
--
hSetBuffering :: Handle -> BufferMode -> IO ()
-- | Computation hGetBuffering hdl returns the current
-- buffering mode for hdl.
hGetBuffering :: Handle -> IO BufferMode
-- | The action hFlush hdl causes any items buffered for
-- output in handle hdl to be sent immediately to the operating
-- system.
--
-- This operation may fail with:
--
--
-- - isFullError if the device is full;
-- - isPermissionError if a system resource limit would be
-- exceeded. It is unspecified whether the characters in the buffer are
-- discarded or retained under these circumstances.
--
hFlush :: Handle -> IO ()
-- | Computation hGetPosn hdl returns the current I/O
-- position of hdl as a value of the abstract type
-- HandlePosn.
hGetPosn :: Handle -> IO HandlePosn
-- | If a call to hGetPosn hdl returns a position
-- p, then computation hSetPosn p sets the
-- position of hdl to the position it held at the time of the
-- call to hGetPosn.
--
-- This operation may fail with:
--
--
-- - isPermissionError if a system resource limit would be
-- exceeded.
--
hSetPosn :: HandlePosn -> IO ()
data HandlePosn :: *
-- | Computation hSeek hdl mode i sets the position of
-- handle hdl depending on mode. The offset i
-- is given in terms of 8-bit bytes.
--
-- If hdl is block- or line-buffered, then seeking to a position
-- which is not in the current buffer will first cause any items in the
-- output buffer to be written to the device, and then cause the input
-- buffer to be discarded. Some handles may not be seekable (see
-- hIsSeekable), or only support a subset of the possible
-- positioning operations (for instance, it may only be possible to seek
-- to the end of a tape, or to a positive offset from the beginning or
-- current position). It is not possible to set a negative I/O position,
-- or for a physical file, an I/O position beyond the current
-- end-of-file.
--
-- This operation may fail with:
--
--
-- - isIllegalOperationError if the Handle is not seekable, or
-- does not support the requested seek mode.
-- - isPermissionError if a system resource limit would be
-- exceeded.
--
hSeek :: Handle -> SeekMode -> Integer -> IO ()
-- | A mode that determines the effect of hSeek hdl mode
-- i.
data SeekMode :: *
-- | the position of hdl is set to i.
AbsoluteSeek :: SeekMode
-- | the position of hdl is set to offset i from the
-- current position.
RelativeSeek :: SeekMode
-- | the position of hdl is set to offset i from the end
-- of the file.
SeekFromEnd :: SeekMode
-- | Computation hTell hdl returns the current position of
-- the handle hdl, as the number of bytes from the beginning of
-- the file. The value returned may be subsequently passed to
-- hSeek to reposition the handle to the current position.
--
-- This operation may fail with:
--
--
-- - isIllegalOperationError if the Handle is not
-- seekable.
--
hTell :: Handle -> IO Integer
hIsOpen :: Handle -> IO Bool
hIsClosed :: Handle -> IO Bool
hIsReadable :: Handle -> IO Bool
hIsWritable :: Handle -> IO Bool
hIsSeekable :: Handle -> IO Bool
-- | Is the handle connected to a terminal?
hIsTerminalDevice :: Handle -> IO Bool
-- | Set the echoing status of a handle connected to a terminal.
hSetEcho :: Handle -> Bool -> IO ()
-- | Get the echoing status of a handle connected to a terminal.
hGetEcho :: Handle -> IO Bool
-- | hShow is in the IO monad, and gives more comprehensive
-- output than the (pure) instance of Show for Handle.
hShow :: Handle -> IO String
-- | Computation hWaitForInput hdl t waits until input is
-- available on handle hdl. It returns True as soon as
-- input is available on hdl, or False if no input is
-- available within t milliseconds. Note that
-- hWaitForInput waits until one or more full characters
-- are available, which means that it needs to do decoding, and hence may
-- fail with a decoding error.
--
-- If t is less than zero, then hWaitForInput waits
-- indefinitely.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file has been reached.
-- - a decoding error, if the input begins with an invalid byte
-- sequence in this Handle's encoding.
--
--
-- NOTE for GHC users: unless you use the -threaded flag,
-- hWaitForInput hdl t where t >= 0 will block all
-- other Haskell threads for the duration of the call. It behaves like a
-- safe foreign call in this respect.
hWaitForInput :: Handle -> Int -> IO Bool
-- | Computation hReady hdl indicates whether at least one
-- item is available for input from handle hdl.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file has been reached.
--
hReady :: Handle -> IO Bool
-- | Computation hGetChar hdl reads a character from the
-- file or channel managed by hdl, blocking until a character is
-- available.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file has been reached.
--
hGetChar :: Handle -> IO Char
-- | Computation hGetLine hdl reads a line from the file or
-- channel managed by hdl.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file is encountered when reading
-- the first character of the line.
--
--
-- If hGetLine encounters end-of-file at any other point while
-- reading in a line, it is treated as a line terminator and the
-- (partial) line is returned.
hGetLine :: Handle -> IO String
-- | Computation hLookAhead returns the next character from the
-- handle without removing it from the input buffer, blocking until a
-- character is available.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file has been reached.
--
hLookAhead :: Handle -> IO Char
-- | Computation hGetContents hdl returns the list of
-- characters corresponding to the unread portion of the channel or file
-- managed by hdl, which is put into an intermediate state,
-- semi-closed. In this state, hdl is effectively closed,
-- but items are read from hdl on demand and accumulated in a
-- special list returned by hGetContents hdl.
--
-- Any operation that fails because a handle is closed, also fails if a
-- handle is semi-closed. The only exception is hClose. A
-- semi-closed handle becomes closed:
--
--
-- - if hClose is applied to it;
-- - if an I/O error occurs when reading an item from the handle;
-- - or once the entire contents of the handle has been read.
--
--
-- Once a semi-closed handle becomes closed, the contents of the
-- associated list becomes fixed. The contents of this final list is only
-- partially specified: it will contain at least all the items of the
-- stream that were evaluated prior to the handle becoming closed.
--
-- Any I/O errors encountered while a handle is semi-closed are simply
-- discarded.
--
-- This operation may fail with:
--
--
-- - isEOFError if the end of file has been reached.
--
hGetContents :: Handle -> IO String
-- | Computation hPutChar hdl ch writes the character
-- ch to the file or channel managed by hdl. Characters
-- may be buffered if buffering is enabled for hdl.
--
-- This operation may fail with:
--
--
hPutChar :: Handle -> Char -> IO ()
-- | Computation hPutStr hdl s writes the string s
-- to the file or channel managed by hdl.
--
-- This operation may fail with:
--
--
hPutStr :: Handle -> String -> IO ()
-- | The same as hPutStr, but adds a newline character.
hPutStrLn :: Handle -> String -> IO ()
-- | Computation hPrint hdl t writes the string
-- representation of t given by the shows function to the
-- file or channel managed by hdl and appends a newline.
--
-- This operation may fail with:
--
--
hPrint :: Show a => Handle -> a -> IO ()
-- | The interact function takes a function of type
-- String->String as its argument. The entire input from the
-- standard input device is passed to this function as its argument, and
-- the resulting string is output on the standard output device.
interact :: (String -> String) -> IO ()
-- | Write a character to the standard output device (same as
-- hPutChar stdout).
putChar :: Char -> IO ()
-- | Write a string to the standard output device (same as hPutStr
-- stdout).
putStr :: String -> IO ()
-- | The same as putStr, but adds a newline character.
putStrLn :: String -> IO ()
-- | The print function outputs a value of any printable type to the
-- standard output device. Printable types are those that are instances
-- of class Show; print converts values to strings for
-- output using the show operation and adds a newline.
--
-- For example, a program to print the first 20 integers and their powers
-- of 2 could be written as:
--
--
-- main = print ([(n, 2^n) | n <- [0..19]])
--
print :: Show a => a -> IO ()
-- | Read a character from the standard input device (same as
-- hGetChar stdin).
getChar :: IO Char
-- | Read a line from the standard input device (same as hGetLine
-- stdin).
getLine :: IO String
-- | The getContents operation returns all user input as a single
-- string, which is read lazily as it is needed (same as
-- hGetContents stdin).
getContents :: IO String
-- | The readIO function is similar to read except that it
-- signals parse failure to the IO monad instead of terminating
-- the program.
readIO :: Read a => String -> IO a
-- | The readLn function combines getLine and readIO.
readLn :: Read a => IO a
-- | Select binary mode (True) or text mode (False) on a open
-- handle. (See also openBinaryFile.)
--
-- This has the same effect as calling hSetEncoding with
-- char8, together with hSetNewlineMode with
-- noNewlineTranslation.
hSetBinaryMode :: Handle -> Bool -> IO ()
-- | hPutBuf hdl buf count writes count 8-bit
-- bytes from the buffer buf to the handle hdl. It
-- returns ().
--
-- hPutBuf ignores any text encoding that applies to the
-- Handle, writing the bytes directly to the underlying file or
-- device.
--
-- hPutBuf ignores the prevailing TextEncoding and
-- NewlineMode on the Handle, and writes bytes directly.
--
-- This operation may fail with:
--
--
-- - ResourceVanished if the handle is a pipe or socket, and the
-- reading end is closed. (If this is a POSIX system, and the program has
-- not asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead,
-- whose default action is to terminate the program).
--
hPutBuf :: Handle -> Ptr a -> Int -> IO ()
-- | hGetBuf hdl buf count reads data from the handle
-- hdl into the buffer buf until either EOF is reached
-- or count 8-bit bytes have been read. It returns the number of
-- bytes actually read. This may be zero if EOF was reached before any
-- data was read (or if count is zero).
--
-- hGetBuf never raises an EOF exception, instead it returns a
-- value smaller than count.
--
-- If the handle is a pipe or socket, and the writing end is closed,
-- hGetBuf will behave as if EOF was reached.
--
-- hGetBuf ignores the prevailing TextEncoding and
-- NewlineMode on the Handle, and reads bytes directly.
hGetBuf :: Handle -> Ptr a -> Int -> IO Int
hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
-- | hGetBufNonBlocking hdl buf count reads data from the
-- handle hdl into the buffer buf until either EOF is
-- reached, or count 8-bit bytes have been read, or there is no
-- more data available to read immediately.
--
-- hGetBufNonBlocking is identical to hGetBuf, except that
-- it will never block waiting for data to become available, instead it
-- returns only whatever data is available. To wait for data to arrive
-- before calling hGetBufNonBlocking, use hWaitForInput.
--
-- If the handle is a pipe or socket, and the writing end is closed,
-- hGetBufNonBlocking will behave as if EOF was reached.
--
-- hGetBufNonBlocking ignores the prevailing TextEncoding
-- and NewlineMode on the Handle, and reads bytes directly.
--
-- NOTE: on Windows, this function does not work correctly; it behaves
-- identically to hGetBuf.
hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int