libghc-system-fileio-doc 0.3.16.3-3build1 / usr / share / doc / libghc-system-fileio-doc / html / system-fileio.txt

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


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

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> 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 <a>Show</a> and <a>Eq</a> 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 <a>==</a> only to itself; no attempt is
--   made to compare the internal state of different handles for equality.
data Handle :: *

-- | See <a>openFile</a>
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 ()