Hledger.Utils.UTF8IOCompat

UTF-8 aware string IO functions that will work across multiple platforms and GHC versions. Includes code from Text.Pandoc.UTF8 ((C) 2010 John MacFarlane).

Example usage:

import Prelude hiding (readFile,writeFile,appendFile,getContents,putStr,putStrLn) import UTF8IOCompat (readFile,writeFile,appendFile,getContents,putStr,putStrLn) import UTF8IOCompat (SystemString,fromSystemString,toSystemString,error',userError')

2013410 update: we now trust that current GHC versions & platforms do the right thing, so this file is a no-op and on its way to being removed. Not carefully tested.

20191020 update: all packages have base>=4.9 which corresponds to GHC v8.0.1 and higher. Tear this file apart!

Documentation

readFile :: FilePath -> IO String

The readFile function reads a file and returns the contents of the file as a string. The file is read lazily, on demand, as with getContents.

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

The computation writeFile file str function writes the string str, to the file file.

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

The computation appendFile file str function appends the string str, to the file file.

Note that writeFile and appendFile write a literal string to a file. To write a value of any printable type, as with print, use the show function to convert the value to a string first.

main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])

getContents :: IO String

The getContents operation returns all user input as a single string, which is read lazily as it is needed (same as hGetContents stdin).

hGetContents :: Handle -> IO String

Computation hGetContents hdl returns the list of characters corresponding to the unread portion of the channel or file managed by hdl, which is put into an intermediate state, semi-closed. In this state, hdl is effectively closed, but items are read from hdl on demand and accumulated in a special list returned by hGetContents hdl.

Any operation that fails because a handle is closed, also fails if a handle is semi-closed. The only exception is hClose. A semi-closed handle becomes closed:

• if hClose is applied to it;
• if an I/O error occurs when reading an item from the handle;
• or once the entire contents of the handle has been read.

Once a semi-closed handle becomes closed, the contents of the associated list becomes fixed. The contents of this final list is only partially specified: it will contain at least all the items of the stream that were evaluated prior to the handle becoming closed.

Any I/O errors encountered while a handle is semi-closed are simply discarded.

This operation may fail with:

• isEOFError if the end of file has been reached.

putStr :: String -> IO ()

Write a string to the standard output device (same as hPutStr stdout).

putStrLn :: String -> IO ()

The same as putStr, but adds a newline character.

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

Computation hPutStr hdl s writes the string s to the file or channel managed by hdl.

This operation may fail with:

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

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

The same as hPutStr, but adds a newline character.

error' :: String -> a

A SystemString-aware version of error.

userError' :: String -> IOError

A SystemString-aware version of userError.

usageError :: String -> a

A SystemString-aware version of error that adds a usage hint.