Portability	portable
Maintainer	[email protected]

Filesystem

Contents

Files
- Binary files
- Text files
Directories

Description

Simple FilePath‐aware wrappers around standard System.IO computations. See the linked documentation for each computation for details on exceptions and operating system interaction.

Synopsis

Documentation

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.

Instances

Eq Handle
Show Handle
Typeable Handle

data IOMode

See System.IO.openFile

Constructors

ReadMode
WriteMode
AppendMode
ReadWriteMode

Instances

Enum IOMode
Eq IOMode
Ord IOMode
Read IOMode
Show IOMode
Ix IOMode

rename :: FilePath -> FilePath -> IO ()Source

Rename a filesystem object. Some operating systems have restrictions on what objects can be renamed; see linked documentation for details.

See: renameFile and renameDirectory

Files

isFile :: FilePath -> IO Bool Source

Check if a file exists at the given path.

See: doesFileExist

getModified :: FilePath -> IO UTCTime Source

Get when the object at a given path was last modified.

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.

Since: 0.2

copyFile Source

Arguments

:: FilePath	Old location
-> FilePath	New location
-> IO ()

Copy a file to a new entry in the filesystem. If a file already exists at the new location, it will be replaced.

See: copyFile

Since: 0.1.1

removeFile :: FilePath -> IO ()Source

Remove a file.

See: removeFile

Binary files

openFile :: FilePath -> IOMode -> IO Handle Source

Open a file in binary mode, and return an open Handle. The Handle should be hClosed when it is no longer needed.

withFile is easier to use, because it will handle the Handle’s lifetime automatically.

See: openBinaryFile

withFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO aSource

Open a file in binary mode, and pass its Handle to a provided computation. The Handle will be automatically closed when the computation returns.

See: withBinaryFile

readFile :: FilePath -> IO ByteString Source

Read in the entire contents of a binary file.

See: readFile

writeFile :: FilePath -> ByteString -> IO ()Source

Replace the entire contents of a binary file with the provided ByteString.

See: writeFile

appendFile :: FilePath -> ByteString -> IO ()Source

Append a ByteString to a file. If the file does not exist, it will be created.

See: appendFile

Text files

openTextFile :: FilePath -> IOMode -> IO Handle Source

Open a file in text mode, and return an open Handle. The Handle should be hClosed when it is no longer needed.

withTextFile is easier to use, because it will handle the Handle’s lifetime automatically.

See: openFile

withTextFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO aSource

Open a file in text mode, and pass its Handle to a provided computation. The Handle will be automatically closed when the computation returns.

See: withFile

readTextFile :: FilePath -> IO Text Source

Read in the entire contents of a text file.

See: readFile

writeTextFile :: FilePath -> Text -> IO ()Source

Replace the entire contents of a text file with the provided Text.

See: writeFile

appendTextFile :: FilePath -> Text -> IO ()Source

Append Text to a file. If the file does not exist, it will be created.

See: appendFile

Directories

isDirectory :: FilePath -> IO Bool Source

Check if a directory exists at the given path.

See: doesDirectoryExist

canonicalizePath :: FilePath -> IO FilePath Source

listDirectory :: FilePath -> IO [FilePath]Source

List contents of a directory, excluding "." and "..". Each returned FilePath includes the path of the directory.

See: getDirectoryContents

Creating

createDirectory Source

Arguments

:: Bool	Succeed if the directory already exists
-> FilePath
-> IO ()

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.

See: createDirectory.

createTree :: FilePath -> IO ()Source

Create a directory at a given path, including any parents which might be missing.

See: createDirectoryIfMissing

Removing

removeDirectory :: FilePath -> IO ()Source

Remove an empty directory.

See: removeDirectory

removeTree :: FilePath -> IO ()Source

Recursively remove a directory tree rooted at the given path.

See: removeDirectoryRecursive

Current working directory

getWorkingDirectory :: IO FilePath Source

Get the current working directory.

See: getCurrentDirectory

setWorkingDirectory :: FilePath -> IO ()Source

Set the current working directory.

See: setCurrentDirectory

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.

See: getHomeDirectory

getDesktopDirectory :: IO FilePath Source

Get the user’s home 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.

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.

See: getUserDocumentsDirectory

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.

See: getAppUserDataDirectory

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.

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.