| Copyright | 2011-2012 John Millikin <jmillikin@gmail.com> |
|---|---|
| License | MIT |
| Maintainer | John Millikin <jmillikin@gmail.com> |
| Portability | portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell98 |
Filesystem
Contents
Description
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.
- data Handle :: *
- data IOMode :: *
- isFile :: FilePath -> IO Bool
- getModified :: FilePath -> IO UTCTime
- getSize :: FilePath -> IO Integer
- copyFile :: FilePath -> FilePath -> IO ()
- copyFileContent :: FilePath -> FilePath -> IO ()
- copyPermissions :: FilePath -> FilePath -> IO ()
- removeFile :: FilePath -> IO ()
- openFile :: FilePath -> IOMode -> IO Handle
- withFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a
- readFile :: FilePath -> IO ByteString
- writeFile :: FilePath -> ByteString -> IO ()
- appendFile :: FilePath -> ByteString -> IO ()
- openTextFile :: FilePath -> IOMode -> IO Handle
- withTextFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a
- readTextFile :: FilePath -> IO Text
- writeTextFile :: FilePath -> Text -> IO ()
- appendTextFile :: FilePath -> Text -> IO ()
- isDirectory :: FilePath -> IO Bool
- canonicalizePath :: FilePath -> IO FilePath
- listDirectory :: FilePath -> IO [FilePath]
- createDirectory :: Bool -> FilePath -> IO ()
- createTree :: FilePath -> IO ()
- removeDirectory :: FilePath -> IO ()
- removeTree :: FilePath -> IO ()
- getWorkingDirectory :: IO FilePath
- setWorkingDirectory :: FilePath -> IO ()
- getHomeDirectory :: IO FilePath
- getDesktopDirectory :: IO FilePath
- getDocumentsDirectory :: IO FilePath
- getAppDataDirectory :: Text -> IO FilePath
- getAppCacheDirectory :: Text -> IO FilePath
- getAppConfigDirectory :: Text -> IO FilePath
- rename :: FilePath -> FilePath -> IO ()
Exports from System.IO
data Handle :: *
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.
Files
isFile :: FilePath -> IO Bool Source
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.
getModified :: FilePath -> IO UTCTime Source
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
getSize :: FilePath -> IO Integer Source
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
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
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
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
removeFile :: FilePath -> IO () Source
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.
Binary files
openFile :: FilePath -> IOMode -> IO Handle Source
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.
withFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a Source
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.
readFile :: FilePath -> IO ByteString Source
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.
writeFile :: FilePath -> ByteString -> IO () Source
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.
appendFile :: FilePath -> ByteString -> IO () Source
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.
Text files
openTextFile :: FilePath -> IOMode -> IO Handle Source
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.
withTextFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a Source
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.
readTextFile :: FilePath -> IO Text Source
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.
writeTextFile :: FilePath -> Text -> IO () Source
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.
appendTextFile :: FilePath -> Text -> IO () Source
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.
Directories
isDirectory :: FilePath -> IO Bool Source
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.
canonicalizePath :: FilePath -> IO FilePath Source
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
listDirectory :: FilePath -> IO [FilePath] Source
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.
Creating directories
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.
createTree :: FilePath -> IO () Source
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.
Removing directories
removeDirectory :: FilePath -> IO () Source
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.
removeTree :: FilePath -> IO () Source
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.
Current working directory
getWorkingDirectory :: IO FilePath Source
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.
setWorkingDirectory :: FilePath -> IO () Source
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.
Commonly used paths
getHomeDirectory :: IO FilePath Source
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.
getDesktopDirectory :: IO FilePath Source
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.
getDocumentsDirectory :: IO FilePath Source
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.
getAppDataDirectory :: Text -> IO FilePath Source
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.
getAppCacheDirectory :: Text -> IO FilePath Source
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.
getAppConfigDirectory :: Text -> IO FilePath Source
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.