File.Text

Textual file handling.

File path operations

withFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a

Unlifted version of withFile.

Since: unliftio-0.1.0.0

openFileBlocking :: FilePath -> IOMode -> IO Handle

Like openFile, but opens the file in ordinary blocking mode. This can be useful for opening a FIFO for writing: if we open in non-blocking mode then the open will fail if there are no readers, whereas a blocking open will block until a reader appear.

Since: base-4.4.0.0

Reading

readFile :: FilePath -> IO Text

The readFile function reads a file and returns the contents of the file as a string. The entire file is read strictly, as with getContents.

Writing

writeFile :: FilePath -> Text -> IO ()

Write a string to a file. The file is truncated to zero length before writing begins.

appendFile :: FilePath -> Text -> IO ()

Write a string the end of a file.

File handle operations

Reading

getChar :: IO Char

Read a character from the standard input device (same as hGetChar stdin).

getLine :: IO Text

Read a single line of user input from stdin.

getContents :: IO Text

Read all user input on stdin as a single string.

hGetChar :: Handle -> IO Char

Computation hGetChar hdl reads a character from the file or channel managed by hdl, blocking until a character is available.

This operation may fail with:

• isEOFError if the end of file has been reached.

hGetLine :: Handle -> IO Text

Read a single line from a handle.

hGetChunk :: Handle -> IO Text

Experimental. Read a single chunk of strict text from a Handle. The size of the chunk depends on the amount of input currently buffered.

This function blocks only if there is no data available, and EOF has not yet been reached. Once EOF is reached, this function returns an empty string instead of throwing an exception.

hGetContents :: Handle -> IO Text

Read the remaining contents of a Handle as a string. The Handle is closed once the contents have been read, or if an exception is thrown.

Internally, this function reads a chunk at a time from the lower-level buffering abstraction, and concatenates the chunks into a single string once the entire file has been read.

As a result, it requires approximately twice as much memory as its result to construct its result. For files more than a half of available RAM in size, this may result in memory exhaustion.

Writing

putStr :: Text -> IO ()

Write a string to stdout.

putStrLn :: Text -> IO ()

Write a string to stdout, followed by a newline.

print :: Show a => a -> IO ()

The print function outputs a value of any printable type to the standard output device. Printable types are those that are instances of class Show; print converts values to strings for output using the show operation and adds a newline.

For example, a program to print the first 20 integers and their powers of 2 could be written as:

main = print ([(n, 2^n) | n <- [0..19]])

hPutStr :: Handle -> Text -> IO ()

Write a string to a handle.

hPutStrLn :: Handle -> Text -> IO ()

Write a string to a handle, followed by a newline.

hPrint :: Show a => Handle -> a -> IO ()

Computation hPrint hdl t writes the string representation of t given by the shows function to the file or channel managed by hdl and appends a newline.

This operation may fail with:

• isFullError if the device is full; or
• isPermissionError if another system resource limit would be exceeded.

File encoding

data TextEncoding

A TextEncoding is a specification of a conversion scheme between sequences of bytes and sequences of Unicode characters.

For example, UTF-8 is an encoding of Unicode characters into a sequence of bytes. The TextEncoding for UTF-8 is utf8.

Instances

Show TextEncoding

Since: base-4.3.0.0

Defined in GHC.IO.Encoding.Types

Methods

showsPrec :: Int -> TextEncoding -> ShowS

show :: TextEncoding -> String

showList :: [TextEncoding] -> ShowS

hSetEncoding :: Handle -> TextEncoding -> IO ()

The action hSetEncoding hdl encoding changes the text encoding for the handle hdl to encoding. The default encoding when a Handle is created is localeEncoding, namely the default encoding for the current locale.

To create a Handle with no encoding at all, use openBinaryFile. To stop further encoding or decoding on an existing Handle, use hSetBinaryMode.

hSetEncoding may need to flush buffered data in order to change the encoding.

hGetEncoding :: Handle -> IO (Maybe TextEncoding)

Return the current TextEncoding for the specified Handle, or Nothing if the Handle is in binary mode.

Note that the TextEncoding remembers nothing about the state of the encoder/decoder in use on this Handle. For example, if the encoding in use is UTF-16, then using hGetEncoding and hSetEncoding to save and restore the encoding may result in an extra byte-order-mark being written to the file.

latin1 :: TextEncoding

The Latin1 (ISO8859-1) encoding. This encoding maps bytes directly to the first 256 Unicode code points, and is thus not a complete Unicode encoding. An attempt to write a character greater than '\255' to a Handle using the latin1 encoding will result in an error.

utf8 :: TextEncoding

The UTF-8 Unicode encoding

utf8_bom :: TextEncoding

The UTF-8 Unicode encoding, with a byte-order-mark (BOM; the byte sequence 0xEF 0xBB 0xBF). This encoding behaves like utf8, except that on input, the BOM sequence is ignored at the beginning of the stream, and on output, the BOM sequence is prepended.

The byte-order-mark is strictly unnecessary in UTF-8, but is sometimes used to identify the encoding of a file.

utf16 :: TextEncoding

The UTF-16 Unicode encoding (a byte-order-mark should be used to indicate endianness).

utf16le :: TextEncoding

The UTF-16 Unicode encoding (litte-endian)

utf16be :: TextEncoding

The UTF-16 Unicode encoding (big-endian)

utf32 :: TextEncoding

The UTF-32 Unicode encoding (a byte-order-mark should be used to indicate endianness).

utf32le :: TextEncoding

The UTF-32 Unicode encoding (litte-endian)

utf32be :: TextEncoding

The UTF-32 Unicode encoding (big-endian)