-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Support for well-typed paths
--
-- Support for well-typed paths, utilizing ByteString under the hood.
@package hpath
@version 0.9.1
module System.Posix.Directory.Foreign
newtype DirType
DirType :: Int -> DirType
data Flags
Flags :: Int -> Flags
UnsupportedFlag :: String -> Flags
unFlags :: Flags -> Int
-- | Returns True if posix-paths was compiled with support for the
-- provided flag. (As of this writing, the only flag for which this check
-- may be necessary is oCloexec; all other flags will always yield
-- True.)
isSupported :: Flags -> Bool
-- | O_CLOEXEC is not supported on every POSIX platform. Use
-- isSupported oCloexec to determine if support for
-- O_CLOEXEC was compiled into your version of posix-paths. (If
-- not, using oCloexec will throw an exception.)
oCloexec :: Flags
dtBlk :: DirType
oAppend :: Flags
dtChr :: DirType
pathMax :: Int
oAsync :: Flags
dtDir :: DirType
oCreat :: Flags
dtFifo :: DirType
unionFlags :: [Flags] -> CInt
dtLnk :: DirType
oDirectory :: Flags
oExcl :: Flags
dtReg :: DirType
oNoctty :: Flags
dtSock :: DirType
oNofollow :: Flags
dtUnknown :: DirType
oNonblock :: Flags
oRdonly :: Flags
oWronly :: Flags
oRdwr :: Flags
oSync :: Flags
oTrunc :: Flags
instance GHC.Show.Show System.Posix.Directory.Foreign.Flags
instance GHC.Classes.Eq System.Posix.Directory.Foreign.Flags
instance GHC.Show.Show System.Posix.Directory.Foreign.DirType
instance GHC.Classes.Eq System.Posix.Directory.Foreign.DirType
-- | Provides an alternative for openFd which gives us more control
-- on what status flags to pass to the low-level open(2) call,
-- in contrast to the unix package.
module System.Posix.FD
-- | Open and optionally create this file. See Files for information
-- on how to use the FileMode type.
--
-- Note that passing Just x as the 4th argument triggers the
-- oCreat status flag, which must be set when you pass in
-- oExcl to the status flags. Also see the manpage for
-- open(2).
openFd :: RawFilePath -> OpenMode -> [Flags] -> Maybe FileMode -> IO Fd
-- | The equivalent of System.FilePath on raw (byte string) file
-- paths.
--
-- Not all functions of System.FilePath are implemented yet. Feel
-- free to contribute!
module System.Posix.FilePath
-- | Path separator character
pathSeparator :: Word8
-- | Check if a character is the path separator
--
--
-- \n -> (_chr n == '/') == isPathSeparator n
--
isPathSeparator :: Word8 -> Bool
-- | Search path separator
searchPathSeparator :: Word8
-- | Check if a character is the search path separator
--
--
-- \n -> (_chr n == ':') == isSearchPathSeparator n
--
isSearchPathSeparator :: Word8 -> Bool
-- | File extension separator
extSeparator :: Word8
-- | Check if a character is the file extension separator
--
--
-- \n -> (_chr n == '.') == isExtSeparator n
--
isExtSeparator :: Word8 -> Bool
-- | 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 ""
-- ["."]
--
splitSearchPath :: ByteString -> [RawFilePath]
-- | Get a list of RawFilePaths in the $PATH variable.
getSearchPath :: IO [RawFilePath]
-- | 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
--
splitExtension :: RawFilePath -> (RawFilePath, ByteString)
-- | Get the final extension from a RawFilePath
--
--
-- >>> takeExtension "file.exe"
-- ".exe"
--
-- >>> takeExtension "file"
-- ""
--
-- >>> takeExtension "/path/file.tar.gz"
-- ".gz"
--
takeExtension :: RawFilePath -> ByteString
-- | Change a file's extension
--
--
-- \path -> let ext = takeExtension path in replaceExtension path ext == path
--
replaceExtension :: RawFilePath -> ByteString -> RawFilePath
-- | Drop the final extension from a RawFilePath
--
--
-- >>> dropExtension "file.exe"
-- "file"
--
-- >>> dropExtension "file"
-- "file"
--
-- >>> dropExtension "/path/file.tar.gz"
-- "/path/file.tar"
--
dropExtension :: RawFilePath -> RawFilePath
-- | Add an extension to a RawFilePath
--
--
-- >>> addExtension "file" ".exe"
-- "file.exe"
--
-- >>> addExtension "file.tar" ".gz"
-- "file.tar.gz"
--
-- >>> addExtension "/path/" ".ext"
-- "/path/.ext"
--
addExtension :: RawFilePath -> ByteString -> RawFilePath
-- | Check if a RawFilePath has an extension
--
--
-- >>> hasExtension "file"
-- False
--
-- >>> hasExtension "file.tar"
-- True
--
-- >>> hasExtension "/path.part1/"
-- False
--
hasExtension :: RawFilePath -> Bool
-- | Operator version of addExtension
(<.>) :: RawFilePath -> ByteString -> RawFilePath
-- | Split a RawFilePath on the first extension.
--
--
-- >>> splitExtensions "/path/file.tar.gz"
-- ("/path/file",".tar.gz")
--
--
--
-- \path -> uncurry addExtension (splitExtensions path) == path
--
splitExtensions :: RawFilePath -> (RawFilePath, ByteString)
-- | Remove all extensions from a RawFilePath
--
--
-- >>> dropExtensions "/path/file.tar.gz"
-- "/path/file"
--
dropExtensions :: RawFilePath -> RawFilePath
-- | Take all extensions from a RawFilePath
--
--
-- >>> takeExtensions "/path/file.tar.gz"
-- ".tar.gz"
--
takeExtensions :: RawFilePath -> ByteString
-- | 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)
--
stripExtension :: ByteString -> RawFilePath -> Maybe 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) == "./"
--
splitFileName :: RawFilePath -> (RawFilePath, RawFilePath)
-- | Get the file name
--
--
-- >>> takeFileName "path/file.txt"
-- "file.txt"
--
-- >>> takeFileName "path/"
-- ""
--
takeFileName :: RawFilePath -> RawFilePath
-- | Change the file name
--
--
-- \path -> replaceFileName path (takeFileName path) == path
--
replaceFileName :: RawFilePath -> ByteString -> RawFilePath
-- | Drop the file name
--
--
-- >>> dropFileName "path/file.txt"
-- "path/"
--
-- >>> dropFileName "file.txt"
-- "./"
--
dropFileName :: RawFilePath -> RawFilePath
-- | Get the file name, without a trailing extension
--
--
-- >>> takeBaseName "path/file.tar.gz"
-- "file.tar"
--
-- >>> takeBaseName ""
-- ""
--
takeBaseName :: RawFilePath -> ByteString
-- | Change the base name
--
--
-- >>> replaceBaseName "path/file.tar.gz" "bob"
-- "path/bob.gz"
--
--
--
-- \path -> replaceBaseName path (takeBaseName path) == path
--
replaceBaseName :: RawFilePath -> ByteString -> 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"
--
takeDirectory :: RawFilePath -> RawFilePath
-- | Change the directory component of a RawFilePath
--
--
-- \path -> replaceDirectory path (takeDirectory path) `equalFilePath` path || takeDirectory path == "."
--
replaceDirectory :: RawFilePath -> ByteString -> RawFilePath
-- | Join two paths together
--
--
-- >>> combine "/" "file"
-- "/file"
--
-- >>> combine "/path/to" "file"
-- "/path/to/file"
--
-- >>> combine "file" "/absolute/path"
-- "/absolute/path"
--
combine :: RawFilePath -> RawFilePath -> RawFilePath
-- | Operator version of combine
() :: RawFilePath -> 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
--
splitPath :: RawFilePath -> [RawFilePath]
-- | Join a split path back together
--
--
-- \path -> joinPath (splitPath path) == path
--
--
--
-- >>> joinPath ["path","to","file.txt"]
-- "path/to/file.txt"
--
joinPath :: [RawFilePath] -> RawFilePath
-- | Like splitPath, but without trailing slashes
--
--
-- >>> splitDirectories "/path/to/file.txt"
-- ["/","path","to","file.txt"]
--
-- >>> splitDirectories ""
-- []
--
splitDirectories :: RawFilePath -> [RawFilePath]
-- | Check if the last character of a RawFilePath is /.
--
--
-- >>> hasTrailingPathSeparator "/path/"
-- True
--
-- >>> hasTrailingPathSeparator "/"
-- True
--
-- >>> hasTrailingPathSeparator "/path"
-- False
--
hasTrailingPathSeparator :: RawFilePath -> Bool
-- | Add a trailing path separator.
--
--
-- >>> addTrailingPathSeparator "/path"
-- "/path/"
--
-- >>> addTrailingPathSeparator "/path/"
-- "/path/"
--
-- >>> addTrailingPathSeparator "/"
-- "/"
--
addTrailingPathSeparator :: RawFilePath -> RawFilePath
-- | Remove a trailing path separator
--
--
-- >>> dropTrailingPathSeparator "/path/"
-- "/path"
--
-- >>> dropTrailingPathSeparator "/path////"
-- "/path"
--
-- >>> dropTrailingPathSeparator "/"
-- "/"
--
-- >>> dropTrailingPathSeparator "//"
-- "/"
--
dropTrailingPathSeparator :: 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"
--
normalise :: 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
makeRelative :: RawFilePath -> RawFilePath -> RawFilePath
-- | 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
--
equalFilePath :: RawFilePath -> RawFilePath -> Bool
-- | Check if a path is relative
--
--
-- \path -> isRelative path /= isAbsolute path
--
isRelative :: RawFilePath -> Bool
-- | Check if a path is absolute
--
--
-- >>> isAbsolute "/path"
-- True
--
-- >>> isAbsolute "path"
-- False
--
-- >>> isAbsolute ""
-- False
--
isAbsolute :: RawFilePath -> Bool
-- | Is a FilePath valid, i.e. could you create a file like it?
--
--
-- >>> isValid ""
-- False
--
-- >>> isValid "\0"
-- False
--
-- >>> isValid "/random_ path:*"
-- True
--
isValid :: RawFilePath -> Bool
-- | 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)
--
makeValid :: RawFilePath -> RawFilePath
-- | 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
--
isFileName :: 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
--
hasParentDir :: 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
--
hiddenFile :: RawFilePath -> Bool
-- | Traversal and read operations on directories.
module System.Posix.Directory.Traversals
-- | Gets all directory contents (not recursively).
getDirectoryContents :: RawFilePath -> IO [(DirType, RawFilePath)]
-- | Like getDirectoryContents except for a file descriptor.
--
-- To avoid complicated error checks, the file descriptor is
-- always closed, even if fdOpendir fails. Usually, this
-- only happens on successful fdOpendir and after the directory
-- stream is closed. Also see the manpage of fdopendir(3) for
-- more details.
getDirectoryContents' :: Fd -> IO [(DirType, RawFilePath)]
-- | Get all files from a directory and its subdirectories.
--
-- Upon entering a directory, allDirectoryContents will get all
-- entries strictly. However the returned list is lazy in that
-- directories will only be accessed on demand.
--
-- Follows symbolic links for the input dir.
allDirectoryContents :: RawFilePath -> IO [RawFilePath]
-- | Get all files from a directory and its subdirectories strictly.
--
-- Follows symbolic links for the input dir.
allDirectoryContents' :: RawFilePath -> IO [RawFilePath]
-- | Recursively apply the action to the parent directory and all
-- files/subdirectories.
--
-- This function allows for memory-efficient traversals.
--
-- Follows symbolic links for the input dir.
traverseDirectory :: (s -> RawFilePath -> IO s) -> s -> RawFilePath -> IO s
readDirEnt :: DirStream -> IO (DirType, RawFilePath)
packDirStream :: Ptr CDir -> DirStream
unpackDirStream :: DirStream -> Ptr CDir
-- | Binding to fdopendir(3).
fdOpendir :: Fd -> IO DirStream
-- | return the canonicalized absolute pathname
--
-- like canonicalizePath, but uses realpath(3)
realpath :: RawFilePath -> IO RawFilePath
-- | Support for well-typed paths.
module HPath
-- | An absolute path.
data Abs
-- | Path of some base and type.
--
-- Internally is a ByteString. The ByteString can be of two formats only:
--
--
-- - without trailing path separator: file.txt,
-- foo/bar.txt, /foo/bar.txt
-- - with trailing path separator: foo/,
-- /foo/bar/
--
--
-- There are no duplicate path separators //, no .., no
-- ./, no ~/, etc.
data Path b
-- | A relative path; one without a root.
data Rel
-- | A filename, without any /.
data Fn
-- | Exception when parsing a location.
data PathParseException
data PathException
class RelC m
-- | Get a location for an absolute path. Produces a normalised path.
--
-- Throws: PathParseException
--
--
-- >>> parseAbs "/abc" :: Maybe (Path Abs)
-- Just "/abc"
--
-- >>> parseAbs "/" :: Maybe (Path Abs)
-- Just "/"
--
-- >>> parseAbs "/abc/def" :: Maybe (Path Abs)
-- Just "/abc/def"
--
-- >>> parseAbs "/abc/def/.///" :: Maybe (Path Abs)
-- Just "/abc/def/"
--
-- >>> parseAbs "abc" :: Maybe (Path Abs)
-- Nothing
--
-- >>> parseAbs "" :: Maybe (Path Abs)
-- Nothing
--
-- >>> parseAbs "/abc/../foo" :: Maybe (Path Abs)
-- Nothing
--
parseAbs :: MonadThrow m => ByteString -> m (Path Abs)
-- | Parses a filename. Filenames must not contain slashes. Excludes
-- . and '..'.
--
-- Throws: PathParseException
--
--
-- >>> parseFn "abc" :: Maybe (Path Fn)
-- Just "abc"
--
-- >>> parseFn "..." :: Maybe (Path Fn)
-- Just "..."
--
-- >>> parseFn "def/" :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "abc/def" :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "abc/def/." :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "/abc" :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "" :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "abc/../foo" :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn "." :: Maybe (Path Fn)
-- Nothing
--
-- >>> parseFn ".." :: Maybe (Path Fn)
-- Nothing
--
parseFn :: MonadThrow m => ByteString -> m (Path Fn)
-- | Get a location for a relative path. Produces a normalised path.
--
-- Note that filepath may contain any number of ./ but
-- may not consist solely of ./. It also may not contain a
-- single .. anywhere.
--
-- Throws: PathParseException
--
--
-- >>> parseRel "abc" :: Maybe (Path Rel)
-- Just "abc"
--
-- >>> parseRel "def/" :: Maybe (Path Rel)
-- Just "def/"
--
-- >>> parseRel "abc/def" :: Maybe (Path Rel)
-- Just "abc/def"
--
-- >>> parseRel "abc/def/." :: Maybe (Path Rel)
-- Just "abc/def/"
--
-- >>> parseRel "/abc" :: Maybe (Path Rel)
-- Nothing
--
-- >>> parseRel "" :: Maybe (Path Rel)
-- Nothing
--
-- >>> parseRel "abc/../foo" :: Maybe (Path Rel)
-- Nothing
--
-- >>> parseRel "." :: Maybe (Path Rel)
-- Nothing
--
-- >>> parseRel ".." :: Maybe (Path Rel)
-- Nothing
--
parseRel :: MonadThrow m => ByteString -> m (Path Rel)
-- | Convert an absolute Path to a ByteString type.
fromAbs :: Path Abs -> ByteString
-- | Convert a relative Path to a ByteString type.
fromRel :: RelC r => Path r -> ByteString
-- | Convert any Path to a ByteString type.
toFilePath :: Path b -> ByteString
-- | Append two paths.
--
-- The second argument must always be a relative path, which ensures that
-- undefinable things like `"abc" <> "/def"` cannot happen.
--
-- Technically, the first argument can be a path that points to a
-- non-directory, because this library is IO-agnostic and makes no
-- assumptions about file types.
--
--
-- >>> (MkPath "/") </> (MkPath "file" :: Path Rel)
-- "/file"
--
-- >>> (MkPath "/path/to") </> (MkPath "file" :: Path Rel)
-- "/path/to/file"
--
-- >>> (MkPath "/") </> (MkPath "file/lal" :: Path Rel)
-- "/file/lal"
--
-- >>> (MkPath "/") </> (MkPath "file/" :: Path Rel)
-- "/file/"
--
() :: RelC r => Path b -> Path r -> Path b
-- | Extract the file part of a path.
--
-- The following properties hold:
--
--
-- basename (p </> a) == basename a
--
--
-- Throws: PathException if given the root path "/"
--
--
-- >>> basename (MkPath "/abc/def/dod") :: Maybe (Path Fn)
-- Just "dod"
--
-- >>> basename (MkPath "/abc/def/dod/") :: Maybe (Path Fn)
-- Just "dod"
--
-- >>> basename (MkPath "/") :: Maybe (Path Fn)
-- Nothing
--
basename :: MonadThrow m => Path b -> m (Path Fn)
-- | Extract the directory name of a path.
--
--
-- >>> dirname (MkPath "/abc/def/dod")
-- "/abc/def"
--
-- >>> dirname (MkPath "/")
-- "/"
--
dirname :: Path Abs -> Path Abs
-- | Is p a parent of the given location? Implemented in terms of
-- stripDir. The bases must match.
--
--
-- >>> (MkPath "/lal/lad") `isParentOf` (MkPath "/lal/lad/fad")
-- True
--
-- >>> (MkPath "lal/lad") `isParentOf` (MkPath "lal/lad/fad")
-- True
--
-- >>> (MkPath "/") `isParentOf` (MkPath "/")
-- False
--
-- >>> (MkPath "/lal/lad/fad") `isParentOf` (MkPath "/lal/lad")
-- False
--
-- >>> (MkPath "fad") `isParentOf` (MkPath "fad")
-- False
--
isParentOf :: Path b -> Path b -> Bool
-- | Get all parents of a path.
--
--
-- >>> getAllParents (MkPath "/abs/def/dod")
-- ["/abs/def","/abs","/"]
--
-- >>> getAllParents (MkPath "/")
-- []
--
getAllParents :: Path Abs -> [Path Abs]
-- | Strip directory from path, making it relative to that directory.
-- Throws Couldn'tStripPrefixDir if directory is not a parent of
-- the path.
--
-- The bases must match.
--
--
-- >>> (MkPath "/lal/lad") `stripDir` (MkPath "/lal/lad/fad") :: Maybe (Path Rel)
-- Just "fad"
--
-- >>> (MkPath "lal/lad") `stripDir` (MkPath "lal/lad/fad") :: Maybe (Path Rel)
-- Just "fad"
--
-- >>> (MkPath "/") `stripDir` (MkPath "/") :: Maybe (Path Rel)
-- Nothing
--
-- >>> (MkPath "/lal/lad/fad") `stripDir` (MkPath "/lal/lad") :: Maybe (Path Rel)
-- Nothing
--
-- >>> (MkPath "fad") `stripDir` (MkPath "fad") :: Maybe (Path Rel)
-- Nothing
--
stripDir :: MonadThrow m => Path b -> Path b -> m (Path Rel)
withAbsPath :: Path Abs -> (ByteString -> IO a) -> IO a
withRelPath :: Path Rel -> (ByteString -> IO a) -> IO a
withFnPath :: Path Fn -> (ByteString -> IO a) -> IO a
instance GHC.Show.Show HPath.PathException
instance GHC.Show.Show HPath.PathParseException
instance HPath.RelC HPath.Rel
instance HPath.RelC HPath.Fn
instance GHC.Exception.Exception HPath.PathException
instance GHC.Exception.Exception HPath.PathParseException
-- | Provides error handling.
module HPath.IO.Errors
-- | Additional generic IO exceptions that the posix functions do not
-- provide.
data HPathIOException
SameFile :: ByteString -> ByteString -> HPathIOException
DestinationInSource :: ByteString -> ByteString -> HPathIOException
RecursiveFailure :: [(RecursiveFailureHint, IOException)] -> HPathIOException
-- | A type for giving failure hints on recursive failure, which allows to
-- programmatically make choices without examining the weakly typed I/O
-- error attributes (like ioeGetFileName).
--
-- The first argument to the data constructor is always the source and
-- the second the destination.
data RecursiveFailureHint
ReadContentsFailed :: ByteString -> ByteString -> RecursiveFailureHint
CreateDirFailed :: ByteString -> ByteString -> RecursiveFailureHint
CopyFileFailed :: ByteString -> ByteString -> RecursiveFailureHint
RecreateSymlinkFailed :: ByteString -> ByteString -> RecursiveFailureHint
isSameFile :: HPathIOException -> Bool
isDestinationInSource :: HPathIOException -> Bool
isRecursiveFailure :: HPathIOException -> Bool
isReadContentsFailed :: RecursiveFailureHint -> Bool
isCreateDirFailed :: RecursiveFailureHint -> Bool
isCopyFileFailed :: RecursiveFailureHint -> Bool
isRecreateSymlinkFailed :: RecursiveFailureHint -> Bool
-- | Throws AlreadyExists IOError if file exists.
throwFileDoesExist :: Path b -> IO ()
-- | Throws AlreadyExists IOError if directory exists.
throwDirDoesExist :: Path b -> IO ()
-- | Uses isSameFile and throws SameFile if it returns True.
throwSameFile :: Path b1 -> Path b2 -> IO ()
-- | Check if the files are the same by examining device and file id. This
-- follows symbolic links.
sameFile :: Path b1 -> Path b2 -> IO Bool
-- | Checks whether the destination directory is contained within the
-- source directory by comparing the device+file ID of the source
-- directory with all device+file IDs of the parent directories of the
-- destination.
throwDestinationInSource :: Path b1 -> Path b2 -> IO ()
-- | Checks if the given file exists and is not a directory. Does not
-- follow symlinks.
doesFileExist :: Path b -> IO Bool
-- | Checks if the given file exists and is a directory. Does not follow
-- symlinks.
doesDirectoryExist :: Path b -> IO Bool
-- | Checks whether a file or folder is writable.
isWritable :: Path b -> IO Bool
-- | Checks whether the directory at the given path exists and can be
-- opened. This invokes openDirStream which follows symlinks.
canOpenDirectory :: Path b -> IO Bool
-- | Carries out an action, then checks if there is an IOException and a
-- specific errno. If so, then it carries out another action, otherwise
-- it rethrows the error.
catchErrno :: [Errno] -> IO a -> IO a -> IO a
-- | Execute the given action and retrow IO exceptions as a new Exception
-- that have the given errno. If errno does not match the exception is
-- rethrown as is.
rethrowErrnoAs :: Exception e => [Errno] -> e -> IO a -> IO a
-- | Like catchIOError, with arguments swapped.
handleIOError :: (IOError -> IO a) -> IO a -> IO a
-- | Like bracket, but allows to have different clean-up actions
-- depending on whether the in-between computation has raised an
-- exception or not.
bracketeer :: IO a -> (a -> IO b) -> (a -> IO b) -> (a -> IO c) -> IO c
reactOnError :: IO a -> [(IOErrorType, IO a)] -> [(HPathIOException, IO a)] -> IO a
instance GHC.Show.Show HPath.IO.Errors.HPathIOException
instance GHC.Classes.Eq HPath.IO.Errors.HPathIOException
instance GHC.Show.Show HPath.IO.Errors.RecursiveFailureHint
instance GHC.Classes.Eq HPath.IO.Errors.RecursiveFailureHint
instance GHC.Exception.Exception HPath.IO.Errors.HPathIOException
-- | This module provides high-level IO related file operations like copy,
-- delete, move and so on. It only operates on Path x which
-- guarantees us well-typed paths. Passing in Path Abs to any of
-- these functions generally increases safety. Passing Path Rel
-- may trigger looking up the current directory via getcwd in
-- some cases where it cannot be avoided.
--
-- Some functions are just path-safe wrappers around unix functions,
-- others have stricter exception handling and some implement
-- functionality that doesn't have a unix counterpart (like
-- copyDirRecursive).
--
-- Some of these operations are due to their nature not atomic,
-- which means they may do multiple syscalls which form one context. Some
-- of them also have to examine the filetypes explicitly before the
-- syscalls, so a reasonable decision can be made. That means the result
-- is undefined if another process changes that context while the
-- non-atomic operation is still happening. However, where possible, as
-- few syscalls as possible are used and the underlying exception
-- handling is kept.
--
-- Note: BlockDevice, CharacterDevice, NamedPipe and
-- Socket are ignored by some of the more high-level functions
-- (like easyCopy). For other functions (like copyFile),
-- the behavior on these file types is unreliable/unsafe. Check the
-- documentation of those functions for details.
module HPath.IO
data FileType
Directory :: FileType
RegularFile :: FileType
SymbolicLink :: FileType
BlockDevice :: FileType
CharacterDevice :: FileType
NamedPipe :: FileType
Socket :: FileType
-- | The error mode for recursive operations.
--
-- On FailEarly the whole operation fails immediately if any of
-- the recursive sub-operations fail, which is sort of the default for IO
-- operations.
--
-- On CollectFailures skips errors in the recursion and keeps on
-- recursing. However all errors are collected in the
-- RecursiveFailure error type, which is raised finally if there
-- was any error. Also note that RecursiveFailure does not give
-- any guarantees on the ordering of the collected exceptions.
data RecursiveErrorMode
FailEarly :: RecursiveErrorMode
CollectFailures :: RecursiveErrorMode
-- | The mode for copy and file moves. Overwrite mode is usually not very
-- well defined, but is a convenience shortcut.
data CopyMode
-- | fail if any target exists
Strict :: CopyMode
-- | overwrite targets
Overwrite :: CopyMode
-- | Copies the contents of a directory recursively to the given
-- destination, while preserving permissions. Does not follow symbolic
-- links. This behaves more or less like the following, without
-- descending into the destination if it already exists:
--
--
-- cp -a /source/dir /destination/somedir
--
--
-- For directory contents, this will ignore any file type that is not
-- RegularFile, SymbolicLink or Directory.
--
-- For Overwrite copy mode this does not prune destination
-- directory contents, so the destination might contain more files than
-- the source after the operation has completed. Permissions of existing
-- directories are fixed.
--
-- Safety/reliability concerns:
--
--
-- - not atomic
-- - examines filetypes explicitly
-- - an explicit check throwDestinationInSource is carried out
-- for the top directory for basic sanity, because otherwise we might end
-- up with an infinite copy loop... however, this operation is not
-- carried out recursively (because it's slow)
--
--
-- Throws:
--
--
--
-- Throws in FailEarly RecursiveErrorMode only:
--
--
--
-- Throws in CollectFailures RecursiveErrorMode only:
--
--
--
-- Throws in Strict CopyMode only:
--
--
copyDirRecursive :: Path b1 -> Path b2 -> CopyMode -> RecursiveErrorMode -> IO ()
-- | Recreate a symlink.
--
-- In Overwrite copy mode only files and empty directories are
-- deleted.
--
-- Safety/reliability concerns:
--
--
-- - Overwrite mode is inherently non-atomic
--
--
-- Throws:
--
--
--
-- Throws in Strict mode only:
--
--
--
-- Throws in Overwrite mode only:
--
--
--
-- Note: calls symlink
recreateSymlink :: Path b1 -> Path b2 -> CopyMode -> IO ()
-- | Copies the given regular file to the given destination. Neither
-- follows symbolic links, nor accepts them. For "copying" symbolic
-- links, use recreateSymlink instead.
--
-- Note that this is still sort of a low-level function and doesn't
-- examine file types. For a more high-level version, use easyCopy
-- instead.
--
-- In Overwrite copy mode only overwrites actual files, not
-- directories.
--
-- Safety/reliability concerns:
--
--
-- - Overwrite mode is not atomic
-- - when used on CharacterDevice, reads the "contents" and
-- copies them to a regular file, which might take indefinitely
-- - when used on BlockDevice, may either read the "contents"
-- and copy them to a regular file (potentially hanging indefinitely) or
-- may create a regular empty destination file
-- - when used on NamedPipe, will hang indefinitely
--
--
-- Throws:
--
--
--
-- Throws in Strict mode only:
--
--
--
-- Note: calls sendfile and possibly read/write
-- as fallback
copyFile :: Path b1 -> Path b2 -> CopyMode -> IO ()
-- | Copies a regular file, directory or symbolic link. In case of a
-- symbolic link it is just recreated, even if it points to a directory.
-- Any other file type is ignored.
--
-- Safety/reliability concerns:
--
--
easyCopy :: Path b1 -> Path b2 -> CopyMode -> RecursiveErrorMode -> IO ()
-- | Deletes the given file. Raises eISDIR if run on a directory.
-- Does not follow symbolic links.
--
-- Throws:
--
--
deleteFile :: Path b -> IO ()
-- | Deletes the given directory, which must be empty, never symlinks.
--
-- Throws:
--
--
--
-- Notes: calls rmdir
deleteDir :: Path b -> IO ()
-- | Deletes the given directory recursively. Does not follow symbolic
-- links. Tries deleteDir first before attemtping a recursive
-- deletion.
--
-- On directory contents this behaves like easyDelete and thus
-- will ignore any file type that is not RegularFile,
-- SymbolicLink or Directory.
--
-- Safety/reliability concerns:
--
--
-- - not atomic
-- - examines filetypes explicitly
--
--
-- Throws:
--
--
deleteDirRecursive :: Path b -> IO ()
-- | Deletes a file, directory or symlink. In case of directory, performs
-- recursive deletion. In case of a symlink, the symlink file is deleted.
-- Any other file type is ignored.
--
-- Safety/reliability concerns:
--
--
easyDelete :: Path b -> IO ()
-- | Opens a file appropriately by invoking xdg-open. The file type is not
-- checked. This forks a process.
openFile :: Path b -> IO ProcessID
-- | Executes a program with the given arguments. This forks a process.
executeFile :: Path b -> [ByteString] -> IO ProcessID
-- | Create an empty regular file at the given directory with the given
-- filename.
--
-- Throws:
--
--
createRegularFile :: FileMode -> Path b -> IO ()
-- | Create an empty directory at the given directory with the given
-- filename.
--
-- Throws:
--
--
createDir :: FileMode -> Path b -> IO ()
-- | Create an empty directory at the given directory with the given
-- filename. All parent directories are created with the same filemode.
-- This basically behaves like:
--
--
-- mkdir -p /some/dir
--
--
-- Safety/reliability concerns:
--
--
--
-- Throws:
--
--
-- - PermissionDenied if any part of the path components do not
-- exist and cannot be written to
-- - AlreadyExists if destination already exists and is not a
-- directory
--
createDirRecursive :: FileMode -> Path b -> IO ()
-- | Create a symlink.
--
-- Throws:
--
--
--
-- Note: calls symlink
createSymlink :: Path b -> ByteString -> IO ()
-- | Rename a given file with the provided filename. Destination and source
-- must be on the same device, otherwise eXDEV will be raised.
--
-- Does not follow symbolic links, but renames the symbolic link file.
--
-- Safety/reliability concerns:
--
--
-- - has a separate set of exception handling, apart from the
-- syscall
--
--
-- Throws:
--
--
--
-- Note: calls rename (but does not allow to rename over existing
-- files)
renameFile :: Path b1 -> Path b2 -> IO ()
-- | Move a file. This also works across devices by copy-delete fallback.
-- And also works on directories.
--
-- Does not follow symbolic links, but renames the symbolic link file.
--
-- Safety/reliability concerns:
--
--
--
-- Throws:
--
--
--
-- Throws in Strict mode only:
--
--
--
-- Note: calls rename (but does not allow to rename over existing
-- files)
moveFile :: Path b1 -> Path b2 -> CopyMode -> IO ()
-- | Read the given file at once into memory as a strict ByteString.
-- Symbolic links are followed, no sanity checks on file size or file
-- type. File must exist.
--
-- Note: the size of the file is determined in advance, as to only have
-- one allocation.
--
-- Safety/reliability concerns:
--
--
-- - since amount of bytes to read is determined in advance, the file
-- might be read partially only if something else is appending to it
-- while reading
-- - the whole file is read into memory!
--
--
-- Throws:
--
--
readFile :: Path b -> IO ByteString
-- | Read the given file in chunks of size `8192` into memory until
-- fread returns 0. Returns a lazy ByteString, because it uses
-- Builders under the hood.
--
-- Safety/reliability concerns:
--
--
-- - the whole file is read into memory!
--
--
-- Throws:
--
--
readFileEOF :: Path b -> IO ByteString
-- | Write a given ByteString to a file, truncating the file beforehand.
-- The file must exist. Follows symlinks.
--
-- Throws:
--
--
writeFile :: Path b -> ByteString -> IO ()
-- | Append a given ByteString to a file. The file must exist. Follows
-- symlinks.
--
-- Throws:
--
--
appendFile :: Path b -> ByteString -> IO ()
-- | Default permissions for a new file.
newFilePerms :: FileMode
-- | Default permissions for a new directory.
newDirPerms :: FileMode
-- | Gets all filenames of the given directory. This excludes "." and "..".
-- This version does not follow symbolic links.
--
-- The contents are not sorted and there is no guarantee on the ordering.
--
-- Throws:
--
--
getDirsFiles :: Path b -> IO [Path b]
-- | Get the file type of the file located at the given path. Does not
-- follow symbolic links.
--
-- Throws:
--
--
getFileType :: Path b -> IO FileType
-- | Applies realpath on the given path.
--
-- Throws:
--
--
canonicalizePath :: Path b -> IO (Path Abs)
-- | Converts any path to an absolute path. This is done in the following
-- way:
--
--
-- - if the path is already an absolute one, just return it
-- - if it's a relative path, prepend the current directory to it
--
toAbs :: Path b -> IO (Path Abs)
instance GHC.Show.Show HPath.IO.FileType
instance GHC.Classes.Eq HPath.IO.FileType