Version bump 0.3.2
[packages/utf8-string.git] / System / IO / UTF8.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : System.IO.UTF8
4 -- Copyright : (c) Eric Mertens 2007
5 -- License : BSD3-style (see LICENSE)
6 --
7 -- Maintainer: emertens@galois.com
8 -- Stability : experimental
9 -- Portability : portable
10 --
11 -- String IO preserving UTF8 encoding.
12 --
13
14 module System.IO.UTF8 (
15 print
16 , putStr
17 , putStrLn
18 , getLine
19 , readLn
20 , openBinaryFile
21 , withBinaryFile
22 , readFile
23 , writeFile
24 , appendFile
25 , getContents
26 , hGetLine
27 , hGetContents
28 , hPutStr
29 , hPutStrLn
30 ) where
31
32 import Control.Monad (liftM)
33 import Data.Word (Word8)
34 import Prelude (String, (=<<), (.), map, Enum(toEnum, fromEnum), Read,
35 Show(..))
36 import System.IO (Handle, IO, FilePath, IOMode(AppendMode, ReadMode, WriteMode))
37 import qualified System.IO as IO
38
39 import Codec.Binary.UTF8.String (encode, decode)
40
41
42 -- | Encode a string in UTF8 form.
43 encodeString :: String -> String
44 encodeString xs = bytesToString (encode xs)
45
46 -- | Decode a string from UTF8
47 decodeString :: String -> String
48 decodeString xs = decode (stringToBytes xs)
49
50 -- | Convert a list of bytes to a String
51 bytesToString :: [Word8] -> String
52 bytesToString xs = map (toEnum . fromEnum) xs
53
54 -- | String to list of bytes.
55 stringToBytes :: String -> [Word8]
56 stringToBytes xs = map (toEnum . fromEnum) xs
57
58 -- | The 'print' function outputs a value of any printable type to the
59 -- standard output device. This function differs from the
60 -- System.IO.print in that it preserves any UTF8 encoding of the shown value.
61 --
62 print :: Show a => a -> IO ()
63 print x = putStrLn (show x)
64
65 -- | Write a UTF8 string to the standard output device
66 putStr :: String -> IO ()
67 putStr x = IO.putStr (encodeString x)
68
69 -- | The same as 'putStr', but adds a newline character.
70 putStrLn :: String -> IO ()
71 putStrLn x = IO.putStrLn (encodeString x)
72
73 -- | Read a UTF8 line from the standard input device
74 getLine :: IO String
75 getLine = liftM decodeString IO.getLine
76
77 -- | The 'readLn' function combines 'getLine' and 'readIO', preserving UTF8
78 readLn :: Read a => IO a
79 readLn = IO.readIO =<< getLine
80
81 openBinaryFile :: FilePath -> IOMode -> IO Handle
82 openBinaryFile n m = IO.openBinaryFile (encodeString n) m
83
84 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO a) -> IO a
85 withBinaryFile n m f = IO.withBinaryFile (encodeString n) m f
86
87 -- | The 'readFile' function reads a file and
88 -- returns the contents of the file as a UTF8 string.
89 -- The file is read lazily, on demand, as with 'getContents'.
90 readFile :: FilePath -> IO String
91 readFile n = hGetContents =<< openBinaryFile n ReadMode
92
93 -- | The computation 'writeFile' @file str@ function writes the UTF8 string @str@,
94 -- to the file @file@.
95 writeFile :: FilePath -> String -> IO ()
96 writeFile n s = withBinaryFile n WriteMode (\ h -> hPutStr h s)
97
98 -- | The computation 'appendFile' @file str@ function appends the UTF8 string @str@,
99 -- to the file @file@.
100 appendFile :: FilePath -> String -> IO ()
101 appendFile n s = withBinaryFile n AppendMode (\ h -> hPutStr h s)
102
103 -- | Read a UTF8 line from a Handle
104 hGetLine :: Handle -> IO String
105 hGetLine h = liftM decodeString (IO.hGetLine h)
106
107 -- | Lazily read a UTF8 string from a Handle
108 hGetContents :: Handle -> IO String
109 hGetContents h = liftM decodeString (IO.hGetContents h)
110
111 -- | Write a UTF8 string to a Handle.
112 hPutStr :: Handle -> String -> IO ()
113 hPutStr h s = IO.hPutStr h (encodeString s)
114
115 -- | Write a UTF8 string to a Handle, appending a newline.
116 hPutStrLn :: Handle -> String -> IO ()
117 hPutStrLn h s = IO.hPutStrLn h (encodeString s)
118
119 -- | Lazily read stdin as a UTF8 string.
120 getContents :: IO String
121 getContents = liftM decodeString IO.getContents
122