hledger-lib-1.3: Core data types, parsers and functionality for the hledger accounting tools

Safe Haskell | Safe
Language | Haskell2010

Hledger.Utils.UTF8IOCompat

Description

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.

Synopsis

- readFile :: FilePath -> IO String
- writeFile :: FilePath -> String -> IO ()
- appendFile :: FilePath -> String -> IO ()
- getContents :: IO String
- hGetContents :: Handle -> IO String
- putStr :: String -> IO ()
- putStrLn :: String -> IO ()
- hPutStr :: Handle -> String -> IO ()
- hPutStrLn :: Handle -> String -> IO ()
- type SystemString = String
- fromSystemString :: SystemString -> String
- toSystemString :: String -> SystemString
- error' :: String -> a
- userError' :: String -> IOError
- usageError :: String -> a

# 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.

type SystemString = String #

A string received from or being passed to the operating system, such as a file path, command-line argument, or environment variable name or value. With GHC versions before 7.2 on some platforms (posix) these are typically encoded. When converting, we assume the encoding is UTF-8 (cf http://www.dwheeler.com/essays/fixing-unix-linux-filenames.html#UTF8).

fromSystemString :: SystemString -> String #

Convert a system string to an ordinary string, decoding from UTF-8 if it appears to be UTF8-encoded and GHC version is less than 7.2.

toSystemString :: String -> SystemString #

Convert a unicode string to a system string, encoding with UTF-8 if we are on a posix platform with GHC < 7.2.

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.