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