-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Consistent filesystem interaction across GHC versions (deprecated)
--   
--   Consistent filesystem interaction across GHC versions (deprecated
--   package).
@package system-fileio
@version 0.3.16.7

-- | Simple FilePath‐aware wrappers around standard System.IO
--   computations. These wrappers are designed to work as similarly as
--   possible across various versions of GHC.
--   
--   In particular, they do not require POSIX file paths to be valid
--   strings, and can therefore open paths regardless of the current locale
--   encoding.
module Filesystem

-- | 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

-- | See openFile
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode

-- | Check if a file exists at the given path.
--   
--   Any non‐directory object, including devices and pipes, are considered
--   to be files. Symbolic links are resolved to their targets before
--   checking their type.
--   
--   This computation does not throw exceptions.
isFile :: FilePath -> IO Bool

-- | Get when the object at a given path was last modified.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.2
getModified :: FilePath -> IO UTCTime

-- | Get the size of an object at a given path. For special objects like
--   links or directories, the size is filesystem‐ and platform‐dependent.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.2
getSize :: FilePath -> IO Integer

-- | Copy the content and permissions of a file to a new entry in the
--   filesystem. If a file already exists at the new location, it will be
--   replaced. Copying a file is not atomic.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.1.1
copyFile :: FilePath -> FilePath -> IO ()

-- | Copy the content of a file to a new entry in the filesystem. If a file
--   already exists at the new location, it will be replaced. Copying a
--   file is not atomic.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.2.4 / 0.3.4
copyFileContent :: FilePath -> FilePath -> IO ()

-- | Copy the permissions from one path to another. Both paths must already
--   exist.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.2.4 / 0.3.4
copyPermissions :: FilePath -> FilePath -> IO ()

-- | Remove a file. This will fail if the file does not exist.
--   
--   This computation cannot remove directories. For that, use
--   removeDirectory or removeTree.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
removeFile :: FilePath -> IO ()

-- | Open a file in binary mode, and return an open Handle. The
--   Handle should be closed with hClose when it is no
--   longer needed.
--   
--   withFile is easier to use, because it will handle the
--   Handle’s lifetime automatically.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
openFile :: FilePath -> IOMode -> IO Handle

-- | Open a file in binary mode, and pass its Handle to a provided
--   computation. The Handle will be automatically closed when the
--   computation returns.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
withFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a

-- | Read in the entire content of a binary file.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
readFile :: FilePath -> IO ByteString

-- | Replace the entire content of a binary file with the provided
--   ByteString.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a ByteString to a file. If the file does not exist, it
--   will be created.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
appendFile :: FilePath -> ByteString -> IO ()

-- | Open a file in text mode, and return an open Handle. The
--   Handle should be closed with hClose when it is no
--   longer needed.
--   
--   withTextFile is easier to use, because it will handle the
--   Handle’s lifetime automatically.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
openTextFile :: FilePath -> IOMode -> IO Handle

-- | Open a file in text mode, and pass its Handle to a provided
--   computation. The Handle will be automatically closed when the
--   computation returns.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
withTextFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a

-- | Read in the entire content of a text file.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
readTextFile :: FilePath -> IO Text

-- | Replace the entire content of a text file with the provided
--   Text.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
writeTextFile :: FilePath -> Text -> IO ()

-- | Append Text to a file. If the file does not exist, it will be
--   created.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
appendTextFile :: FilePath -> Text -> IO ()

-- | Check if a directory exists at the given path.
--   
--   Symbolic links are resolved to their targets before checking their
--   type.
--   
--   This computation does not throw exceptions.
isDirectory :: FilePath -> IO Bool

-- | Resolve symlinks and ".." path elements to return a canonical path. It
--   is intended that two paths referring to the same object will always
--   resolve to the same canonical path.
--   
--   Note that on many operating systems, it is impossible to guarantee
--   that two paths to the same file will resolve to the same canonical
--   path.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
--   
--   Since: 0.1.1
canonicalizePath :: FilePath -> IO FilePath

-- | List objects in a directory, excluding "." and "..".
--   Each returned FilePath includes the path of the directory.
--   Entries are not sorted.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
listDirectory :: FilePath -> IO [FilePath]

-- | Create a directory at a given path. The user may choose whether it is
--   an error for a directory to already exist at that path.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
createDirectory :: Bool -> FilePath -> IO ()

-- | Create a directory at a given path, including any parents which might
--   be missing.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
createTree :: FilePath -> IO ()

-- | Remove an empty directory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
removeDirectory :: FilePath -> IO ()

-- | Recursively remove a directory tree rooted at the given path.
--   
--   This computation does not follow symlinks. If the tree contains
--   symlinks, the links themselves will be removed, but not the objects
--   they point to.
--   
--   If the root path is a symlink, then it will be treated as if it were a
--   regular directory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
removeTree :: FilePath -> IO ()

-- | Get the current working directory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getWorkingDirectory :: IO FilePath

-- | Set the current working directory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
setWorkingDirectory :: FilePath -> IO ()

-- | Get the user’s home directory. This is useful for building paths to
--   more specific directories.
--   
--   For directing the user to open or safe a document, use
--   getDocumentsDirectory.
--   
--   For data files the user does not explicitly create, such as automatic
--   saves, use getAppDataDirectory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getHomeDirectory :: IO FilePath

-- | Get the user’s desktop directory. This is a good starting point for
--   file dialogs and other user queries. For data files the user does not
--   explicitly create, such as automatic saves, use
--   getAppDataDirectory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getDesktopDirectory :: IO FilePath

-- | Get the user’s documents directory. This is a good place to save
--   user‐created files. For data files the user does not explicitly
--   create, such as automatic saves, use getAppDataDirectory.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getDocumentsDirectory :: IO FilePath

-- | Get the user’s application data directory, given an application label.
--   This directory is where applications should store data the user did
--   not explicitly create, such as databases and automatic saves.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getAppDataDirectory :: Text -> IO FilePath

-- | Get the user’s application cache directory, given an application
--   label. This directory is where applications should store caches, which
--   might be large and can be safely deleted.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getAppCacheDirectory :: Text -> IO FilePath

-- | Get the user’s application configuration directory, given an
--   application label. This directory is where applications should store
--   their configurations and settings.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
getAppConfigDirectory :: Text -> IO FilePath

-- | Rename a filesystem object.
--   
--   This computation throws IOError on failure. See “Classifying
--   I/O errors” in the System.IO.Error documentation for
--   information on why the failure occured.
rename :: FilePath -> FilePath -> IO ()
