-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Read and write UTF-8 text files
--   
--   This is a trivial integration of the <tt>path</tt> and <tt>text</tt>
--   packages, providing convenient functions to read and write UTF-8 text
--   files.
@package path-text-utf8
@version 0.0.0.2


-- | Read and write UTF-8 text files.
module Path.Text.UTF8

-- | Read the contents of a UTF-8 encoded text file.
--   
--   May throw <a>IOError</a> or <a>UnicodeException</a>. To handle these
--   errors in <a>Either</a> instead, use <a>tryReadFile</a>.
readFile :: Path base File -> IO Text

-- | Read the contents of a UTF-8 encoded text file.
--   
--   Any <a>IOError</a> or <a>UnicodeException</a> that occurs is caught
--   and returned as a <a>ReadError</a> on the <a>Left</a> side of the
--   <a>Either</a>. To throw these exceptions instead, use <a>readFile</a>.
tryReadFile :: Path base File -> IO (Either ReadError Text)
data ReadError
ReadErrorIO :: IOError -> ReadError
ReadErrorDecode :: UnicodeException -> ReadError

-- | Write text to a file in a UTF-8 encoding.
--   
--   May throw <a>IOError</a>. To handle this error in <a>Either</a>
--   instead, use <a>tryWriteFile</a>.
writeFile :: Path base File -> Text -> IO ()

-- | Write text to a file in a UTF-8 encoding.
--   
--   Any <a>IOError</a> that occurs is caught and returned on the
--   <a>Left</a> side of the <a>Either</a>. To throw the exception instead,
--   use <a>writeFile</a>.
tryWriteFile :: Path base File -> Text -> IO (Either WriteError ())
type WriteError = IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | An exception type for representing Unicode encoding errors.
data UnicodeException :: *

-- | Could not decode a byte sequence because it was invalid under the
--   given encoding, or ran out of input in mid-decode.
DecodeError :: String -> Maybe Word8 -> UnicodeException