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