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


-- | Consistent filesystem interaction across GHC versions (deprecated)
--   
--   Please see:
--   <a>https://plus.google.com/+MichaelSnoyman/posts/Ft5hnPqpgEx</a>
@package system-fileio
@version 0.3.16.4


-- | Simple <a>FilePath</a>‐aware wrappers around standard <a>System.IO</a>
--   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
data Handle
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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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
--   <a>removeDirectory</a> or <a>removeTree</a>.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> documentation for
--   information on why the failure occured.
removeFile :: FilePath -> IO ()

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

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

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

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

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

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

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

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

-- | List objects in a directory, excluding <tt>"."</tt> and <tt>".."</tt>.
--   Each returned <a>FilePath</a> includes the path of the directory.
--   Entries are not sorted.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> documentation for
--   information on why the failure occured.
createTree :: FilePath -> IO ()

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

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

-- | Set the current working directory.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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
--   <a>getDocumentsDirectory</a>.
--   
--   For data files the user does not explicitly create, such as automatic
--   saves, use <a>getAppDataDirectory</a>.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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
--   <a>getAppDataDirectory</a>.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>getAppDataDirectory</a>.
--   
--   This computation throws <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> 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 <a>IOError</a> on failure. See “Classifying
--   I/O errors” in the <a>System.IO.Error</a> documentation for
--   information on why the failure occured.
getAppConfigDirectory :: Text -> IO FilePath

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