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

Exports from System.IO
Files
- Binary files
- Text files
Directories
Other

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.

Synopsis

data Handle
data IOMode
- = ReadMode
- | WriteMode
- | AppendMode
- | ReadWriteMode
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 #

Instances

Instances details

Show Handle
Instance details Defined in GHC.IO.Handle.Types Methods showsPrec :: Int -> Handle -> ShowS show :: Handle -> String showList :: [Handle] -> ShowS
Eq Handle
Instance details Defined in GHC.IO.Handle.Types Methods (==) :: Handle -> Handle -> Bool (/=) :: Handle -> Handle -> Bool

data IOMode #

Constructors

ReadMode
WriteMode
AppendMode
ReadWriteMode

Instances

Instances details

Enum IOMode
Instance details Defined in GHC.IO.IOMode Methods succ :: IOMode -> IOMode pred :: IOMode -> IOMode toEnum :: Int -> IOMode fromEnum :: IOMode -> Int enumFrom :: IOMode -> [IOMode] enumFromThen :: IOMode -> IOMode -> [IOMode] enumFromTo :: IOMode -> IOMode -> [IOMode] enumFromThenTo :: IOMode -> IOMode -> IOMode -> [IOMode]
Ix IOMode
Instance details Defined in GHC.IO.IOMode Methods range :: (IOMode, IOMode) -> [IOMode] index :: (IOMode, IOMode) -> IOMode -> Int unsafeIndex :: (IOMode, IOMode) -> IOMode -> Int inRange :: (IOMode, IOMode) -> IOMode -> Bool rangeSize :: (IOMode, IOMode) -> Int unsafeRangeSize :: (IOMode, IOMode) -> Int
Read IOMode
Instance details Defined in GHC.IO.IOMode Methods readsPrec :: Int -> ReadS IOMode readList :: ReadS [IOMode] readPrec :: ReadPrec IOMode readListPrec :: ReadPrec [IOMode]
Show IOMode
Instance details Defined in GHC.IO.IOMode Methods showsPrec :: Int -> IOMode -> ShowS show :: IOMode -> String showList :: [IOMode] -> ShowS
Eq IOMode
Instance details Defined in GHC.IO.IOMode Methods (==) :: IOMode -> IOMode -> Bool (/=) :: IOMode -> IOMode -> Bool
Ord IOMode
Instance details Defined in GHC.IO.IOMode Methods compare :: IOMode -> IOMode -> Ordering (<) :: IOMode -> IOMode -> Bool (<=) :: IOMode -> IOMode -> Bool (>) :: IOMode -> IOMode -> Bool (>=) :: IOMode -> IOMode -> Bool max :: IOMode -> IOMode -> IOMode min :: IOMode -> IOMode -> IOMode

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

copyFile Source #

Arguments

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

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

copyFileContent Source #

Arguments

:: FilePath	Old location
-> FilePath	New location
-> 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

copyPermissions Source #

Arguments

:: FilePath	Old location
-> FilePath	New location
-> 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

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

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.

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.

Other

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

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.