git.iko.soy/text
on builder help sign in
text/Data/Text/Encoding/Error.hs
116 lines 4.0 kB history raw
1{-# LANGUAGE CPP, DeriveDataTypeable #-}
2-- |
3-- Module : Data.Text.Encoding.Error
4-- Copyright : (c) Bryan O'Sullivan 2009
5--
6-- License : BSD-style
7-- Maintainer : bos@serpentine.com, rtomharper@googlemail.com,
8-- duncan@haskell.org
9-- Stability : experimental
10-- Portability : GHC
11--
12-- Types and functions for dealing with encoding and decoding errors
13-- in Unicode text.
14--
15-- The standard functions for encoding and decoding text are strict,
16-- which is to say that they throw exceptions on invalid input. This
17-- is often unhelpful on real world input, so alternative functions
18-- exist that accept custom handlers for dealing with invalid inputs.
19-- These 'OnError' handlers are normal Haskell functions. You can use
20-- one of the presupplied functions in this module, or you can write a
21-- custom handler of your own.
23module Data.Text.Encoding.Error
24 (
25 -- * Error handling types
26 UnicodeException(..)
27 , OnError
28 , OnDecodeError
29 , OnEncodeError
30 -- * Useful error handling functions
31 , lenientDecode
32 , strictDecode
33 , strictEncode
34 , ignore
35 , replace
36 ) where
38#if __GLASGOW_HASKELL__ >= 610
39import Control.Exception (Exception, throw)
40#else
41import Control.Exception.Extensible (Exception, throw)
42#endif
43import Data.Typeable (Typeable)
44import Data.Word (Word8)
45import Numeric (showHex)
47-- | Function type for handling a coding error. It is supplied with
48-- two inputs:
49--
50-- * A 'String' that describes the error.
51--
52-- * The input value that caused the error. If the error arose
53-- because the end of input was reached or could not be identified
54-- precisely, this value will be 'Nothing'.
55--
56-- If the handler returns a value wrapped with 'Just', that value will
57-- be used in the output as the replacement for the invalid input. If
58-- it returns 'Nothing', no value will be used in the output.
59--
60-- Should the handler need to abort processing, it should use 'error'
61-- or 'throw' an exception (preferably a 'UnicodeException'). It may
62-- use the description provided to construct a more helpful error
63-- report.
64type OnError a b = String -> Maybe a -> Maybe b
66-- | A handler for a decoding error.
67type OnDecodeError = OnError Word8 Char
69-- | A handler for an encoding error.
70type OnEncodeError = OnError Char Word8
72-- | An exception type for representing Unicode encoding errors.
73data UnicodeException =
74 DecodeError String (Maybe Word8)
75 -- ^ Could not decode a byte sequence because it was invalid under
76 -- the given encoding, or ran out of input in mid-decode.
77 | EncodeError String (Maybe Char)
78 -- ^ Tried to encode a character that could not be represented
79 -- under the given encoding, or ran out of input in mid-encode.
80 deriving (Eq, Typeable)
82showUnicodeException :: UnicodeException -> String
83showUnicodeException (DecodeError desc (Just w))
84 = "Cannot decode byte '\\x" ++ showHex w ("': " ++ desc)
85showUnicodeException (DecodeError desc Nothing)
86 = "Cannot decode input: " ++ desc
87showUnicodeException (EncodeError desc (Just c))
88 = "Cannot encode character '\\x" ++ showHex (fromEnum c) ("': " ++ desc)
89showUnicodeException (EncodeError desc Nothing)
90 = "Cannot encode input: " ++ desc
92instance Show UnicodeException where
93 show = showUnicodeException
95instance Exception UnicodeException
97-- | Throw a 'UnicodeException' if decoding fails.
98strictDecode :: OnDecodeError
99strictDecode desc c = throw (DecodeError desc c)
101-- | Replace an invalid input byte with the Unicode replacement
102-- character U+FFFD.
103lenientDecode :: OnDecodeError
104lenientDecode _ _ = Just '\xfffd'
106-- | Throw a 'UnicodeException' if encoding fails.
107strictEncode :: OnEncodeError
108strictEncode desc c = throw (EncodeError desc c)
110-- | Ignore an invalid input, substituting nothing in the output.
111ignore :: OnError a b
112ignore _ _ = Nothing
114-- | Replace an invalid input with a valid output.
115replace :: b -> OnError a b
116replace c _ _ = Just c