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


-- | Fast JSON parsing and encoding
--   
--   A JSON parsing and encoding library optimized for ease of use and high
--   performance.
--   
--   To get started, see the documentation for the <tt>Data.Aeson</tt>
--   module below.
--   
--   (A note on naming: in Greek mythology, Aeson was the father of Jason.)
@package aeson
@version 2.1.2.1


-- | Strong type for JSON keys.
module Data.Aeson.Key
data Key
fromString :: String -> Key
toString :: Key -> String
toText :: Key -> Text
fromText :: Text -> Key

-- | <tt>'coercing r1 r2'</tt> will evaluate to <tt>r1</tt> if <a>Key</a>
--   is <tt>Coercible</tt> to <a>Text</a>, and to <tt>r2</tt> otherwise.
--   
--   Using <tt>coercing</tt> we can make more efficient implementations
--   when <a>Key</a> is backed up by <a>Text</a> without exposing
--   internals.
coercionToText :: Maybe (Coercion Key Text)

toShortText :: Key -> ShortText

fromShortText :: ShortText -> Key
instance Data.Data.Data Data.Aeson.Key.Key
instance GHC.Classes.Ord Data.Aeson.Key.Key
instance GHC.Classes.Eq Data.Aeson.Key.Key
instance GHC.Read.Read Data.Aeson.Key.Key
instance GHC.Show.Show Data.Aeson.Key.Key
instance Data.String.IsString Data.Aeson.Key.Key
instance Data.Hashable.Class.Hashable Data.Aeson.Key.Key
instance Control.DeepSeq.NFData Data.Aeson.Key.Key
instance GHC.Base.Semigroup Data.Aeson.Key.Key
instance GHC.Base.Monoid Data.Aeson.Key.Key
instance Language.Haskell.TH.Syntax.Lift Data.Aeson.Key.Key
instance Test.QuickCheck.Arbitrary.Arbitrary Data.Aeson.Key.Key
instance Test.QuickCheck.Arbitrary.CoArbitrary Data.Aeson.Key.Key
instance Test.QuickCheck.Function.Function Data.Aeson.Key.Key


-- | Token definitions.
module Data.Aeson.Decoding.Tokens

-- | A well-formed JSON token stream.
--   
--   <i>Note</i>: <a>Lit</a> exists to make <a>Tokens</a> have only 6
--   constructors. This may or may not have impact on performance.
data Tokens k e
TkLit :: !Lit -> k -> Tokens k e
TkText :: !Text -> k -> Tokens k e
TkNumber :: !Number -> k -> Tokens k e
TkArrayOpen :: TkArray k e -> Tokens k e
TkRecordOpen :: TkRecord k e -> Tokens k e
TkErr :: e -> Tokens k e

-- | Literals. <tt>null</tt>, <tt>true</tt>, <tt>false</tt>.
data Lit
LitNull :: Lit
LitTrue :: Lit
LitFalse :: Lit

-- | Numbers
--   
--   We preserve whether the number was integral, decimal or in scientific
--   form.
data Number

-- | e.g. <tt>123</tt>
NumInteger :: !Integer -> Number

-- | e.g. <tt>123.456</tt>
NumDecimal :: !Scientific -> Number

-- | e.g. <tt>123e456</tt>, <tt>123e-456</tt> or <tt>123.456E-967</tt>
NumScientific :: !Scientific -> Number

-- | Array tokens.
data TkArray k e
TkItem :: Tokens (TkArray k e) e -> TkArray k e
TkArrayEnd :: k -> TkArray k e
TkArrayErr :: e -> TkArray k e

-- | Record tokens.
data TkRecord k e
TkPair :: !Key -> Tokens (TkRecord k e) e -> TkRecord k e
TkRecordEnd :: k -> TkRecord k e
TkRecordErr :: e -> TkRecord k e
instance GHC.Show.Show Data.Aeson.Decoding.Tokens.Lit
instance GHC.Classes.Eq Data.Aeson.Decoding.Tokens.Lit
instance GHC.Show.Show Data.Aeson.Decoding.Tokens.Number
instance GHC.Classes.Eq Data.Aeson.Decoding.Tokens.Number
instance (GHC.Show.Show k, GHC.Show.Show e) => GHC.Show.Show (Data.Aeson.Decoding.Tokens.TkArray k e)
instance (GHC.Classes.Eq k, GHC.Classes.Eq e) => GHC.Classes.Eq (Data.Aeson.Decoding.Tokens.TkArray k e)
instance (GHC.Show.Show k, GHC.Show.Show e) => GHC.Show.Show (Data.Aeson.Decoding.Tokens.Tokens k e)
instance (GHC.Classes.Eq k, GHC.Classes.Eq e) => GHC.Classes.Eq (Data.Aeson.Decoding.Tokens.Tokens k e)
instance (GHC.Show.Show k, GHC.Show.Show e) => GHC.Show.Show (Data.Aeson.Decoding.Tokens.TkRecord k e)
instance (GHC.Classes.Eq k, GHC.Classes.Eq e) => GHC.Classes.Eq (Data.Aeson.Decoding.Tokens.TkRecord k e)
instance GHC.Base.Functor (Data.Aeson.Decoding.Tokens.Tokens k)
instance GHC.Base.Functor (Data.Aeson.Decoding.Tokens.TkArray k)
instance GHC.Base.Functor (Data.Aeson.Decoding.Tokens.TkRecord k)
instance Data.Foldable.Foldable (Data.Aeson.Decoding.Tokens.Tokens k)
instance Data.Foldable.Foldable (Data.Aeson.Decoding.Tokens.TkArray k)
instance Data.Foldable.Foldable (Data.Aeson.Decoding.Tokens.TkRecord k)
instance Data.Traversable.Traversable (Data.Aeson.Decoding.Tokens.Tokens k)
instance Data.Traversable.Traversable (Data.Aeson.Decoding.Tokens.TkArray k)
instance Data.Traversable.Traversable (Data.Aeson.Decoding.Tokens.TkRecord k)
instance Data.Bifunctor.Bifunctor Data.Aeson.Decoding.Tokens.Tokens
instance Data.Bifunctor.Bifunctor Data.Aeson.Decoding.Tokens.TkArray
instance Data.Bifunctor.Bifunctor Data.Aeson.Decoding.Tokens.TkRecord
instance Data.Bifoldable.Bifoldable Data.Aeson.Decoding.Tokens.Tokens
instance Data.Bifoldable.Bifoldable Data.Aeson.Decoding.Tokens.TkArray
instance Data.Bifoldable.Bifoldable Data.Aeson.Decoding.Tokens.TkRecord
instance Data.Bitraversable.Bitraversable Data.Aeson.Decoding.Tokens.Tokens
instance Data.Bitraversable.Bitraversable Data.Aeson.Decoding.Tokens.TkArray
instance Data.Bitraversable.Bitraversable Data.Aeson.Decoding.Tokens.TkRecord


-- | An abstract interface for maps from JSON keys to values.
module Data.Aeson.KeyMap

-- | A map from JSON key type <a>Key</a> to <tt>v</tt>.
data KeyMap v

-- | Is the map empty?
null :: KeyMap v -> Bool

-- | Return the value to which the specified key is mapped, or Nothing if
--   this map contains no mapping for the key.
lookup :: Key -> KeyMap v -> Maybe v

-- | Return the value to which the specified key is mapped, or Nothing if
--   this map contains no mapping for the key.
--   
--   This is a flipped version of <a>lookup</a>.
(!?) :: KeyMap v -> Key -> Maybe v

-- | Return the number of key-value mappings in this map.
size :: KeyMap v -> Int

-- | Is the key a member of the map?
member :: Key -> KeyMap a -> Bool

-- | Construct an empty map.
empty :: KeyMap v

-- | Construct a map with a single element.
singleton :: Key -> v -> KeyMap v

-- | Associate the specified value with the specified key in this map. If
--   this map previously contained a mapping for the key, the old value is
--   replaced.
insert :: Key -> v -> KeyMap v -> KeyMap v

-- | Insert with a function combining new and old values, taken in that
--   order.
insertWith :: (a -> a -> a) -> Key -> a -> KeyMap a -> KeyMap a

-- | Remove the mapping for the specified key from this map if present.
delete :: Key -> KeyMap v -> KeyMap v

-- | <a>alterF</a> can be used to insert, delete, or update a value in a
--   map.
alterF :: Functor f => (Maybe v -> f (Maybe v)) -> Key -> KeyMap v -> f (KeyMap v)

-- | Difference of two maps. Return elements of the first map not existing
--   in the second.
difference :: KeyMap v -> KeyMap v' -> KeyMap v
union :: KeyMap v -> KeyMap v -> KeyMap v

-- | The union with a combining function.
unionWith :: (v -> v -> v) -> KeyMap v -> KeyMap v -> KeyMap v

-- | The union with a combining function.
unionWithKey :: (Key -> v -> v -> v) -> KeyMap v -> KeyMap v -> KeyMap v

-- | The (left-biased) intersection of two maps (based on keys).
intersection :: KeyMap a -> KeyMap b -> KeyMap a

-- | The intersection with a combining function.
intersectionWith :: (a -> b -> c) -> KeyMap a -> KeyMap b -> KeyMap c

-- | The intersection with a combining function.
intersectionWithKey :: (Key -> a -> b -> c) -> KeyMap a -> KeyMap b -> KeyMap c

-- | Generalized union with combining function.
alignWith :: (These a b -> c) -> KeyMap a -> KeyMap b -> KeyMap c

-- | Generalized union with combining function.
alignWithKey :: (Key -> These a b -> c) -> KeyMap a -> KeyMap b -> KeyMap c

-- | Construct a map with the supplied mappings. If the list contains
--   duplicate mappings, the later mappings take precedence.
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("a", 'x'), ("a", 'y')]
--   fromList [("a",'y')]
--   </pre>
fromList :: [(Key, v)] -> KeyMap v

-- | Construct a map from a list of elements. Uses the provided function,
--   f, to merge duplicate entries with (f newVal oldVal).
fromListWith :: (v -> v -> v) -> [(Key, v)] -> KeyMap v

-- | Return a list of this map's keys and elements.
--   
--   The order is not stable. Use <a>toAscList</a> for stable ordering.
toList :: KeyMap v -> [(Key, v)]

-- | Return a list of this map's elements in ascending order based of the
--   textual key.
toAscList :: KeyMap v -> [(Key, v)]

-- | Return a list of this map' elements.
elems :: KeyMap v -> [v]

-- | Convert a <a>HashMap</a> to a <a>KeyMap</a>.
fromHashMap :: HashMap Key v -> KeyMap v

-- | Convert a <a>KeyMap</a> to a <a>HashMap</a>.
toHashMap :: KeyMap v -> HashMap Key v

-- | Convert a <tt><a>HashMap</a> <a>Text</a></tt>to a <a>KeyMap</a>.
fromHashMapText :: HashMap Text v -> KeyMap v

-- | Convert a <a>KeyMap</a> to a <tt><a>HashMap</a> <a>Text</a></tt>.
toHashMapText :: KeyMap v -> HashMap Text v
coercionToHashMap :: Maybe (Coercion (HashMap Key v) (KeyMap v))

-- | Convert a <a>Map</a> to a <a>KeyMap</a>.
fromMap :: Map Key v -> KeyMap v

-- | Convert a <a>KeyMap</a> to a <a>Map</a>.
toMap :: KeyMap v -> Map Key v

-- | Convert a <tt><a>Map</a> <a>Text</a></tt>to a <a>KeyMap</a>.
fromMapText :: Map Text v -> KeyMap v

-- | Convert a <a>KeyMap</a> to a <tt><a>Map</a> <a>Text</a></tt>.
toMapText :: KeyMap v -> Map Text v
coercionToMap :: Maybe (Coercion (Map Key v) (KeyMap v))

-- | Map a function over all values in the map.
map :: (a -> b) -> KeyMap a -> KeyMap b

-- | Map a function over all values in the map.
mapWithKey :: (Key -> a -> b) -> KeyMap a -> KeyMap b

-- | Transform the keys and values of a <a>KeyMap</a>.
mapKeyVal :: (Key -> Key) -> (v1 -> v2) -> KeyMap v1 -> KeyMap v2

-- | Perform an Applicative action for each key-value pair in a
--   <a>KeyMap</a> and produce a <a>KeyMap</a> of all the results.
traverse :: Applicative f => (v1 -> f v2) -> KeyMap v1 -> f (KeyMap v2)

-- | Perform an Applicative action for each key-value pair in a
--   <a>KeyMap</a> and produce a <a>KeyMap</a> of all the results.
traverseWithKey :: Applicative f => (Key -> v1 -> f v2) -> KeyMap v1 -> f (KeyMap v2)
foldr :: (a -> b -> b) -> b -> KeyMap a -> b
foldr' :: (a -> b -> b) -> b -> KeyMap a -> b
foldl :: (b -> a -> b) -> b -> KeyMap a -> b
foldl' :: (b -> a -> b) -> b -> KeyMap a -> b
foldMapWithKey :: Monoid m => (Key -> a -> m) -> KeyMap a -> m

-- | Reduce this map by applying a binary operator to all elements, using
--   the given starting value (typically the right-identity of the
--   operator).
foldrWithKey :: (Key -> v -> a -> a) -> a -> KeyMap v -> a

-- | Return a list of this map's keys.
keys :: KeyMap v -> [Key]

-- | Filter all keys/values that satisfy some predicate.
filter :: (v -> Bool) -> KeyMap v -> KeyMap v

-- | Filter all keys/values that satisfy some predicate.
filterWithKey :: (Key -> v -> Bool) -> KeyMap v -> KeyMap v

-- | Map values and collect the Just results.
mapMaybe :: (a -> Maybe b) -> KeyMap a -> KeyMap b

-- | Map values and collect the Just results.
mapMaybeWithKey :: (Key -> v -> Maybe u) -> KeyMap v -> KeyMap u
data Key
instance GHC.Base.Functor Data.Aeson.KeyMap.KeyMap
instance Data.Data.Data v => Data.Data.Data (Data.Aeson.KeyMap.KeyMap v)
instance GHC.Classes.Ord v => GHC.Classes.Ord (Data.Aeson.KeyMap.KeyMap v)
instance GHC.Classes.Eq v => GHC.Classes.Eq (Data.Aeson.KeyMap.KeyMap v)
instance GHC.Read.Read v => GHC.Read.Read (Data.Aeson.KeyMap.KeyMap v)
instance GHC.Show.Show v => GHC.Show.Show (Data.Aeson.KeyMap.KeyMap v)
instance Data.Foldable.Foldable Data.Aeson.KeyMap.KeyMap
instance Data.Traversable.Traversable Data.Aeson.KeyMap.KeyMap
instance GHC.Base.Semigroup (Data.Aeson.KeyMap.KeyMap v)
instance GHC.Base.Monoid (Data.Aeson.KeyMap.KeyMap v)
instance GHC.IsList.IsList (Data.Aeson.KeyMap.KeyMap v)
instance Language.Haskell.TH.Syntax.Lift v => Language.Haskell.TH.Syntax.Lift (Data.Aeson.KeyMap.KeyMap v)
instance Data.Hashable.Class.Hashable v => Data.Hashable.Class.Hashable (Data.Aeson.KeyMap.KeyMap v)
instance Control.DeepSeq.NFData v => Control.DeepSeq.NFData (Data.Aeson.KeyMap.KeyMap v)
instance WithIndex.FunctorWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance WithIndex.FoldableWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance WithIndex.TraversableWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance Data.Semialign.Internal.Zip Data.Aeson.KeyMap.KeyMap
instance Data.Semialign.Internal.ZipWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance Data.Semialign.Internal.Semialign Data.Aeson.KeyMap.KeyMap
instance Data.Semialign.Internal.SemialignWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance Data.Semialign.Internal.Align Data.Aeson.KeyMap.KeyMap
instance Witherable.Filterable Data.Aeson.KeyMap.KeyMap
instance Witherable.Witherable Data.Aeson.KeyMap.KeyMap
instance Witherable.FilterableWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance Witherable.WitherableWithIndex Data.Aeson.Key.Key Data.Aeson.KeyMap.KeyMap
instance Test.QuickCheck.Arbitrary.Arbitrary1 Data.Aeson.KeyMap.KeyMap
instance Test.QuickCheck.Arbitrary.Arbitrary v => Test.QuickCheck.Arbitrary.Arbitrary (Data.Aeson.KeyMap.KeyMap v)
instance Test.QuickCheck.Arbitrary.CoArbitrary v => Test.QuickCheck.Arbitrary.CoArbitrary (Data.Aeson.KeyMap.KeyMap v)
instance Test.QuickCheck.Function.Function v => Test.QuickCheck.Function.Function (Data.Aeson.KeyMap.KeyMap v)


-- | Parser from lazy <a>ByteString</a> to <a>Tokens</a>.
module Data.Aeson.Decoding.ByteString.Lazy

-- | Lex (and parse) lazy <a>ByteString</a> into <a>Tokens</a> stream.
lbsToTokens :: ByteString -> Tokens ByteString String


-- | Parser from strict <a>ByteString</a> to <a>Tokens</a>.
module Data.Aeson.Decoding.ByteString

-- | Lex (and parse) strict <a>ByteString</a> into <a>Tokens</a> stream.
bsToTokens :: ByteString -> Tokens ByteString String


-- | Efficiently and correctly parse a JSON string. The string must be
--   encoded as UTF-8.
module Data.Aeson.Parser.Internal

-- | Parse any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for <a>value</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith</a>.
json :: Parser Value

-- | Parse a top-level JSON value followed by optional whitespace and
--   end-of-input. See also: <a>json</a>.
jsonEOF :: Parser Value

-- | Parse any JSON value.
--   
--   This parser is parameterized by a function to construct an
--   <a>Object</a> from a raw list of key-value pairs, where duplicates are
--   preserved. The pairs appear in <b>reverse order</b> from the source.
--   
--   <h4><b>Examples</b></h4>
--   
--   <a>json</a> keeps only the first occurrence of each key, using
--   <a>fromList</a>.
--   
--   <pre>
--   <a>json</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromList</a>)
--   </pre>
--   
--   <a>jsonLast</a> keeps the last occurrence of each key, using
--   <tt><a>fromListWith</a> (<a>const</a> <a>id</a>)</tt>.
--   
--   <pre>
--   <a>jsonLast</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromListWith</a> (<a>const</a> <a>id</a>))
--   </pre>
--   
--   <a>jsonAccum</a> keeps wraps all values in arrays to keep duplicates,
--   using <a>fromListAccum</a>.
--   
--   <pre>
--   <a>jsonAccum</a> = <a>jsonWith</a> (<a>Right</a> . <a>fromListAccum</a>)
--   </pre>
--   
--   <a>jsonNoDup</a> fails if any object contains duplicate keys, using
--   <a>parseListNoDup</a>.
--   
--   <pre>
--   <a>jsonNoDup</a> = <a>jsonWith</a> <a>parseListNoDup</a>
--   </pre>
jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json</a> which keeps only the last occurrence of every
--   key.
jsonLast :: Parser Value

-- | Variant of <a>json</a> wrapping all object mappings in <a>Array</a> to
--   preserve key-value pairs with the same keys.
jsonAccum :: Parser Value

-- | Variant of <a>json</a> which fails if any object contains duplicate
--   keys.
jsonNoDup :: Parser Value

-- | Parse any JSON value. Synonym of <a>json</a>.
value :: Parser Value

-- | Parse a quoted JSON string.
jstring :: Parser Text

-- | Parse a string without a leading quote.
jstring_ :: Parser Text

-- | Parse a JSON number.
scientific :: Parser Scientific

-- | Parse any JSON value.
--   
--   This is a strict version of <a>json</a> which avoids building up
--   thunks during parsing; it performs all conversions immediately. Prefer
--   this version if most of the JSON data needs to be accessed.
--   
--   This function is an alias for <a>value'</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith'</a>.
json' :: Parser Value

-- | Parse a top-level JSON value followed by optional whitespace and
--   end-of-input. See also: <a>json'</a>.
jsonEOF' :: Parser Value

-- | Strict version of <a>jsonWith</a>.
jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json'</a> which keeps only the last occurrence of every
--   key.
jsonLast' :: Parser Value

-- | Variant of <a>json'</a> wrapping all object mappings in <a>Array</a>
--   to preserve key-value pairs with the same keys.
jsonAccum' :: Parser Value

-- | Variant of <a>json'</a> which fails if any object contains duplicate
--   keys.
jsonNoDup' :: Parser Value

-- | Strict version of <a>value</a>. Synonym of <a>json'</a>.
value' :: Parser Value
decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a

-- | <tt><a>fromListAccum</a> kvs</tt> is an object mapping keys to arrays
--   containing all associated values from the original list <tt>kvs</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; fromListAccum [("apple", Bool True), ("apple", Bool False), ("orange", Bool False)]
--   fromList [("apple",Array [Bool False,Bool True]),("orange",Array [Bool False])]
--   </pre>
fromListAccum :: [(Key, Value)] -> Object

-- | <tt><tt>fromListNoDup</tt> kvs</tt> fails if <tt>kvs</tt> contains
--   duplicate keys.
parseListNoDup :: [(Key, Value)] -> Either String Object
unescapeText :: ByteString -> Either UnicodeException Text


-- | Efficiently and correctly parse a JSON string. The string must be
--   encoded as UTF-8.
--   
--   It can be useful to think of parsing as occurring in two phases:
--   
--   <ul>
--   <li>Identification of the textual boundaries of a JSON value. This is
--   always strict, so that an invalid JSON document can be rejected as
--   soon as possible.</li>
--   <li>Conversion of a JSON value to a Haskell value. This may be either
--   immediate (strict) or deferred (lazy); see below for details.</li>
--   </ul>
--   
--   The question of whether to choose a lazy or strict parser is subtle,
--   but it can have significant performance implications, resulting in
--   changes in CPU use and memory footprint of 30% to 50%, or occasionally
--   more. Measure the performance of your application with each!
module Data.Aeson.Parser

-- | Parse any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for <a>value</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith</a>.
json :: Parser Value

-- | Parse any JSON value. Synonym of <a>json</a>.
value :: Parser Value

-- | Parse a quoted JSON string.
jstring :: Parser Text

-- | Parse a JSON number.
scientific :: Parser Scientific

-- | Parse any JSON value.
--   
--   This parser is parameterized by a function to construct an
--   <a>Object</a> from a raw list of key-value pairs, where duplicates are
--   preserved. The pairs appear in <b>reverse order</b> from the source.
--   
--   <h4><b>Examples</b></h4>
--   
--   <a>json</a> keeps only the first occurrence of each key, using
--   <a>fromList</a>.
--   
--   <pre>
--   <a>json</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromList</a>)
--   </pre>
--   
--   <a>jsonLast</a> keeps the last occurrence of each key, using
--   <tt><a>fromListWith</a> (<a>const</a> <a>id</a>)</tt>.
--   
--   <pre>
--   <a>jsonLast</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromListWith</a> (<a>const</a> <a>id</a>))
--   </pre>
--   
--   <a>jsonAccum</a> keeps wraps all values in arrays to keep duplicates,
--   using <a>fromListAccum</a>.
--   
--   <pre>
--   <a>jsonAccum</a> = <a>jsonWith</a> (<a>Right</a> . <a>fromListAccum</a>)
--   </pre>
--   
--   <a>jsonNoDup</a> fails if any object contains duplicate keys, using
--   <a>parseListNoDup</a>.
--   
--   <pre>
--   <a>jsonNoDup</a> = <a>jsonWith</a> <a>parseListNoDup</a>
--   </pre>
jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json</a> which keeps only the last occurrence of every
--   key.
jsonLast :: Parser Value

-- | Variant of <a>json</a> wrapping all object mappings in <a>Array</a> to
--   preserve key-value pairs with the same keys.
jsonAccum :: Parser Value

-- | Variant of <a>json</a> which fails if any object contains duplicate
--   keys.
jsonNoDup :: Parser Value

-- | Parse any JSON value.
--   
--   This is a strict version of <a>json</a> which avoids building up
--   thunks during parsing; it performs all conversions immediately. Prefer
--   this version if most of the JSON data needs to be accessed.
--   
--   This function is an alias for <a>value'</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith'</a>.
json' :: Parser Value

-- | Strict version of <a>value</a>. Synonym of <a>json'</a>.
value' :: Parser Value

-- | Strict version of <a>jsonWith</a>.
jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json'</a> which keeps only the last occurrence of every
--   key.
jsonLast' :: Parser Value

-- | Variant of <a>json'</a> wrapping all object mappings in <a>Array</a>
--   to preserve key-value pairs with the same keys.
jsonAccum' :: Parser Value

-- | Variant of <a>json'</a> which fails if any object contains duplicate
--   keys.
jsonNoDup' :: Parser Value
decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a


-- | Internal types and functions.
--   
--   <b>Note</b>: all declarations in this module are unstable, and prone
--   to being changed at any time.

-- | <i>Deprecated: All contents of this module are exported from
--   Data.Aeson.Types module. This module will be removed in the next major
--   aeson version.</i>
module Data.Aeson.Internal

-- | The internal result of running a <a>Parser</a>.
data IResult a
IError :: JSONPath -> String -> IResult a
ISuccess :: a -> IResult a

-- | Elements of a JSON path used to describe the location of an error.
data JSONPathElement

-- | JSON path element of a key into an object, "object.key".
Key :: Key -> JSONPathElement

-- | JSON path element of an index into an array, "array[index]".
Index :: {-# UNPACK #-} !Int -> JSONPathElement
type JSONPath = [JSONPathElement]

-- | Add JSON Path context to a parser
--   
--   When parsing a complex structure, it helps to annotate (sub)parsers
--   with context, so that if an error occurs, you can find its location.
--   
--   <pre>
--   withObject "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age"  &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a JSON Path
--   location of that error.
--   
--   Since 0.10
(<?>) :: Parser a -> JSONPathElement -> Parser a

-- | Annotate an error message with a <a>JSONPath</a> error location.
formatError :: JSONPath -> String -> String

-- | Convert a value from JSON, failing if the types do not match.
ifromJSON :: FromJSON a => Value -> IResult a

-- | Run a <a>Parser</a>.
iparse :: (a -> Parser b) -> a -> IResult b



-- | <i>Deprecated: This module will be removed in the next major aeson
--   version.</i>
module Data.Aeson.Internal.Time

-- | Like TimeOfDay, but using a fixed-width integer for seconds.
data TimeOfDay64
TOD :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int64 -> TimeOfDay64

-- | <i>Deprecated: Use MkFixed</i>
fromPico :: Pico -> Integer

-- | <i>Deprecated: Use MkFixed</i>
toPico :: Integer -> Pico
diffTimeOfDay64 :: DiffTime -> TimeOfDay64
toTimeOfDay64 :: TimeOfDay -> TimeOfDay64

module Data.Aeson.Encoding.Internal

-- | An encoding of a JSON value.
--   
--   <tt>tag</tt> represents which kind of JSON the Encoding is encoding
--   to, we reuse <a>Text</a> and <a>Series</a> as tags here.
newtype Encoding' tag
Encoding :: Builder -> Encoding' tag

-- | Acquire the underlying bytestring builder.
[fromEncoding] :: Encoding' tag -> Builder

-- | Often used synonym for <a>Encoding'</a>.
type Encoding = Encoding' Value
encodingToLazyByteString :: Encoding' a -> ByteString

-- | Make Encoding from Builder.
--   
--   Use with care! You have to make sure that the passed Builder is a
--   valid JSON Encoding!
unsafeToEncoding :: Builder -> Encoding' a
retagEncoding :: Encoding' a -> Encoding' b

-- | A series of values that, when encoded, should be separated by commas.
--   Since 0.11.0.0, the <tt>.=</tt> operator is overloaded to create
--   either <tt>(Text, Value)</tt> or <a>Series</a>. You can use Series
--   when encoding directly to a bytestring builder as in the following
--   example:
--   
--   <pre>
--   toEncoding (Person name age) = pairs ("name" .= name &lt;&gt; "age" .= age)
--   </pre>
data Series
Empty :: Series
Value :: Encoding' Series -> Series

-- | Encode a series of key/value pairs, separated by commas.
pairs :: Series -> Encoding
pair :: Key -> Encoding -> Series
pairStr :: String -> Encoding -> Series

-- | A variant of a <a>pair</a> where key is already encoded including the
--   quotes and colon.
--   
--   <pre>
--   <a>pair</a> "foo" v = <tt>unsafePair</tt> "\"foo\":" v
--   </pre>
unsafePairSBS :: ShortByteString -> Encoding -> Series
pair' :: Encoding' Key -> Encoding -> Series
nullEncoding :: Encoding' a -> Bool
emptyArray_ :: Encoding
emptyObject_ :: Encoding
wrapObject :: Encoding' a -> Encoding
wrapArray :: Encoding' a -> Encoding
null_ :: Encoding
bool :: Bool -> Encoding
key :: Key -> Encoding' a
text :: Text -> Encoding' a
lazyText :: Text -> Encoding' a

shortText :: ShortText -> Encoding' a
string :: String -> Encoding' a
list :: (a -> Encoding) -> [a] -> Encoding

-- | Encode as JSON object
dict :: (k -> Encoding' Key) -> (v -> Encoding) -> (forall a. (k -> v -> a -> a) -> a -> m -> a) -> m -> Encoding

-- | Encode as a tuple.
--   
--   @ toEncoding (X a b c) = tuple $ toEncoding a &gt;*&lt; toEncoding b
--   &gt;*&lt; toEncoding c
tuple :: Encoding' InArray -> Encoding

-- | See <a>tuple</a>.
(>*<) :: Encoding' a -> Encoding' b -> Encoding' InArray
infixr 6 >*<

-- | Type tag for tuples contents, see <a>tuple</a>.
data InArray
empty :: Encoding' a
(><) :: Encoding' a -> Encoding' a -> Encoding' a
infixr 6 ><
econcat :: [Encoding' a] -> Encoding' a
int8 :: Int8 -> Encoding
int16 :: Int16 -> Encoding
int32 :: Int32 -> Encoding
int64 :: Int64 -> Encoding
int :: Int -> Encoding
word8 :: Word8 -> Encoding
word16 :: Word16 -> Encoding
word32 :: Word32 -> Encoding
word64 :: Word64 -> Encoding
word :: Word -> Encoding
integer :: Integer -> Encoding
float :: Float -> Encoding

-- | <pre>
--   &gt;&gt;&gt; double 42
--   "42.0"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (0/0)
--   "null"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (1/0)
--   "\"+inf\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (-23/0)
--   "\"-inf\""
--   </pre>
double :: Double -> Encoding
scientific :: Scientific -> Encoding
int8Text :: Int8 -> Encoding' a
int16Text :: Int16 -> Encoding' a
int32Text :: Int32 -> Encoding' a
int64Text :: Int64 -> Encoding' a
intText :: Int -> Encoding' a
word8Text :: Word8 -> Encoding' a
word16Text :: Word16 -> Encoding' a
word32Text :: Word32 -> Encoding' a
word64Text :: Word64 -> Encoding' a
wordText :: Word -> Encoding' a
integerText :: Integer -> Encoding' a
floatText :: Float -> Encoding' a

-- | <pre>
--   &gt;&gt;&gt; doubleText 42
--   "\"42.0\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (0/0)
--   "\"NaN\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (1/0)
--   "\"+inf\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (-23/0)
--   "\"-inf\""
--   </pre>
doubleText :: Double -> Encoding' a
scientificText :: Scientific -> Encoding' a
day :: Day -> Encoding' a
month :: Month -> Encoding' a
quarter :: Quarter -> Encoding' a
localTime :: LocalTime -> Encoding' a
utcTime :: UTCTime -> Encoding' a
timeOfDay :: TimeOfDay -> Encoding' a
zonedTime :: ZonedTime -> Encoding' a
value :: Value -> Encoding
comma :: Encoding' a
colon :: Encoding' a
openBracket :: Encoding' a
closeBracket :: Encoding' a
openCurly :: Encoding' a
closeCurly :: Encoding' a
instance GHC.Base.Semigroup Data.Aeson.Encoding.Internal.Series
instance GHC.Base.Monoid Data.Aeson.Encoding.Internal.Series
instance GHC.Show.Show (Data.Aeson.Encoding.Internal.Encoding' a)
instance GHC.Classes.Eq (Data.Aeson.Encoding.Internal.Encoding' a)
instance GHC.Classes.Ord (Data.Aeson.Encoding.Internal.Encoding' a)


-- | Functions in this module return well-formed <a>Encoding'</a>.
--   Polymorphic variants, which return <tt><a>Encoding'</a> a</tt>, return
--   a textual JSON value, so it can be used as both <tt><a>Encoding'</a>
--   <tt>Text</tt></tt> and <tt><a>Encoding'</a> = <a>Encoding'</a>
--   <a>Value</a></tt>.
module Data.Aeson.Encoding

-- | Often used synonym for <a>Encoding'</a>.
type Encoding = Encoding' Value

-- | An encoding of a JSON value.
--   
--   <tt>tag</tt> represents which kind of JSON the Encoding is encoding
--   to, we reuse <a>Text</a> and <a>Series</a> as tags here.
data Encoding' tag
encodingToLazyByteString :: Encoding' a -> ByteString

-- | Acquire the underlying bytestring builder.
fromEncoding :: Encoding' tag -> Builder

-- | Make Encoding from Builder.
--   
--   Use with care! You have to make sure that the passed Builder is a
--   valid JSON Encoding!
unsafeToEncoding :: Builder -> Encoding' a

-- | A series of values that, when encoded, should be separated by commas.
--   Since 0.11.0.0, the <tt>.=</tt> operator is overloaded to create
--   either <tt>(Text, Value)</tt> or <a>Series</a>. You can use Series
--   when encoding directly to a bytestring builder as in the following
--   example:
--   
--   <pre>
--   toEncoding (Person name age) = pairs ("name" .= name &lt;&gt; "age" .= age)
--   </pre>
data Series

-- | Encode a series of key/value pairs, separated by commas.
pairs :: Series -> Encoding
pair :: Key -> Encoding -> Series
pairStr :: String -> Encoding -> Series
pair' :: Encoding' Key -> Encoding -> Series
nullEncoding :: Encoding' a -> Bool
emptyArray_ :: Encoding
emptyObject_ :: Encoding
text :: Text -> Encoding' a
lazyText :: Text -> Encoding' a

shortText :: ShortText -> Encoding' a
string :: String -> Encoding' a
list :: (a -> Encoding) -> [a] -> Encoding

-- | Encode as JSON object
dict :: (k -> Encoding' Key) -> (v -> Encoding) -> (forall a. (k -> v -> a -> a) -> a -> m -> a) -> m -> Encoding
null_ :: Encoding
bool :: Bool -> Encoding
int8 :: Int8 -> Encoding
int16 :: Int16 -> Encoding
int32 :: Int32 -> Encoding
int64 :: Int64 -> Encoding
int :: Int -> Encoding
word8 :: Word8 -> Encoding
word16 :: Word16 -> Encoding
word32 :: Word32 -> Encoding
word64 :: Word64 -> Encoding
word :: Word -> Encoding
integer :: Integer -> Encoding
float :: Float -> Encoding

-- | <pre>
--   &gt;&gt;&gt; double 42
--   "42.0"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (0/0)
--   "null"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (1/0)
--   "\"+inf\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; double (-23/0)
--   "\"-inf\""
--   </pre>
double :: Double -> Encoding
scientific :: Scientific -> Encoding
int8Text :: Int8 -> Encoding' a
int16Text :: Int16 -> Encoding' a
int32Text :: Int32 -> Encoding' a
int64Text :: Int64 -> Encoding' a
intText :: Int -> Encoding' a
word8Text :: Word8 -> Encoding' a
word16Text :: Word16 -> Encoding' a
word32Text :: Word32 -> Encoding' a
word64Text :: Word64 -> Encoding' a
wordText :: Word -> Encoding' a
integerText :: Integer -> Encoding' a
floatText :: Float -> Encoding' a

-- | <pre>
--   &gt;&gt;&gt; doubleText 42
--   "\"42.0\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (0/0)
--   "\"NaN\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (1/0)
--   "\"+inf\""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleText (-23/0)
--   "\"-inf\""
--   </pre>
doubleText :: Double -> Encoding' a
scientificText :: Scientific -> Encoding' a
day :: Day -> Encoding' a
month :: Month -> Encoding' a
quarter :: Quarter -> Encoding' a
localTime :: LocalTime -> Encoding' a
utcTime :: UTCTime -> Encoding' a
timeOfDay :: TimeOfDay -> Encoding' a
zonedTime :: ZonedTime -> Encoding' a
value :: Value -> Encoding


-- | Types for working with JSON data.
module Data.Aeson.Types

-- | A JSON value represented as a Haskell value.
data Value
Object :: !Object -> Value
Array :: !Array -> Value
String :: !Text -> Value
Number :: !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value
data Key

-- | Often used synonym for <a>Encoding'</a>.
type Encoding = Encoding' Value

-- | Make Encoding from Builder.
--   
--   Use with care! You have to make sure that the passed Builder is a
--   valid JSON Encoding!
unsafeToEncoding :: Builder -> Encoding' a

-- | Acquire the underlying bytestring builder.
fromEncoding :: Encoding' tag -> Builder

-- | A series of values that, when encoded, should be separated by commas.
--   Since 0.11.0.0, the <tt>.=</tt> operator is overloaded to create
--   either <tt>(Text, Value)</tt> or <a>Series</a>. You can use Series
--   when encoding directly to a bytestring builder as in the following
--   example:
--   
--   <pre>
--   toEncoding (Person name age) = pairs ("name" .= name &lt;&gt; "age" .= age)
--   </pre>
data Series

-- | A JSON "array" (sequence).
type Array = Vector Value

-- | The empty array.
emptyArray :: Value

-- | A key/value pair for an <a>Object</a>.
type Pair = (Key, Value)

-- | A JSON "object" (key/value map).
type Object = KeyMap Value

-- | The empty object.
emptyObject :: Value

-- | A newtype wrapper for <a>UTCTime</a> that uses the same non-standard
--   serialization format as Microsoft .NET, whose <a>System.DateTime</a>
--   type is by default serialized to JSON as in the following example:
--   
--   <pre>
--   /Date(1302547608878)/
--   </pre>
--   
--   The number represents milliseconds since the Unix epoch.
newtype DotNetTime
DotNetTime :: UTCTime -> DotNetTime

-- | Acquire the underlying value.
[fromDotNetTime] :: DotNetTime -> UTCTime

-- | Fail parsing due to a type mismatch, with a descriptive message.
--   
--   The following wrappers should generally be preferred:
--   <a>withObject</a>, <a>withArray</a>, <a>withText</a>, <a>withBool</a>.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   typeMismatch "Object" (String "oops")
--   -- Error: "expected Object, but encountered String"
--   </pre>
typeMismatch :: String -> Value -> Parser a

-- | Fail parsing due to a type mismatch, when the expected types are
--   implicit.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   unexpected (String "oops")
--   -- Error: "unexpected String"
--   </pre>
unexpected :: Value -> Parser a

-- | A JSON parser. N.B. This might not fit your usual understanding of
--   "parser". Instead you might like to think of <a>Parser</a> as a "parse
--   result", i.e. a parser to which the input has already been applied.
data Parser a

-- | The result of running a <a>Parser</a>.
data Result a
Error :: String -> Result a
Success :: a -> Result a

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   In many cases, you can get the compiler to generate parsing code for
--   you (see below). To begin, let's cover writing an instance by hand.
--   
--   There are various reasons a conversion could fail. For example, an
--   <a>Object</a> could be missing a required key, an <a>Array</a> could
--   be of the wrong size, or a value could be of an incompatible type.
--   
--   The basic ways to signal a failed conversion are as follows:
--   
--   <ul>
--   <li><a>fail</a> yields a custom error message: it is the recommended
--   way of reporting a failure;</li>
--   <li><a>empty</a> (or <a>mzero</a>) is uninformative: use it when the
--   error is meant to be caught by some <tt>(<a>&lt;|&gt;</a>)</tt>;</li>
--   <li><a>typeMismatch</a> can be used to report a failure when the
--   encountered value is not of the expected JSON type; <a>unexpected</a>
--   is an appropriate alternative when more than one type may be expected,
--   or to keep the expected type implicit.</li>
--   </ul>
--   
--   <a>prependFailure</a> (or <a>modifyFailure</a>) add more information
--   to a parser's error messages.
--   
--   An example type and instance using <a>typeMismatch</a> and
--   <a>prependFailure</a>:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> (<a>Object</a> v) = Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   
--       -- We do not expect a non-<a>Object</a> value here.
--       -- We could use <a>empty</a> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    =
--           <a>prependFailure</a> "parsing Coord failed, "
--               (<a>typeMismatch</a> "Object" invalid)
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withScientific</a>,
--   etc. are provided. Their use is to be preferred when possible, since
--   they are more terse. Using <a>withObject</a>, we can rewrite the above
--   instance (assuming the same language extension and data type) as:
--   
--   <pre>
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>withObject</a> "Coord" $ \v -&gt; Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   </pre>
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>parseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>FromJSON</a> instance for
--   your datatype without giving a definition for <a>parseJSON</a>.
--   
--   For example, the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>FromJSON</a> Coord
--   </pre>
--   
--   or using the <a>DerivingVia extension</a>
--   
--   <pre>
--   deriving via <a>Generically</a> Coord instance <a>FromJSON</a> Coord
--   </pre>
--   
--   The default implementation will be equivalent to <tt>parseJSON =
--   <a>genericParseJSON</a> <a>defaultOptions</a></tt>; if you need
--   different options, you can customize the generic decoding by defining:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>genericParseJSON</a> customOptions
--   </pre>
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
parseJSON :: (FromJSON a, Generic a, GFromJSON Zero (Rep a)) => Value -> Parser a
parseJSONList :: FromJSON a => Value -> Parser [a]

-- | Convert a value from JSON, failing if the types do not match.
fromJSON :: FromJSON a => Value -> Result a

-- | Run a <a>Parser</a>.
parse :: (a -> Parser b) -> a -> Result b

-- | Run a <a>Parser</a> with an <a>Either</a> result type. If the parse
--   fails, the <a>Left</a> payload will contain an error message.
parseEither :: (a -> Parser b) -> a -> Either String b

-- | Run a <a>Parser</a> with a <a>Maybe</a> result type.
parseMaybe :: (a -> Parser b) -> a -> Maybe b

-- | Raise a parsing failure with some custom message.
parseFail :: String -> Parser a

-- | If the inner <tt>Parser</tt> failed, modify the failure message using
--   the provided function. This allows you to create more descriptive
--   error messages. For example:
--   
--   <pre>
--   parseJSON (Object o) = modifyFailure
--       ("Parsing of the Foo value failed: " ++)
--       (Foo &lt;$&gt; o .: "someField")
--   </pre>
--   
--   Since 0.6.2.0
modifyFailure :: (String -> String) -> Parser a -> Parser a

-- | If the inner <a>Parser</a> failed, prepend the given string to the
--   failure message.
--   
--   <pre>
--   <a>prependFailure</a> s = <a>modifyFailure</a> (s <a>++</a>)
--   </pre>
prependFailure :: String -> Parser a -> Parser a

-- | Throw a parser error with an additional path.
parserThrowError :: JSONPath -> String -> Parser a

-- | A handler function to handle previous errors and return to normal
--   execution.
parserCatchError :: Parser a -> (JSONPath -> String -> Parser a) -> Parser a

-- | The internal result of running a <a>Parser</a>.
data IResult a
IError :: JSONPath -> String -> IResult a
ISuccess :: a -> IResult a

-- | Convert a value from JSON, failing if the types do not match.
ifromJSON :: FromJSON a => Value -> IResult a

-- | Run a <a>Parser</a>.
iparse :: (a -> Parser b) -> a -> IResult b

-- | Run a <a>Parser</a> with an <a>Either</a> result type. If the parse
--   fails, the <a>Left</a> payload will contain an error message and a
--   json path to failed element.
iparseEither :: (a -> Parser b) -> a -> Either (JSONPath, String) b

-- | A type that can be converted to JSON.
--   
--   Instances in general <i>must</i> specify <a>toJSON</a> and
--   <i>should</i> (but don't need to) specify <a>toEncoding</a>.
--   
--   An example type and instance:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>ToJSON</a> Coord where
--     <a>toJSON</a> (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   
--     <a>toEncoding</a> (Coord x y) = <tt>pairs</tt> ("x" <a>.=</a> x <a>&lt;&gt;</a> "y" <a>.=</a> y)
--   </pre>
--   
--   Instead of manually writing your <a>ToJSON</a> instance, there are two
--   options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>toJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>ToJSON</a> instance. If you
--   require nothing other than <a>defaultOptions</a>, it is sufficient to
--   write (and this is the only alternative where the default
--   <a>toJSON</a> implementation is sufficient):
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
--   
--   or more conveniently using the <a>DerivingVia extension</a>
--   
--   <pre>
--   deriving via <a>Generically</a> Coord instance <a>ToJSON</a> Coord
--   </pre>
--   
--   If on the other hand you wish to customize the generic decoding, you
--   have to implement both methods:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toJSON</a>     = <a>genericToJSON</a> customOptions
--       <a>toEncoding</a> = <a>genericToEncoding</a> customOptions
--   </pre>
--   
--   Previous versions of this library only had the <a>toJSON</a> method.
--   Adding <a>toEncoding</a> had two reasons:
--   
--   <ol>
--   <li><a>toEncoding</a> is more efficient for the common case that the
--   output of <a>toJSON</a> is directly serialized to a
--   <tt>ByteString</tt>. Further, expressing either method in terms of the
--   other would be non-optimal.</li>
--   <li>The choice of defaults allows a smooth transition for existing
--   users: Existing instances that do not define <a>toEncoding</a> still
--   compile and have the correct semantics. This is ensured by making the
--   default implementation of <a>toEncoding</a> use <a>toJSON</a>. This
--   produces correct results, but since it performs an intermediate
--   conversion to a <a>Value</a>, it will be less efficient than directly
--   emitting an <a>Encoding</a>. (this also means that specifying nothing
--   more than <tt>instance ToJSON Coord</tt> would be sufficient as a
--   generically decoding instance, but there probably exists no good
--   reason to not specify <a>toEncoding</a> in new instances.)</li>
--   </ol>
class ToJSON a

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: ToJSON a => a -> Value

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: (ToJSON a, Generic a, GToJSON' Value Zero (Rep a)) => a -> Value

-- | Encode a Haskell value as JSON.
--   
--   The default implementation of this method creates an intermediate
--   <a>Value</a> using <a>toJSON</a>. This provides source-level
--   compatibility for people upgrading from older versions of this
--   library, but obviously offers no performance advantage.
--   
--   To benefit from direct encoding, you <i>must</i> provide an
--   implementation for this method. The easiest way to do so is by having
--   your types implement <a>Generic</a> using the <tt>DeriveGeneric</tt>
--   extension, and then have GHC generate a method body as follows.
--   
--   <pre>
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
toEncoding :: ToJSON a => a -> Encoding
toJSONList :: ToJSON a => [a] -> Value
toEncodingList :: ToJSON a => [a] -> Encoding

-- | A key-value pair for encoding a JSON object.
class KeyValue kv
(.=) :: (KeyValue kv, ToJSON v) => Key -> v -> kv
infixr 8 .=

-- | Typeclass for types that can be used as the key of a map-like
--   container (like <tt>Map</tt> or <tt>HashMap</tt>). For example, since
--   <a>Text</a> has a <a>ToJSONKey</a> instance and <a>Char</a> has a
--   <a>ToJSON</a> instance, we can encode a value of type <tt>Map</tt>
--   <a>Text</a> <a>Char</a>:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [("foo" :: Text, 'a')]
--   {"foo":"a"}
--   </pre>
--   
--   Since <a>Int</a> also has a <a>ToJSONKey</a> instance, we can
--   similarly write:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(5 :: Int, 'a')]
--   {"5":"a"}
--   </pre>
--   
--   JSON documents only accept strings as object keys. For any type from
--   <tt>base</tt> that has a natural textual representation, it can be
--   expected that its <a>ToJSONKey</a> instance will choose that
--   representation.
--   
--   For data types that lack a natural textual representation, an
--   alternative is provided. The map-like container is represented as a
--   JSON array instead of a JSON object. Each value in the array is an
--   array with exactly two values. The first is the key and the second is
--   the value.
--   
--   For example, values of type '[Text]' cannot be encoded to a string, so
--   a <tt>Map</tt> with keys of type '[Text]' is encoded as follows:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(["foo","bar","baz" :: Text], 'a')]
--   [[["foo","bar","baz"],"a"]]
--   </pre>
--   
--   The default implementation of <a>ToJSONKey</a> chooses this method of
--   encoding a key, using the <a>ToJSON</a> instance of the type.
--   
--   To use your own data type as the key in a map, all that is needed is
--   to write a <a>ToJSONKey</a> (and possibly a <tt>FromJSONKey</tt>)
--   instance for it. If the type cannot be trivially converted to and from
--   <a>Text</a>, it is recommended that <a>ToJSONKeyValue</a> is used.
--   Since the default implementations of the typeclass methods can build
--   this from a <a>ToJSON</a> instance, there is nothing that needs to be
--   written:
--   
--   <pre>
--   data Foo = Foo { fooAge :: Int, fooName :: Text }
--     deriving (Eq,Ord,Generic)
--   instance ToJSON Foo
--   instance ToJSONKey Foo
--   </pre>
--   
--   That's it. We can now write:
--   
--   <pre>
--   &gt;&gt;&gt; let m = Map.fromList [(Foo 4 "bar",'a'),(Foo 6 "arg",'b')]
--   
--   &gt;&gt;&gt; LBC8.putStrLn $ encode m
--   [[{"fooName":"bar","fooAge":4},"a"],[{"fooName":"arg","fooAge":6},"b"]]
--   </pre>
--   
--   The next case to consider is if we have a type that is a newtype
--   wrapper around <a>Text</a>. The recommended approach is to use
--   generalized newtype deriving:
--   
--   <pre>
--   newtype RecordId = RecordId { getRecordId :: Text }
--     deriving (Eq,Ord,ToJSONKey)
--   </pre>
--   
--   Then we may write:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(RecordId "abc",'a')]
--   {"abc":"a"}
--   </pre>
--   
--   Simple sum types are a final case worth considering. Suppose we have:
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving (Show,Read,Eq,Ord)
--   </pre>
--   
--   It is possible to get the <a>ToJSONKey</a> instance for free as we did
--   with <tt>Foo</tt>. However, in this case, we have a natural way to go
--   to and from <a>Text</a> that does not require any escape sequences. So
--   <a>ToJSONKeyText</a> can be used instead of <a>ToJSONKeyValue</a> to
--   encode maps as objects instead of arrays of pairs. This instance may
--   be implemented using generics as follows:
--   
--   <pre>
--   instance <a>ToJSONKey</a> Color where
--     <a>toJSONKey</a> = <a>genericToJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
--   
--   <h3><b>Low-level implementations</b></h3>
--   
--   The <a>Show</a> instance can be used to help write <a>ToJSONKey</a>:
--   
--   <pre>
--   instance ToJSONKey Color where
--     toJSONKey = ToJSONKeyText f g
--       where f = Text.pack . show
--             g = text . Text.pack . show
--             -- text function is from Data.Aeson.Encoding
--   </pre>
--   
--   The situation of needing to turning function <tt>a -&gt; Text</tt>
--   into a <a>ToJSONKeyFunction</a> is common enough that a special
--   combinator is provided for it. The above instance can be rewritten as:
--   
--   <pre>
--   instance ToJSONKey Color where
--     toJSONKey = toJSONKeyText (Text.pack . show)
--   </pre>
--   
--   The performance of the above instance can be improved by not using
--   <a>Value</a> as an intermediate step when converting to <a>Text</a>.
--   One option for improving performance would be to use template haskell
--   machinery from the <tt>text-show</tt> package. However, even with the
--   approach, the <a>Encoding</a> (a wrapper around a bytestring builder)
--   is generated by encoding the <a>Text</a> to a <tt>ByteString</tt>, an
--   intermediate step that could be avoided. The fastest possible
--   implementation would be:
--   
--   <pre>
--   -- Assuming that OverloadedStrings is enabled
--   instance ToJSONKey Color where
--     toJSONKey = ToJSONKeyText f g
--       where f x = case x of {Red -&gt; "Red";Green -&gt;"Green";Blue -&gt; "Blue"}
--             g x = case x of {Red -&gt; text "Red";Green -&gt; text "Green";Blue -&gt; text "Blue"}
--             -- text function is from Data.Aeson.Encoding
--   </pre>
--   
--   This works because GHC can lift the encoded values out of the case
--   statements, which means that they are only evaluated once. This
--   approach should only be used when there is a serious need to maximize
--   performance.
class ToJSONKey a

-- | Strategy for rendering the key for a map-like container.
toJSONKey :: ToJSONKey a => ToJSONKeyFunction a

-- | Strategy for rendering the key for a map-like container.
toJSONKey :: (ToJSONKey a, ToJSON a) => ToJSONKeyFunction a

-- | This is similar in spirit to the <tt>showsList</tt> method of
--   <a>Show</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
toJSONKeyList :: ToJSONKey a => ToJSONKeyFunction [a]

-- | This is similar in spirit to the <tt>showsList</tt> method of
--   <a>Show</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
toJSONKeyList :: (ToJSONKey a, ToJSON a) => ToJSONKeyFunction [a]
data ToJSONKeyFunction a

-- | key is encoded to string, produces object
ToJSONKeyText :: !a -> Key -> !a -> Encoding' Key -> ToJSONKeyFunction a

-- | key is encoded to value, produces array
ToJSONKeyValue :: !a -> Value -> !a -> Encoding -> ToJSONKeyFunction a

-- | Helper for creating textual keys.
--   
--   <pre>
--   instance <a>ToJSONKey</a> MyKey where
--       <a>toJSONKey</a> = <a>toJSONKeyText</a> myKeyToText
--         where
--           myKeyToText = Text.pack . show -- or showt from text-show
--   </pre>
toJSONKeyText :: (a -> Text) -> ToJSONKeyFunction a

toJSONKeyKey :: (a -> Key) -> ToJSONKeyFunction a

-- | Contravariant map, as <a>ToJSONKeyFunction</a> is a contravariant
--   functor.
contramapToJSONKeyFunction :: (b -> a) -> ToJSONKeyFunction a -> ToJSONKeyFunction b

-- | Read the docs for <tt>ToJSONKey</tt> first. This class is a conversion
--   in the opposite direction. If you have a newtype wrapper around
--   <a>Text</a>, the recommended way to define instances is with
--   generalized newtype deriving:
--   
--   <pre>
--   newtype SomeId = SomeId { getSomeId :: Text }
--     deriving (Eq,Ord,Hashable,FromJSONKey)
--   </pre>
--   
--   If you have a sum of nullary constructors, you may use the generic
--   implementation:
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving Generic
--   
--   instance <a>FromJSONKey</a> Color where
--     <a>fromJSONKey</a> = <a>genericFromJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
class FromJSONKey a

-- | Strategy for parsing the key of a map-like container.
fromJSONKey :: FromJSONKey a => FromJSONKeyFunction a

-- | Strategy for parsing the key of a map-like container.
fromJSONKey :: (FromJSONKey a, FromJSON a) => FromJSONKeyFunction a

-- | This is similar in spirit to the <a>readList</a> method of
--   <a>Read</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
fromJSONKeyList :: FromJSONKey a => FromJSONKeyFunction [a]

-- | This is similar in spirit to the <a>readList</a> method of
--   <a>Read</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
fromJSONKeyList :: (FromJSONKey a, FromJSON a) => FromJSONKeyFunction [a]

-- | This type is related to <tt>ToJSONKeyFunction</tt>. If
--   <a>FromJSONKeyValue</a> is used in the <a>FromJSONKey</a> instance,
--   then <tt>ToJSONKeyValue</tt> should be used in the <tt>ToJSONKey</tt>
--   instance. The other three data constructors for this type all
--   correspond to <tt>ToJSONKeyText</tt>. Strictly speaking,
--   <a>FromJSONKeyTextParser</a> is more powerful than
--   <a>FromJSONKeyText</a>, which is in turn more powerful than
--   <a>FromJSONKeyCoerce</a>. For performance reasons, these exist as
--   three options instead of one.
data FromJSONKeyFunction a
[FromJSONKeyCoerce] :: Coercible Text a => FromJSONKeyFunction a
[FromJSONKeyText] :: !Text -> a -> FromJSONKeyFunction a
[FromJSONKeyTextParser] :: !Text -> Parser a -> FromJSONKeyFunction a
[FromJSONKeyValue] :: !Value -> Parser a -> FromJSONKeyFunction a

-- | Construct <a>FromJSONKeyFunction</a> for types coercible from
--   <a>Text</a>. This conversion is still unsafe, as <a>Hashable</a> and
--   <a>Eq</a> instances of <tt>a</tt> should be compatible with
--   <a>Text</a> i.e. hash values should be equal for wrapped values as
--   well. This property will always be maintained if the <a>Hashable</a>
--   and <a>Eq</a> instances are derived with generalized newtype deriving.
--   compatible with <a>Text</a> i.e. hash values be equal for wrapped
--   values as well.
--   
--   On pre GHC 7.8 this is unconstrained function.
fromJSONKeyCoerce :: Coercible Text a => FromJSONKeyFunction a

-- | Semantically the same as <tt>coerceFromJSONKeyFunction = fmap coerce =
--   coerce</tt>.
--   
--   See note on <a>fromJSONKeyCoerce</a>.
coerceFromJSONKeyFunction :: Coercible a b => FromJSONKeyFunction a -> FromJSONKeyFunction b

-- | Same as <a>fmap</a>. Provided for the consistency with
--   <tt>ToJSONKeyFunction</tt>.
mapFromJSONKeyFunction :: (a -> b) -> FromJSONKeyFunction a -> FromJSONKeyFunction b
class GetConName f => GToJSONKey f
genericToJSONKey :: (Generic a, GToJSONKey (Rep a)) => JSONKeyOptions -> ToJSONKeyFunction a
class (ConstructorNames f, SumFromString f) => GFromJSONKey f

-- | <a>fromJSONKey</a> for <a>Generic</a> types. These types must be sums
--   of nullary constructors, whose names will be used as keys for JSON
--   objects.
--   
--   See also <tt>genericToJSONKey</tt>.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving <a>Generic</a>
--   
--   instance <a>FromJSONKey</a> Color where
--     <a>fromJSONKey</a> = <a>genericFromJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
genericFromJSONKey :: forall a. (Generic a, GFromJSONKey (Rep a)) => JSONKeyOptions -> FromJSONKeyFunction a

-- | Lifting of the <a>FromJSON</a> class to unary type constructors.
--   
--   Instead of manually writing your <a>FromJSON1</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>liftParseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic1</a></tt>
--   clause to your datatype and declare a <a>FromJSON1</a> instance for
--   your datatype without giving a definition for <a>liftParseJSON</a>.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving <a>Generic1</a>
--   
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON1</a> (Pair a)
--   </pre>
--   
--   or
--   
--   <pre>
--   deriving via <a>Generically1</a> (Pair a) instance <a>FromJSON1</a> (Pair a)
--   </pre>
--   
--   If the default implementation doesn't give exactly the results you
--   want, you can customize the generic decoding with only a tiny amount
--   of effort, using <a>genericLiftParseJSON</a> with your preferred
--   <a>Options</a>:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON1</a> (Pair a) where
--       <a>liftParseJSON</a> = <a>genericLiftParseJSON</a> customOptions
--   </pre>
class FromJSON1 f
liftParseJSON :: FromJSON1 f => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)
liftParseJSON :: (FromJSON1 f, Generic1 f, GFromJSON One (Rep1 f)) => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)
liftParseJSONList :: FromJSON1 f => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser [f a]

-- | Lift the standard <a>parseJSON</a> function through the type
--   constructor.
parseJSON1 :: (FromJSON1 f, FromJSON a) => Value -> Parser (f a)

-- | Lifting of the <a>FromJSON</a> class to binary type constructors.
--   
--   Instead of manually writing your <a>FromJSON2</a> instance,
--   <a>Data.Aeson.TH</a> provides Template Haskell functions which will
--   derive an instance at compile time.
class FromJSON2 f
liftParseJSON2 :: FromJSON2 f => (Value -> Parser a) -> (Value -> Parser [a]) -> (Value -> Parser b) -> (Value -> Parser [b]) -> Value -> Parser (f a b)
liftParseJSONList2 :: FromJSON2 f => (Value -> Parser a) -> (Value -> Parser [a]) -> (Value -> Parser b) -> (Value -> Parser [b]) -> Value -> Parser [f a b]

-- | Lift the standard <a>parseJSON</a> function through the type
--   constructor.
parseJSON2 :: (FromJSON2 f, FromJSON a, FromJSON b) => Value -> Parser (f a b)

-- | Lifting of the <a>ToJSON</a> class to unary type constructors.
--   
--   Instead of manually writing your <a>ToJSON1</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>toJSON1</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic1</a></tt>
--   clause to your datatype and declare a <a>ToJSON1</a> instance for your
--   datatype without giving definitions for <a>liftToJSON</a> or
--   <a>liftToEncoding</a>.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving <a>Generic1</a>
--   
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON1</a> (Pair a)
--   </pre>
--   
--   If the default implementation doesn't give exactly the results you
--   want, you can customize the generic encoding with only a tiny amount
--   of effort, using <a>genericLiftToJSON</a> and
--   <a>genericLiftToEncoding</a> with your preferred <a>Options</a>:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON1</a> (Pair a) where
--       <a>liftToJSON</a>     = <a>genericLiftToJSON</a> customOptions
--       <a>liftToEncoding</a> = <a>genericLiftToEncoding</a> customOptions
--   </pre>
--   
--   See also <a>ToJSON</a>.
class ToJSON1 f
liftToJSON :: ToJSON1 f => (a -> Value) -> ([a] -> Value) -> f a -> Value
liftToJSON :: (ToJSON1 f, Generic1 f, GToJSON' Value One (Rep1 f)) => (a -> Value) -> ([a] -> Value) -> f a -> Value
liftToJSONList :: ToJSON1 f => (a -> Value) -> ([a] -> Value) -> [f a] -> Value
liftToEncoding :: ToJSON1 f => (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding
liftToEncoding :: (ToJSON1 f, Generic1 f, GToJSON' Encoding One (Rep1 f)) => (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding
liftToEncodingList :: ToJSON1 f => (a -> Encoding) -> ([a] -> Encoding) -> [f a] -> Encoding

-- | Lift the standard <a>toJSON</a> function through the type constructor.
toJSON1 :: (ToJSON1 f, ToJSON a) => f a -> Value

-- | Lift the standard <a>toEncoding</a> function through the type
--   constructor.
toEncoding1 :: (ToJSON1 f, ToJSON a) => f a -> Encoding

-- | Lifting of the <a>ToJSON</a> class to binary type constructors.
--   
--   Instead of manually writing your <a>ToJSON2</a> instance,
--   <a>Data.Aeson.TH</a> provides Template Haskell functions which will
--   derive an instance at compile time.
--   
--   The compiler cannot provide a default generic implementation for
--   <a>liftToJSON2</a>, unlike <a>toJSON</a> and <a>liftToJSON</a>.
class ToJSON2 f
liftToJSON2 :: ToJSON2 f => (a -> Value) -> ([a] -> Value) -> (b -> Value) -> ([b] -> Value) -> f a b -> Value
liftToJSONList2 :: ToJSON2 f => (a -> Value) -> ([a] -> Value) -> (b -> Value) -> ([b] -> Value) -> [f a b] -> Value
liftToEncoding2 :: ToJSON2 f => (a -> Encoding) -> ([a] -> Encoding) -> (b -> Encoding) -> ([b] -> Encoding) -> f a b -> Encoding
liftToEncodingList2 :: ToJSON2 f => (a -> Encoding) -> ([a] -> Encoding) -> (b -> Encoding) -> ([b] -> Encoding) -> [f a b] -> Encoding

-- | Lift the standard <a>toJSON</a> function through the type constructor.
toJSON2 :: (ToJSON2 f, ToJSON a, ToJSON b) => f a b -> Value

-- | Lift the standard <a>toEncoding</a> function through the type
--   constructor.
toEncoding2 :: (ToJSON2 f, ToJSON a, ToJSON b) => f a b -> Encoding

-- | Class of generic representation types that can be converted from JSON.
class GFromJSON arity f

-- | A <a>FromArgs</a> value either stores nothing (for <a>FromJSON</a>) or
--   it stores the two function arguments that decode occurrences of the
--   type parameter (for <a>FromJSON1</a>).
data FromArgs arity a
type GToJSON = GToJSON' Value
type GToEncoding = GToJSON' Encoding

-- | Class of generic representation types that can be converted to JSON.
class GToJSON' enc arity f

-- | A <a>ToArgs</a> value either stores nothing (for <a>ToJSON</a>) or it
--   stores the two function arguments that encode occurrences of the type
--   parameter (for <a>ToJSON1</a>).
data ToArgs res arity a

-- | A type-level indicator that <tt>ToJSON</tt> or <tt>FromJSON</tt> is
--   being derived generically.
data Zero

-- | A type-level indicator that <tt>ToJSON1</tt> or <tt>FromJSON1</tt> is
--   being derived generically.
data One

-- | A configurable generic JSON creator. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>toJSON</a> when
--   the type is an instance of <a>Generic</a>.
genericToJSON :: (Generic a, GToJSON' Value Zero (Rep a)) => Options -> a -> Value

-- | A configurable generic JSON creator. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftToJSON</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftToJSON :: (Generic1 f, GToJSON' Value One (Rep1 f)) => Options -> (a -> Value) -> ([a] -> Value) -> f a -> Value

-- | A configurable generic JSON encoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>toEncoding</a>
--   when the type is an instance of <a>Generic</a>.
genericToEncoding :: (Generic a, GToJSON' Encoding Zero (Rep a)) => Options -> a -> Encoding

-- | A configurable generic JSON encoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftToEncoding</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftToEncoding :: (Generic1 f, GToJSON' Encoding One (Rep1 f)) => Options -> (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding

-- | A configurable generic JSON decoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>parseJSON</a> when
--   the type is an instance of <a>Generic</a>.
genericParseJSON :: (Generic a, GFromJSON Zero (Rep a)) => Options -> Value -> Parser a

-- | A configurable generic JSON decoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftParseJSON</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftParseJSON :: (Generic1 f, GFromJSON One (Rep1 f)) => Options -> (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)

-- | <tt><a>withObject</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Object</a> when <tt>value</tt> is an <a>Object</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withObject "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Object, but encountered String"
--   </pre>
withObject :: String -> (Object -> Parser a) -> Value -> Parser a

-- | <tt><a>withText</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Text</a> when <tt>value</tt> is a <a>String</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withText "MyType" f Null
--   -- Error: "parsing MyType failed, expected String, but encountered Null"
--   </pre>
withText :: String -> (Text -> Parser a) -> Value -> Parser a

-- | <tt><a>withArray</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Array</a> when <tt>value</tt> is an <a>Array</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withArray "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Array, but encountered String"
--   </pre>
withArray :: String -> (Array -> Parser a) -> Value -> Parser a

-- | <tt><a>withScientific</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a> and
--   fails using <a>typeMismatch</a> otherwise.
--   
--   <i>Warning</i>: If you are converting from a scientific to an
--   unbounded type such as <a>Integer</a> you may want to add a
--   restriction on the size of the exponent (see
--   <a>withBoundedScientific</a>) to prevent malicious input from filling
--   up the memory of the target system.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withScientific "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Number, but encountered String"
--   </pre>
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a

-- | <tt><a>withBool</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Value</a> when <tt>value</tt> is a <tt>Boolean</tt> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withBool "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Boolean, but encountered String"
--   </pre>
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: String -> (Value -> Parser a) -> Value -> Parser a

-- | Encode a series of key/value pairs, separated by commas.
pairs :: Series -> Encoding

-- | Encode a <a>Foldable</a> as a JSON array.
foldable :: (Foldable t, ToJSON a) => t a -> Encoding

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <tt>empty</tt> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: FromJSON a => Object -> Key -> Parser a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or <tt>empty</tt> if the value cannot be converted to
--   the desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or
--   <tt>empty</tt> if the value cannot be converted to the desired type.
--   
--   This differs from <a>.:?</a> by attempting to parse <a>Null</a> the
--   same as any other JSON value, instead of interpreting it as
--   <a>Nothing</a>.
(.:!) :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Helper for use in combination with <a>.:?</a> to provide default
--   values for optional JSON object fields.
--   
--   This combinator is most useful if the key and value can be absent from
--   an object without affecting its validity and we know a default value
--   to assign in that case. If the key and value are mandatory, use
--   <a>.:</a> instead.
--   
--   Example usage:
--   
--   <pre>
--   v1 &lt;- o <a>.:?</a> "opt_field_with_dfl" .!= "default_val"
--   v2 &lt;- o <a>.:</a>  "mandatory_field"
--   v3 &lt;- o <a>.:?</a> "opt_field2"
--   </pre>
(.!=) :: Parser (Maybe a) -> a -> Parser a

-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
--   duplicate keys arise, later keys and their associated values win.
object :: [Pair] -> Value

-- | Function variant of <a>.:</a>.
parseField :: FromJSON a => Object -> Key -> Parser a

-- | Function variant of <a>.:?</a>.
parseFieldMaybe :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Function variant of <a>.:!</a>.
parseFieldMaybe' :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Variant of <a>.:</a> with explicit parser function.
--   
--   E.g. <tt><a>explicitParseField</a> <a>parseJSON1</a> ::
--   (<a>FromJSON1</a> f, <a>FromJSON</a> a) -&gt; <a>Object</a> -&gt;
--   <a>Text</a> -&gt; <a>Parser</a> (f a)</tt>
explicitParseField :: (Value -> Parser a) -> Object -> Key -> Parser a

-- | Variant of <a>.:?</a> with explicit parser function.
explicitParseFieldMaybe :: (Value -> Parser a) -> Object -> Key -> Parser (Maybe a)

-- | Variant of <a>.:!</a> with explicit parser function.
explicitParseFieldMaybe' :: (Value -> Parser a) -> Object -> Key -> Parser (Maybe a)

-- | Helper function to use with <a>liftToEncoding</a>. Useful when writing
--   own <a>ToJSON1</a> instances.
--   
--   <pre>
--   newtype F a = F [a]
--   
--   -- This instance encodes <a>Value</a> as an array of chars
--   instance <a>ToJSON1</a> F where
--       <a>liftToJSON</a>     tj _ (F xs) = <a>liftToJSON</a>     tj (<a>listValue</a>    tj) xs
--       <a>liftToEncoding</a> te _ (F xs) = <a>liftToEncoding</a> te (<a>listEncoding</a> te) xs
--   
--   instance <a>FromJSON1</a> F where
--       <a>liftParseJSON</a> p _ v = F &lt;$&gt; <a>liftParseJSON</a> p (<a>listParser</a> p) v
--   </pre>
listEncoding :: (a -> Encoding) -> [a] -> Encoding

-- | Helper function to use with <a>liftToJSON</a>, see
--   <a>listEncoding</a>.
listValue :: (a -> Value) -> [a] -> Value

-- | Helper function to use with <a>liftParseJSON</a>. See
--   <a>listEncoding</a>.
listParser :: (Value -> Parser a) -> Value -> Parser [a]

-- | Options that specify how to encode/decode your datatype to/from JSON.
--   
--   Options can be set using record syntax on <a>defaultOptions</a> with
--   the fields below.
data Options

-- | Function applied to field labels. Handy for removing common record
--   prefixes for example.
fieldLabelModifier :: Options -> String -> String

-- | Function applied to constructor tags which could be handy for
--   lower-casing them for example.
constructorTagModifier :: Options -> String -> String

-- | If <a>True</a> the constructors of a datatype, with <i>all</i> nullary
--   constructors, will be encoded to just a string with the constructor
--   tag. If <a>False</a> the encoding will always follow the
--   <a>sumEncoding</a>.
allNullaryToStringTag :: Options -> Bool

-- | If <a>True</a>, record fields with a <a>Nothing</a> value will be
--   omitted from the resulting object. If <a>False</a>, the resulting
--   object will include those fields mapping to <tt>null</tt>.
--   
--   Note that this <i>does not</i> affect parsing: <a>Maybe</a> fields are
--   optional regardless of the value of <a>omitNothingFields</a>, subject
--   to the note below.
--   
--   <h3>Note</h3>
--   
--   Setting <a>omitNothingFields</a> to <a>True</a> only affects fields
--   which are of type <a>Maybe</a> <i>uniformly</i> in the <tt>ToJSON</tt>
--   instance. In particular, if the type of a field is declared as a type
--   variable, it will not be omitted from the JSON object, unless the
--   field is specialized upfront in the instance.
--   
--   The same holds for <a>Maybe</a> fields being optional in the
--   <tt>FromJSON</tt> instance.
--   
--   <h4><b>Example</b></h4>
--   
--   The generic instance for the following type <tt>Fruit</tt> depends on
--   whether the instance head is <tt>Fruit a</tt> or <tt>Fruit (Maybe
--   a)</tt>.
--   
--   <pre>
--   data Fruit a = Fruit
--     { apples :: a  -- A field whose type is a type variable.
--     , oranges :: <a>Maybe</a> Int
--     } deriving <a>Generic</a>
--   
--   -- apples required, oranges optional
--   -- Even if <a>fromJSON</a> is then specialized to (Fruit (<a>Maybe</a> a)).
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON</a> (Fruit a)
--   
--   -- apples optional, oranges optional
--   -- In this instance, the field apples is uniformly of type (<a>Maybe</a> a).
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON</a> (Fruit (<a>Maybe</a> a))
--   
--   options :: <a>Options</a>
--   options = <a>defaultOptions</a> { <a>omitNothingFields</a> = <a>True</a> }
--   
--   -- apples always present in the output, oranges is omitted if <a>Nothing</a>
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON</a> (Fruit a) where
--     <a>toJSON</a> = <a>genericToJSON</a> options
--   
--   -- both apples and oranges are omitted if <a>Nothing</a>
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON</a> (Fruit (<a>Maybe</a> a)) where
--     <a>toJSON</a> = <a>genericToJSON</a> options
--   </pre>
omitNothingFields :: Options -> Bool

-- | Specifies how to encode constructors of a sum datatype.
sumEncoding :: Options -> SumEncoding

-- | Hide the field name when a record constructor has only one field, like
--   a newtype.
unwrapUnaryRecords :: Options -> Bool

-- | Encode types with a single constructor as sums, so that
--   <a>allNullaryToStringTag</a> and <a>sumEncoding</a> apply.
tagSingleConstructors :: Options -> Bool

-- | Applies only to <a>FromJSON</a> instances. If a field appears in the
--   parsed object map, but does not appear in the target object, parsing
--   will fail, with an error message indicating which fields were unknown.
rejectUnknownFields :: Options -> Bool

-- | Specifies how to encode constructors of a sum datatype.
data SumEncoding

-- | A constructor will be encoded to an object with a field
--   <a>tagFieldName</a> which specifies the constructor tag (modified by
--   the <a>constructorTagModifier</a>). If the constructor is a record the
--   encoded record fields will be unpacked into this object. So make sure
--   that your record doesn't have a field with the same label as the
--   <a>tagFieldName</a>. Otherwise the tag gets overwritten by the encoded
--   value of that field! If the constructor is not a record the encoded
--   constructor contents will be stored under the <a>contentsFieldName</a>
--   field.
TaggedObject :: String -> String -> SumEncoding
[tagFieldName] :: SumEncoding -> String
[contentsFieldName] :: SumEncoding -> String

-- | Constructor names won't be encoded. Instead only the contents of the
--   constructor will be encoded as if the type had a single constructor.
--   JSON encodings have to be disjoint for decoding to work properly.
--   
--   When decoding, constructors are tried in the order of definition. If
--   some encodings overlap, the first one defined will succeed.
--   
--   <i>Note:</i> Nullary constructors are encoded as strings (using
--   <a>constructorTagModifier</a>). Having a nullary constructor alongside
--   a single field constructor that encodes to a string leads to
--   ambiguity.
--   
--   <i>Note:</i> Only the last error is kept when decoding, so in the case
--   of malformed JSON, only an error for the last constructor will be
--   reported.
UntaggedValue :: SumEncoding

-- | A constructor will be encoded to an object with a single field named
--   after the constructor tag (modified by the
--   <a>constructorTagModifier</a>) which maps to the encoded contents of
--   the constructor.
ObjectWithSingleField :: SumEncoding

-- | A constructor will be encoded to a 2-element array where the first
--   element is the tag of the constructor (modified by the
--   <a>constructorTagModifier</a>) and the second element the encoded
--   contents of the constructor.
TwoElemArray :: SumEncoding

-- | Converts from CamelCase to another lower case, interspersing the
--   character between all capital letters and their previous entries,
--   except those capital letters that appear together, like <tt>API</tt>.
--   
--   For use by Aeson template haskell calls.
--   
--   <pre>
--   camelTo '_' 'CamelCaseAPI' == "camel_case_api"
--   </pre>

-- | <i>Deprecated: Use camelTo2 for better results</i>
camelTo :: Char -> String -> String

-- | Better version of <a>camelTo</a>. Example where it works better:
--   
--   <pre>
--   camelTo '_' "CamelAPICase" == "camel_apicase"
--   camelTo2 '_' "CamelAPICase" == "camel_api_case"
--   </pre>
camelTo2 :: Char -> String -> String

-- | Default encoding <a>Options</a>:
--   
--   <pre>
--   <a>Options</a>
--   { <a>fieldLabelModifier</a>      = id
--   , <a>constructorTagModifier</a>  = id
--   , <a>allNullaryToStringTag</a>   = True
--   , <a>omitNothingFields</a>       = False
--   , <a>sumEncoding</a>             = <a>defaultTaggedObject</a>
--   , <a>unwrapUnaryRecords</a>      = False
--   , <a>tagSingleConstructors</a>   = False
--   , <a>rejectUnknownFields</a>     = False
--   }
--   </pre>
defaultOptions :: Options

-- | Default <a>TaggedObject</a> <a>SumEncoding</a> options:
--   
--   <pre>
--   defaultTaggedObject = <a>TaggedObject</a>
--                         { <a>tagFieldName</a>      = "tag"
--                         , <a>contentsFieldName</a> = "contents"
--                         }
--   </pre>
defaultTaggedObject :: SumEncoding

-- | Options for encoding keys with <a>genericFromJSONKey</a> and
--   <a>genericToJSONKey</a>.
data JSONKeyOptions

-- | Function applied to keys. Its result is what goes into the encoded
--   <a>Value</a>.
--   
--   <h3><b>Example</b></h3>
--   
--   The following instances encode the constructor <tt>Bar</tt> to
--   lower-case keys <tt>"bar"</tt>.
--   
--   <pre>
--   data Foo = Bar
--     deriving <a>Generic</a>
--   
--   opts :: <a>JSONKeyOptions</a>
--   opts = <a>defaultJSONKeyOptions</a> { <a>keyModifier</a> = <a>toLower</a> }
--   
--   instance <tt>ToJSONKey</tt> Foo where
--     <tt>toJSONKey</tt> = <tt>genericToJSONKey</tt> opts
--   
--   instance <tt>FromJSONKey</tt> Foo where
--     <tt>fromJSONKey</tt> = <tt>genericFromJSONKey</tt> opts
--   </pre>
keyModifier :: JSONKeyOptions -> String -> String

-- | Default <a>JSONKeyOptions</a>:
--   
--   <pre>
--   defaultJSONKeyOptions = <a>JSONKeyOptions</a>
--                           { <a>keyModifier</a> = <a>id</a>
--                           }
--   </pre>
defaultJSONKeyOptions :: JSONKeyOptions

-- | Add JSON Path context to a parser
--   
--   When parsing a complex structure, it helps to annotate (sub)parsers
--   with context, so that if an error occurs, you can find its location.
--   
--   <pre>
--   withObject "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age"  &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a JSON Path
--   location of that error.
--   
--   Since 0.10
(<?>) :: Parser a -> JSONPathElement -> Parser a
type JSONPath = [JSONPathElement]

-- | Elements of a JSON path used to describe the location of an error.
data JSONPathElement

-- | JSON path element of a key into an object, "object.key".
Key :: Key -> JSONPathElement

-- | JSON path element of an index into an array, "array[index]".
Index :: {-# UNPACK #-} !Int -> JSONPathElement

-- | Format a <a>JSONPath</a> as a <a>Value</a>, representing the root
--   object as <tt>$</tt>.
formatPath :: JSONPath -> String

-- | Format a <a>JSONPath</a> as a <a>Value</a> which represents the path
--   relative to some root object.
formatRelativePath :: JSONPath -> String

-- | Annotate an error message with a <a>JSONPath</a> error location.
formatError :: JSONPath -> String -> String


-- | Most frequently, you'll probably want to encode straight to UTF-8 (the
--   standard JSON encoding) using <tt>encode</tt>.
--   
--   You can use the conversions to <a>Builder</a>s when embedding JSON
--   messages as parts of a protocol.
module Data.Aeson.Text

-- | Encode a JSON <a>Value</a> to a <a>Data.Text.Lazy</a>
--   
--   <i>Note:</i> uses <a>toEncoding</a>
encodeToLazyText :: ToJSON a => a -> Text

-- | Encode a JSON <a>Value</a> to a <a>Data.Text</a> <a>Builder</a>, which
--   can be embedded efficiently in a text-based protocol.
--   
--   If you are going to immediately encode straight to a
--   <a>ByteString</a>, it is more efficient to use <tt>encode</tt> (lazy
--   ByteString) or <tt><tt>fromEncoding</tt> . <a>toEncoding</a></tt>
--   (ByteString.Builder) instead.
--   
--   <i>Note:</i> Uses <a>toJSON</a>
encodeToTextBuilder :: ToJSON a => a -> Builder


-- | Types and functions for working efficiently with JSON data.
--   
--   (A note on naming: in Greek mythology, Aeson was the father of Jason.)
module Data.Aeson

-- | Efficiently deserialize a JSON value from a lazy <a>ByteString</a>. If
--   this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace.
--   
--   This function parses immediately, but defers conversion. See
--   <a>json</a> for details.
decode :: FromJSON a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a lazy <a>ByteString</a>. If
--   this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace.
--   
--   This function parses and performs conversion immediately. See
--   <a>json'</a> for details.
decode' :: FromJSON a => ByteString -> Maybe a

-- | Like <a>decode</a> but returns an error message when decoding fails.
eitherDecode :: FromJSON a => ByteString -> Either String a

-- | Like <a>decode'</a> but returns an error message when decoding fails.
eitherDecode' :: FromJSON a => ByteString -> Either String a

-- | Efficiently serialize a JSON value as a lazy <a>ByteString</a>.
--   
--   This is implemented in terms of the <a>ToJSON</a> class's
--   <a>toEncoding</a> method.
encode :: ToJSON a => a -> ByteString

-- | Efficiently serialize a JSON value as a lazy <a>ByteString</a> and
--   write it to a file.
encodeFile :: ToJSON a => FilePath -> a -> IO ()

-- | Efficiently deserialize a JSON value from a strict <a>ByteString</a>.
--   If this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace.
--   
--   This function parses immediately, but defers conversion. See
--   <a>json</a> for details.
decodeStrict :: FromJSON a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a file. If this fails due to
--   incomplete or invalid input, <a>Nothing</a> is returned.
--   
--   The input file's content must consist solely of a JSON document, with
--   no trailing data except for whitespace.
--   
--   This function parses immediately, but defers conversion. See
--   <a>json</a> for details.
decodeFileStrict :: FromJSON a => FilePath -> IO (Maybe a)

-- | Efficiently deserialize a JSON value from a strict <a>ByteString</a>.
--   If this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace.
--   
--   This function parses and performs conversion immediately. See
--   <a>json'</a> for details.
decodeStrict' :: FromJSON a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a file. If this fails due to
--   incomplete or invalid input, <a>Nothing</a> is returned.
--   
--   The input file's content must consist solely of a JSON document, with
--   no trailing data except for whitespace.
--   
--   This function parses and performs conversion immediately. See
--   <a>json'</a> for details.
decodeFileStrict' :: FromJSON a => FilePath -> IO (Maybe a)

-- | Like <a>decodeStrict</a> but returns an error message when decoding
--   fails.
eitherDecodeStrict :: FromJSON a => ByteString -> Either String a

-- | Like <a>decodeFileStrict</a> but returns an error message when
--   decoding fails.
eitherDecodeFileStrict :: FromJSON a => FilePath -> IO (Either String a)

-- | Like <a>decodeStrict'</a> but returns an error message when decoding
--   fails.
eitherDecodeStrict' :: FromJSON a => ByteString -> Either String a

-- | Like <a>decodeFileStrict'</a> but returns an error message when
--   decoding fails.
eitherDecodeFileStrict' :: FromJSON a => FilePath -> IO (Either String a)

-- | Exception thrown by <a>throwDecode</a> and variants.
newtype AesonException
AesonException :: String -> AesonException

-- | Like <a>decode</a> but throws an <a>AesonException</a> when decoding
--   fails.
--   
--   <pre>
--   &gt;&gt;&gt; throwDecode "42" :: Maybe Int
--   Just 42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; throwDecode "42" :: IO Int
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; throwDecode "true" :: IO Int
--   ...Exception: AesonException...
--   </pre>
throwDecode :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Like <a>decodeStrict</a> but throws an <a>AesonException</a> when
--   decoding fails.
throwDecodeStrict :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Like <a>decode'</a> but throws an <a>AesonException</a> when decoding
--   fails.
throwDecode' :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Like <a>decodeStrict'</a> but throws an <a>AesonException</a> when
--   decoding fails.
throwDecodeStrict' :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | A JSON value represented as a Haskell value.
data Value
Object :: !Object -> Value
Array :: !Array -> Value
String :: !Text -> Value
Number :: !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value

-- | Often used synonym for <a>Encoding'</a>.
type Encoding = Encoding' Value

-- | Acquire the underlying bytestring builder.
fromEncoding :: Encoding' tag -> Builder

-- | A JSON "array" (sequence).
type Array = Vector Value

-- | A JSON "object" (key/value map).
type Object = KeyMap Value
data Key

-- | A newtype wrapper for <a>UTCTime</a> that uses the same non-standard
--   serialization format as Microsoft .NET, whose <a>System.DateTime</a>
--   type is by default serialized to JSON as in the following example:
--   
--   <pre>
--   /Date(1302547608878)/
--   </pre>
--   
--   The number represents milliseconds since the Unix epoch.
newtype DotNetTime
DotNetTime :: UTCTime -> DotNetTime

-- | Acquire the underlying value.
[fromDotNetTime] :: DotNetTime -> UTCTime

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   In many cases, you can get the compiler to generate parsing code for
--   you (see below). To begin, let's cover writing an instance by hand.
--   
--   There are various reasons a conversion could fail. For example, an
--   <a>Object</a> could be missing a required key, an <a>Array</a> could
--   be of the wrong size, or a value could be of an incompatible type.
--   
--   The basic ways to signal a failed conversion are as follows:
--   
--   <ul>
--   <li><a>fail</a> yields a custom error message: it is the recommended
--   way of reporting a failure;</li>
--   <li><a>empty</a> (or <a>mzero</a>) is uninformative: use it when the
--   error is meant to be caught by some <tt>(<a>&lt;|&gt;</a>)</tt>;</li>
--   <li><a>typeMismatch</a> can be used to report a failure when the
--   encountered value is not of the expected JSON type; <a>unexpected</a>
--   is an appropriate alternative when more than one type may be expected,
--   or to keep the expected type implicit.</li>
--   </ul>
--   
--   <a>prependFailure</a> (or <a>modifyFailure</a>) add more information
--   to a parser's error messages.
--   
--   An example type and instance using <a>typeMismatch</a> and
--   <a>prependFailure</a>:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> (<a>Object</a> v) = Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   
--       -- We do not expect a non-<a>Object</a> value here.
--       -- We could use <a>empty</a> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    =
--           <a>prependFailure</a> "parsing Coord failed, "
--               (<a>typeMismatch</a> "Object" invalid)
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withScientific</a>,
--   etc. are provided. Their use is to be preferred when possible, since
--   they are more terse. Using <a>withObject</a>, we can rewrite the above
--   instance (assuming the same language extension and data type) as:
--   
--   <pre>
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>withObject</a> "Coord" $ \v -&gt; Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   </pre>
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>parseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>FromJSON</a> instance for
--   your datatype without giving a definition for <a>parseJSON</a>.
--   
--   For example, the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>FromJSON</a> Coord
--   </pre>
--   
--   or using the <a>DerivingVia extension</a>
--   
--   <pre>
--   deriving via <a>Generically</a> Coord instance <a>FromJSON</a> Coord
--   </pre>
--   
--   The default implementation will be equivalent to <tt>parseJSON =
--   <a>genericParseJSON</a> <a>defaultOptions</a></tt>; if you need
--   different options, you can customize the generic decoding by defining:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>genericParseJSON</a> customOptions
--   </pre>
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
parseJSON :: (FromJSON a, Generic a, GFromJSON Zero (Rep a)) => Value -> Parser a
parseJSONList :: FromJSON a => Value -> Parser [a]

-- | The result of running a <a>Parser</a>.
data Result a
Error :: String -> Result a
Success :: a -> Result a

-- | Convert a value from JSON, failing if the types do not match.
fromJSON :: FromJSON a => Value -> Result a

-- | A type that can be converted to JSON.
--   
--   Instances in general <i>must</i> specify <a>toJSON</a> and
--   <i>should</i> (but don't need to) specify <a>toEncoding</a>.
--   
--   An example type and instance:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>ToJSON</a> Coord where
--     <a>toJSON</a> (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   
--     <a>toEncoding</a> (Coord x y) = <tt>pairs</tt> ("x" <a>.=</a> x <a>&lt;&gt;</a> "y" <a>.=</a> y)
--   </pre>
--   
--   Instead of manually writing your <a>ToJSON</a> instance, there are two
--   options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>toJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>ToJSON</a> instance. If you
--   require nothing other than <a>defaultOptions</a>, it is sufficient to
--   write (and this is the only alternative where the default
--   <a>toJSON</a> implementation is sufficient):
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
--   
--   or more conveniently using the <a>DerivingVia extension</a>
--   
--   <pre>
--   deriving via <a>Generically</a> Coord instance <a>ToJSON</a> Coord
--   </pre>
--   
--   If on the other hand you wish to customize the generic decoding, you
--   have to implement both methods:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toJSON</a>     = <a>genericToJSON</a> customOptions
--       <a>toEncoding</a> = <a>genericToEncoding</a> customOptions
--   </pre>
--   
--   Previous versions of this library only had the <a>toJSON</a> method.
--   Adding <a>toEncoding</a> had two reasons:
--   
--   <ol>
--   <li><a>toEncoding</a> is more efficient for the common case that the
--   output of <a>toJSON</a> is directly serialized to a
--   <tt>ByteString</tt>. Further, expressing either method in terms of the
--   other would be non-optimal.</li>
--   <li>The choice of defaults allows a smooth transition for existing
--   users: Existing instances that do not define <a>toEncoding</a> still
--   compile and have the correct semantics. This is ensured by making the
--   default implementation of <a>toEncoding</a> use <a>toJSON</a>. This
--   produces correct results, but since it performs an intermediate
--   conversion to a <a>Value</a>, it will be less efficient than directly
--   emitting an <a>Encoding</a>. (this also means that specifying nothing
--   more than <tt>instance ToJSON Coord</tt> would be sufficient as a
--   generically decoding instance, but there probably exists no good
--   reason to not specify <a>toEncoding</a> in new instances.)</li>
--   </ol>
class ToJSON a

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: ToJSON a => a -> Value

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: (ToJSON a, Generic a, GToJSON' Value Zero (Rep a)) => a -> Value

-- | Encode a Haskell value as JSON.
--   
--   The default implementation of this method creates an intermediate
--   <a>Value</a> using <a>toJSON</a>. This provides source-level
--   compatibility for people upgrading from older versions of this
--   library, but obviously offers no performance advantage.
--   
--   To benefit from direct encoding, you <i>must</i> provide an
--   implementation for this method. The easiest way to do so is by having
--   your types implement <a>Generic</a> using the <tt>DeriveGeneric</tt>
--   extension, and then have GHC generate a method body as follows.
--   
--   <pre>
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
toEncoding :: ToJSON a => a -> Encoding
toJSONList :: ToJSON a => [a] -> Value
toEncodingList :: ToJSON a => [a] -> Encoding

-- | A key-value pair for encoding a JSON object.
class KeyValue kv
(.=) :: (KeyValue kv, ToJSON v) => Key -> v -> kv
infixr 8 .=

-- | Add JSON Path context to a parser
--   
--   When parsing a complex structure, it helps to annotate (sub)parsers
--   with context, so that if an error occurs, you can find its location.
--   
--   <pre>
--   withObject "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age"  &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a JSON Path
--   location of that error.
--   
--   Since 0.10
(<?>) :: Parser a -> JSONPathElement -> Parser a
type JSONPath = [JSONPathElement]

-- | Typeclass for types that can be used as the key of a map-like
--   container (like <tt>Map</tt> or <tt>HashMap</tt>). For example, since
--   <a>Text</a> has a <a>ToJSONKey</a> instance and <a>Char</a> has a
--   <a>ToJSON</a> instance, we can encode a value of type <tt>Map</tt>
--   <a>Text</a> <a>Char</a>:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [("foo" :: Text, 'a')]
--   {"foo":"a"}
--   </pre>
--   
--   Since <a>Int</a> also has a <a>ToJSONKey</a> instance, we can
--   similarly write:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(5 :: Int, 'a')]
--   {"5":"a"}
--   </pre>
--   
--   JSON documents only accept strings as object keys. For any type from
--   <tt>base</tt> that has a natural textual representation, it can be
--   expected that its <a>ToJSONKey</a> instance will choose that
--   representation.
--   
--   For data types that lack a natural textual representation, an
--   alternative is provided. The map-like container is represented as a
--   JSON array instead of a JSON object. Each value in the array is an
--   array with exactly two values. The first is the key and the second is
--   the value.
--   
--   For example, values of type '[Text]' cannot be encoded to a string, so
--   a <tt>Map</tt> with keys of type '[Text]' is encoded as follows:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(["foo","bar","baz" :: Text], 'a')]
--   [[["foo","bar","baz"],"a"]]
--   </pre>
--   
--   The default implementation of <a>ToJSONKey</a> chooses this method of
--   encoding a key, using the <a>ToJSON</a> instance of the type.
--   
--   To use your own data type as the key in a map, all that is needed is
--   to write a <a>ToJSONKey</a> (and possibly a <tt>FromJSONKey</tt>)
--   instance for it. If the type cannot be trivially converted to and from
--   <a>Text</a>, it is recommended that <a>ToJSONKeyValue</a> is used.
--   Since the default implementations of the typeclass methods can build
--   this from a <a>ToJSON</a> instance, there is nothing that needs to be
--   written:
--   
--   <pre>
--   data Foo = Foo { fooAge :: Int, fooName :: Text }
--     deriving (Eq,Ord,Generic)
--   instance ToJSON Foo
--   instance ToJSONKey Foo
--   </pre>
--   
--   That's it. We can now write:
--   
--   <pre>
--   &gt;&gt;&gt; let m = Map.fromList [(Foo 4 "bar",'a'),(Foo 6 "arg",'b')]
--   
--   &gt;&gt;&gt; LBC8.putStrLn $ encode m
--   [[{"fooName":"bar","fooAge":4},"a"],[{"fooName":"arg","fooAge":6},"b"]]
--   </pre>
--   
--   The next case to consider is if we have a type that is a newtype
--   wrapper around <a>Text</a>. The recommended approach is to use
--   generalized newtype deriving:
--   
--   <pre>
--   newtype RecordId = RecordId { getRecordId :: Text }
--     deriving (Eq,Ord,ToJSONKey)
--   </pre>
--   
--   Then we may write:
--   
--   <pre>
--   &gt;&gt;&gt; LBC8.putStrLn $ encode $ Map.fromList [(RecordId "abc",'a')]
--   {"abc":"a"}
--   </pre>
--   
--   Simple sum types are a final case worth considering. Suppose we have:
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving (Show,Read,Eq,Ord)
--   </pre>
--   
--   It is possible to get the <a>ToJSONKey</a> instance for free as we did
--   with <tt>Foo</tt>. However, in this case, we have a natural way to go
--   to and from <a>Text</a> that does not require any escape sequences. So
--   <a>ToJSONKeyText</a> can be used instead of <a>ToJSONKeyValue</a> to
--   encode maps as objects instead of arrays of pairs. This instance may
--   be implemented using generics as follows:
--   
--   <pre>
--   instance <a>ToJSONKey</a> Color where
--     <a>toJSONKey</a> = <a>genericToJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
--   
--   <h3><b>Low-level implementations</b></h3>
--   
--   The <a>Show</a> instance can be used to help write <a>ToJSONKey</a>:
--   
--   <pre>
--   instance ToJSONKey Color where
--     toJSONKey = ToJSONKeyText f g
--       where f = Text.pack . show
--             g = text . Text.pack . show
--             -- text function is from Data.Aeson.Encoding
--   </pre>
--   
--   The situation of needing to turning function <tt>a -&gt; Text</tt>
--   into a <a>ToJSONKeyFunction</a> is common enough that a special
--   combinator is provided for it. The above instance can be rewritten as:
--   
--   <pre>
--   instance ToJSONKey Color where
--     toJSONKey = toJSONKeyText (Text.pack . show)
--   </pre>
--   
--   The performance of the above instance can be improved by not using
--   <a>Value</a> as an intermediate step when converting to <a>Text</a>.
--   One option for improving performance would be to use template haskell
--   machinery from the <tt>text-show</tt> package. However, even with the
--   approach, the <a>Encoding</a> (a wrapper around a bytestring builder)
--   is generated by encoding the <a>Text</a> to a <tt>ByteString</tt>, an
--   intermediate step that could be avoided. The fastest possible
--   implementation would be:
--   
--   <pre>
--   -- Assuming that OverloadedStrings is enabled
--   instance ToJSONKey Color where
--     toJSONKey = ToJSONKeyText f g
--       where f x = case x of {Red -&gt; "Red";Green -&gt;"Green";Blue -&gt; "Blue"}
--             g x = case x of {Red -&gt; text "Red";Green -&gt; text "Green";Blue -&gt; text "Blue"}
--             -- text function is from Data.Aeson.Encoding
--   </pre>
--   
--   This works because GHC can lift the encoded values out of the case
--   statements, which means that they are only evaluated once. This
--   approach should only be used when there is a serious need to maximize
--   performance.
class ToJSONKey a

-- | Strategy for rendering the key for a map-like container.
toJSONKey :: ToJSONKey a => ToJSONKeyFunction a

-- | Strategy for rendering the key for a map-like container.
toJSONKey :: (ToJSONKey a, ToJSON a) => ToJSONKeyFunction a

-- | This is similar in spirit to the <tt>showsList</tt> method of
--   <a>Show</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
toJSONKeyList :: ToJSONKey a => ToJSONKeyFunction [a]

-- | This is similar in spirit to the <tt>showsList</tt> method of
--   <a>Show</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
toJSONKeyList :: (ToJSONKey a, ToJSON a) => ToJSONKeyFunction [a]
data ToJSONKeyFunction a

-- | key is encoded to string, produces object
ToJSONKeyText :: !a -> Key -> !a -> Encoding' Key -> ToJSONKeyFunction a

-- | key is encoded to value, produces array
ToJSONKeyValue :: !a -> Value -> !a -> Encoding -> ToJSONKeyFunction a

-- | Read the docs for <tt>ToJSONKey</tt> first. This class is a conversion
--   in the opposite direction. If you have a newtype wrapper around
--   <a>Text</a>, the recommended way to define instances is with
--   generalized newtype deriving:
--   
--   <pre>
--   newtype SomeId = SomeId { getSomeId :: Text }
--     deriving (Eq,Ord,Hashable,FromJSONKey)
--   </pre>
--   
--   If you have a sum of nullary constructors, you may use the generic
--   implementation:
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving Generic
--   
--   instance <a>FromJSONKey</a> Color where
--     <a>fromJSONKey</a> = <a>genericFromJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
class FromJSONKey a

-- | Strategy for parsing the key of a map-like container.
fromJSONKey :: FromJSONKey a => FromJSONKeyFunction a

-- | Strategy for parsing the key of a map-like container.
fromJSONKey :: (FromJSONKey a, FromJSON a) => FromJSONKeyFunction a

-- | This is similar in spirit to the <a>readList</a> method of
--   <a>Read</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
fromJSONKeyList :: FromJSONKey a => FromJSONKeyFunction [a]

-- | This is similar in spirit to the <a>readList</a> method of
--   <a>Read</a>. It makes it possible to give <a>Value</a> keys special
--   treatment without using <tt>OverlappingInstances</tt>. End users
--   should always be able to use the default implementation of this
--   method.
fromJSONKeyList :: (FromJSONKey a, FromJSON a) => FromJSONKeyFunction [a]

-- | This type is related to <tt>ToJSONKeyFunction</tt>. If
--   <a>FromJSONKeyValue</a> is used in the <a>FromJSONKey</a> instance,
--   then <tt>ToJSONKeyValue</tt> should be used in the <tt>ToJSONKey</tt>
--   instance. The other three data constructors for this type all
--   correspond to <tt>ToJSONKeyText</tt>. Strictly speaking,
--   <a>FromJSONKeyTextParser</a> is more powerful than
--   <a>FromJSONKeyText</a>, which is in turn more powerful than
--   <a>FromJSONKeyCoerce</a>. For performance reasons, these exist as
--   three options instead of one.
data FromJSONKeyFunction a
[FromJSONKeyCoerce] :: Coercible Text a => FromJSONKeyFunction a
[FromJSONKeyText] :: !Text -> a -> FromJSONKeyFunction a
[FromJSONKeyTextParser] :: !Text -> Parser a -> FromJSONKeyFunction a
[FromJSONKeyValue] :: !Value -> Parser a -> FromJSONKeyFunction a
class GetConName f => GToJSONKey f
genericToJSONKey :: (Generic a, GToJSONKey (Rep a)) => JSONKeyOptions -> ToJSONKeyFunction a
class (ConstructorNames f, SumFromString f) => GFromJSONKey f

-- | <a>fromJSONKey</a> for <a>Generic</a> types. These types must be sums
--   of nullary constructors, whose names will be used as keys for JSON
--   objects.
--   
--   See also <tt>genericToJSONKey</tt>.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   data Color = Red | Green | Blue
--     deriving <a>Generic</a>
--   
--   instance <a>FromJSONKey</a> Color where
--     <a>fromJSONKey</a> = <a>genericFromJSONKey</a> <a>defaultJSONKeyOptions</a>
--   </pre>
genericFromJSONKey :: forall a. (Generic a, GFromJSONKey (Rep a)) => JSONKeyOptions -> FromJSONKeyFunction a

-- | Lifting of the <a>FromJSON</a> class to unary type constructors.
--   
--   Instead of manually writing your <a>FromJSON1</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>liftParseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic1</a></tt>
--   clause to your datatype and declare a <a>FromJSON1</a> instance for
--   your datatype without giving a definition for <a>liftParseJSON</a>.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving <a>Generic1</a>
--   
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON1</a> (Pair a)
--   </pre>
--   
--   or
--   
--   <pre>
--   deriving via <a>Generically1</a> (Pair a) instance <a>FromJSON1</a> (Pair a)
--   </pre>
--   
--   If the default implementation doesn't give exactly the results you
--   want, you can customize the generic decoding with only a tiny amount
--   of effort, using <a>genericLiftParseJSON</a> with your preferred
--   <a>Options</a>:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON1</a> (Pair a) where
--       <a>liftParseJSON</a> = <a>genericLiftParseJSON</a> customOptions
--   </pre>
class FromJSON1 f
liftParseJSON :: FromJSON1 f => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)
liftParseJSON :: (FromJSON1 f, Generic1 f, GFromJSON One (Rep1 f)) => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)
liftParseJSONList :: FromJSON1 f => (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser [f a]

-- | Lift the standard <a>parseJSON</a> function through the type
--   constructor.
parseJSON1 :: (FromJSON1 f, FromJSON a) => Value -> Parser (f a)

-- | Lifting of the <a>FromJSON</a> class to binary type constructors.
--   
--   Instead of manually writing your <a>FromJSON2</a> instance,
--   <a>Data.Aeson.TH</a> provides Template Haskell functions which will
--   derive an instance at compile time.
class FromJSON2 f
liftParseJSON2 :: FromJSON2 f => (Value -> Parser a) -> (Value -> Parser [a]) -> (Value -> Parser b) -> (Value -> Parser [b]) -> Value -> Parser (f a b)
liftParseJSONList2 :: FromJSON2 f => (Value -> Parser a) -> (Value -> Parser [a]) -> (Value -> Parser b) -> (Value -> Parser [b]) -> Value -> Parser [f a b]

-- | Lift the standard <a>parseJSON</a> function through the type
--   constructor.
parseJSON2 :: (FromJSON2 f, FromJSON a, FromJSON b) => Value -> Parser (f a b)

-- | Lifting of the <a>ToJSON</a> class to unary type constructors.
--   
--   Instead of manually writing your <a>ToJSON1</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>toJSON1</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic1</a></tt>
--   clause to your datatype and declare a <a>ToJSON1</a> instance for your
--   datatype without giving definitions for <a>liftToJSON</a> or
--   <a>liftToEncoding</a>.
--   
--   For example:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving <a>Generic1</a>
--   
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON1</a> (Pair a)
--   </pre>
--   
--   If the default implementation doesn't give exactly the results you
--   want, you can customize the generic encoding with only a tiny amount
--   of effort, using <a>genericLiftToJSON</a> and
--   <a>genericLiftToEncoding</a> with your preferred <a>Options</a>:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON1</a> (Pair a) where
--       <a>liftToJSON</a>     = <a>genericLiftToJSON</a> customOptions
--       <a>liftToEncoding</a> = <a>genericLiftToEncoding</a> customOptions
--   </pre>
--   
--   See also <a>ToJSON</a>.
class ToJSON1 f
liftToJSON :: ToJSON1 f => (a -> Value) -> ([a] -> Value) -> f a -> Value
liftToJSON :: (ToJSON1 f, Generic1 f, GToJSON' Value One (Rep1 f)) => (a -> Value) -> ([a] -> Value) -> f a -> Value
liftToJSONList :: ToJSON1 f => (a -> Value) -> ([a] -> Value) -> [f a] -> Value
liftToEncoding :: ToJSON1 f => (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding
liftToEncoding :: (ToJSON1 f, Generic1 f, GToJSON' Encoding One (Rep1 f)) => (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding
liftToEncodingList :: ToJSON1 f => (a -> Encoding) -> ([a] -> Encoding) -> [f a] -> Encoding

-- | Lift the standard <a>toJSON</a> function through the type constructor.
toJSON1 :: (ToJSON1 f, ToJSON a) => f a -> Value

-- | Lift the standard <a>toEncoding</a> function through the type
--   constructor.
toEncoding1 :: (ToJSON1 f, ToJSON a) => f a -> Encoding

-- | Lifting of the <a>ToJSON</a> class to binary type constructors.
--   
--   Instead of manually writing your <a>ToJSON2</a> instance,
--   <a>Data.Aeson.TH</a> provides Template Haskell functions which will
--   derive an instance at compile time.
--   
--   The compiler cannot provide a default generic implementation for
--   <a>liftToJSON2</a>, unlike <a>toJSON</a> and <a>liftToJSON</a>.
class ToJSON2 f
liftToJSON2 :: ToJSON2 f => (a -> Value) -> ([a] -> Value) -> (b -> Value) -> ([b] -> Value) -> f a b -> Value
liftToJSONList2 :: ToJSON2 f => (a -> Value) -> ([a] -> Value) -> (b -> Value) -> ([b] -> Value) -> [f a b] -> Value
liftToEncoding2 :: ToJSON2 f => (a -> Encoding) -> ([a] -> Encoding) -> (b -> Encoding) -> ([b] -> Encoding) -> f a b -> Encoding
liftToEncodingList2 :: ToJSON2 f => (a -> Encoding) -> ([a] -> Encoding) -> (b -> Encoding) -> ([b] -> Encoding) -> [f a b] -> Encoding

-- | Lift the standard <a>toJSON</a> function through the type constructor.
toJSON2 :: (ToJSON2 f, ToJSON a, ToJSON b) => f a b -> Value

-- | Lift the standard <a>toEncoding</a> function through the type
--   constructor.
toEncoding2 :: (ToJSON2 f, ToJSON a, ToJSON b) => f a b -> Encoding

-- | Class of generic representation types that can be converted from JSON.
class GFromJSON arity f

-- | A <a>FromArgs</a> value either stores nothing (for <a>FromJSON</a>) or
--   it stores the two function arguments that decode occurrences of the
--   type parameter (for <a>FromJSON1</a>).
data FromArgs arity a
type GToJSON = GToJSON' Value
type GToEncoding = GToJSON' Encoding

-- | Class of generic representation types that can be converted to JSON.
class GToJSON' enc arity f

-- | A <a>ToArgs</a> value either stores nothing (for <a>ToJSON</a>) or it
--   stores the two function arguments that encode occurrences of the type
--   parameter (for <a>ToJSON1</a>).
data ToArgs res arity a

-- | A type-level indicator that <tt>ToJSON</tt> or <tt>FromJSON</tt> is
--   being derived generically.
data Zero

-- | A type-level indicator that <tt>ToJSON1</tt> or <tt>FromJSON1</tt> is
--   being derived generically.
data One

-- | A configurable generic JSON creator. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>toJSON</a> when
--   the type is an instance of <a>Generic</a>.
genericToJSON :: (Generic a, GToJSON' Value Zero (Rep a)) => Options -> a -> Value

-- | A configurable generic JSON creator. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftToJSON</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftToJSON :: (Generic1 f, GToJSON' Value One (Rep1 f)) => Options -> (a -> Value) -> ([a] -> Value) -> f a -> Value

-- | A configurable generic JSON encoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>toEncoding</a>
--   when the type is an instance of <a>Generic</a>.
genericToEncoding :: (Generic a, GToJSON' Encoding Zero (Rep a)) => Options -> a -> Encoding

-- | A configurable generic JSON encoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftToEncoding</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftToEncoding :: (Generic1 f, GToJSON' Encoding One (Rep1 f)) => Options -> (a -> Encoding) -> ([a] -> Encoding) -> f a -> Encoding

-- | A configurable generic JSON decoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>parseJSON</a> when
--   the type is an instance of <a>Generic</a>.
genericParseJSON :: (Generic a, GFromJSON Zero (Rep a)) => Options -> Value -> Parser a

-- | A configurable generic JSON decoder. This function applied to
--   <a>defaultOptions</a> is used as the default for <a>liftParseJSON</a>
--   when the type is an instance of <a>Generic1</a>.
genericLiftParseJSON :: (Generic1 f, GFromJSON One (Rep1 f)) => Options -> (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)

-- | Options that specify how to encode/decode your datatype to/from JSON.
--   
--   Options can be set using record syntax on <a>defaultOptions</a> with
--   the fields below.
data Options

-- | Default encoding <a>Options</a>:
--   
--   <pre>
--   <a>Options</a>
--   { <a>fieldLabelModifier</a>      = id
--   , <a>constructorTagModifier</a>  = id
--   , <a>allNullaryToStringTag</a>   = True
--   , <a>omitNothingFields</a>       = False
--   , <a>sumEncoding</a>             = <a>defaultTaggedObject</a>
--   , <a>unwrapUnaryRecords</a>      = False
--   , <a>tagSingleConstructors</a>   = False
--   , <a>rejectUnknownFields</a>     = False
--   }
--   </pre>
defaultOptions :: Options

-- | Function applied to field labels. Handy for removing common record
--   prefixes for example.
fieldLabelModifier :: Options -> String -> String

-- | Function applied to constructor tags which could be handy for
--   lower-casing them for example.
constructorTagModifier :: Options -> String -> String

-- | If <a>True</a> the constructors of a datatype, with <i>all</i> nullary
--   constructors, will be encoded to just a string with the constructor
--   tag. If <a>False</a> the encoding will always follow the
--   <a>sumEncoding</a>.
allNullaryToStringTag :: Options -> Bool

-- | If <a>True</a>, record fields with a <a>Nothing</a> value will be
--   omitted from the resulting object. If <a>False</a>, the resulting
--   object will include those fields mapping to <tt>null</tt>.
--   
--   Note that this <i>does not</i> affect parsing: <a>Maybe</a> fields are
--   optional regardless of the value of <a>omitNothingFields</a>, subject
--   to the note below.
--   
--   <h3>Note</h3>
--   
--   Setting <a>omitNothingFields</a> to <a>True</a> only affects fields
--   which are of type <a>Maybe</a> <i>uniformly</i> in the <tt>ToJSON</tt>
--   instance. In particular, if the type of a field is declared as a type
--   variable, it will not be omitted from the JSON object, unless the
--   field is specialized upfront in the instance.
--   
--   The same holds for <a>Maybe</a> fields being optional in the
--   <tt>FromJSON</tt> instance.
--   
--   <h4><b>Example</b></h4>
--   
--   The generic instance for the following type <tt>Fruit</tt> depends on
--   whether the instance head is <tt>Fruit a</tt> or <tt>Fruit (Maybe
--   a)</tt>.
--   
--   <pre>
--   data Fruit a = Fruit
--     { apples :: a  -- A field whose type is a type variable.
--     , oranges :: <a>Maybe</a> Int
--     } deriving <a>Generic</a>
--   
--   -- apples required, oranges optional
--   -- Even if <a>fromJSON</a> is then specialized to (Fruit (<a>Maybe</a> a)).
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON</a> (Fruit a)
--   
--   -- apples optional, oranges optional
--   -- In this instance, the field apples is uniformly of type (<a>Maybe</a> a).
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON</a> (Fruit (<a>Maybe</a> a))
--   
--   options :: <a>Options</a>
--   options = <a>defaultOptions</a> { <a>omitNothingFields</a> = <a>True</a> }
--   
--   -- apples always present in the output, oranges is omitted if <a>Nothing</a>
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON</a> (Fruit a) where
--     <a>toJSON</a> = <a>genericToJSON</a> options
--   
--   -- both apples and oranges are omitted if <a>Nothing</a>
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON</a> (Fruit (<a>Maybe</a> a)) where
--     <a>toJSON</a> = <a>genericToJSON</a> options
--   </pre>
omitNothingFields :: Options -> Bool

-- | Specifies how to encode constructors of a sum datatype.
sumEncoding :: Options -> SumEncoding

-- | Hide the field name when a record constructor has only one field, like
--   a newtype.
unwrapUnaryRecords :: Options -> Bool

-- | Encode types with a single constructor as sums, so that
--   <a>allNullaryToStringTag</a> and <a>sumEncoding</a> apply.
tagSingleConstructors :: Options -> Bool

-- | Applies only to <a>FromJSON</a> instances. If a field appears in the
--   parsed object map, but does not appear in the target object, parsing
--   will fail, with an error message indicating which fields were unknown.
rejectUnknownFields :: Options -> Bool

-- | Specifies how to encode constructors of a sum datatype.
data SumEncoding

-- | A constructor will be encoded to an object with a field
--   <a>tagFieldName</a> which specifies the constructor tag (modified by
--   the <a>constructorTagModifier</a>). If the constructor is a record the
--   encoded record fields will be unpacked into this object. So make sure
--   that your record doesn't have a field with the same label as the
--   <a>tagFieldName</a>. Otherwise the tag gets overwritten by the encoded
--   value of that field! If the constructor is not a record the encoded
--   constructor contents will be stored under the <a>contentsFieldName</a>
--   field.
TaggedObject :: String -> String -> SumEncoding
[tagFieldName] :: SumEncoding -> String
[contentsFieldName] :: SumEncoding -> String

-- | Constructor names won't be encoded. Instead only the contents of the
--   constructor will be encoded as if the type had a single constructor.
--   JSON encodings have to be disjoint for decoding to work properly.
--   
--   When decoding, constructors are tried in the order of definition. If
--   some encodings overlap, the first one defined will succeed.
--   
--   <i>Note:</i> Nullary constructors are encoded as strings (using
--   <a>constructorTagModifier</a>). Having a nullary constructor alongside
--   a single field constructor that encodes to a string leads to
--   ambiguity.
--   
--   <i>Note:</i> Only the last error is kept when decoding, so in the case
--   of malformed JSON, only an error for the last constructor will be
--   reported.
UntaggedValue :: SumEncoding

-- | A constructor will be encoded to an object with a single field named
--   after the constructor tag (modified by the
--   <a>constructorTagModifier</a>) which maps to the encoded contents of
--   the constructor.
ObjectWithSingleField :: SumEncoding

-- | A constructor will be encoded to a 2-element array where the first
--   element is the tag of the constructor (modified by the
--   <a>constructorTagModifier</a>) and the second element the encoded
--   contents of the constructor.
TwoElemArray :: SumEncoding

-- | Better version of <a>camelTo</a>. Example where it works better:
--   
--   <pre>
--   camelTo '_' "CamelAPICase" == "camel_apicase"
--   camelTo2 '_' "CamelAPICase" == "camel_api_case"
--   </pre>
camelTo2 :: Char -> String -> String

-- | Default <a>TaggedObject</a> <a>SumEncoding</a> options:
--   
--   <pre>
--   defaultTaggedObject = <a>TaggedObject</a>
--                         { <a>tagFieldName</a>      = "tag"
--                         , <a>contentsFieldName</a> = "contents"
--                         }
--   </pre>
defaultTaggedObject :: SumEncoding

-- | Options for encoding keys with <a>genericFromJSONKey</a> and
--   <a>genericToJSONKey</a>.
data JSONKeyOptions

-- | Function applied to keys. Its result is what goes into the encoded
--   <a>Value</a>.
--   
--   <h3><b>Example</b></h3>
--   
--   The following instances encode the constructor <tt>Bar</tt> to
--   lower-case keys <tt>"bar"</tt>.
--   
--   <pre>
--   data Foo = Bar
--     deriving <a>Generic</a>
--   
--   opts :: <a>JSONKeyOptions</a>
--   opts = <a>defaultJSONKeyOptions</a> { <a>keyModifier</a> = <a>toLower</a> }
--   
--   instance <tt>ToJSONKey</tt> Foo where
--     <tt>toJSONKey</tt> = <tt>genericToJSONKey</tt> opts
--   
--   instance <tt>FromJSONKey</tt> Foo where
--     <tt>fromJSONKey</tt> = <tt>genericFromJSONKey</tt> opts
--   </pre>
keyModifier :: JSONKeyOptions -> String -> String

-- | Default <a>JSONKeyOptions</a>:
--   
--   <pre>
--   defaultJSONKeyOptions = <a>JSONKeyOptions</a>
--                           { <a>keyModifier</a> = <a>id</a>
--                           }
--   </pre>
defaultJSONKeyOptions :: JSONKeyOptions

-- | <tt><a>withObject</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Object</a> when <tt>value</tt> is an <a>Object</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withObject "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Object, but encountered String"
--   </pre>
withObject :: String -> (Object -> Parser a) -> Value -> Parser a

-- | <tt><a>withText</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Text</a> when <tt>value</tt> is a <a>String</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withText "MyType" f Null
--   -- Error: "parsing MyType failed, expected String, but encountered Null"
--   </pre>
withText :: String -> (Text -> Parser a) -> Value -> Parser a

-- | <tt><a>withArray</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Array</a> when <tt>value</tt> is an <a>Array</a> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withArray "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Array, but encountered String"
--   </pre>
withArray :: String -> (Array -> Parser a) -> Value -> Parser a

-- | <tt><a>withScientific</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a> and
--   fails using <a>typeMismatch</a> otherwise.
--   
--   <i>Warning</i>: If you are converting from a scientific to an
--   unbounded type such as <a>Integer</a> you may want to add a
--   restriction on the size of the exponent (see
--   <a>withBoundedScientific</a>) to prevent malicious input from filling
--   up the memory of the target system.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withScientific "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Number, but encountered String"
--   </pre>
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a

-- | <tt><a>withBool</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Value</a> when <tt>value</tt> is a <tt>Boolean</tt> and fails
--   otherwise.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withBool "MyType" f (String "oops")
--   -- Error: "parsing MyType failed, expected Boolean, but encountered String"
--   </pre>
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: String -> (Value -> Parser a) -> Value -> Parser a

-- | A series of values that, when encoded, should be separated by commas.
--   Since 0.11.0.0, the <tt>.=</tt> operator is overloaded to create
--   either <tt>(Text, Value)</tt> or <a>Series</a>. You can use Series
--   when encoding directly to a bytestring builder as in the following
--   example:
--   
--   <pre>
--   toEncoding (Person name age) = pairs ("name" .= name &lt;&gt; "age" .= age)
--   </pre>
data Series

-- | Encode a series of key/value pairs, separated by commas.
pairs :: Series -> Encoding

-- | Encode a <a>Foldable</a> as a JSON array.
foldable :: (Foldable t, ToJSON a) => t a -> Encoding

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <tt>empty</tt> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: FromJSON a => Object -> Key -> Parser a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or <tt>empty</tt> if the value cannot be converted to
--   the desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or
--   <tt>empty</tt> if the value cannot be converted to the desired type.
--   
--   This differs from <a>.:?</a> by attempting to parse <a>Null</a> the
--   same as any other JSON value, instead of interpreting it as
--   <a>Nothing</a>.
(.:!) :: FromJSON a => Object -> Key -> Parser (Maybe a)

-- | Helper for use in combination with <a>.:?</a> to provide default
--   values for optional JSON object fields.
--   
--   This combinator is most useful if the key and value can be absent from
--   an object without affecting its validity and we know a default value
--   to assign in that case. If the key and value are mandatory, use
--   <a>.:</a> instead.
--   
--   Example usage:
--   
--   <pre>
--   v1 &lt;- o <a>.:?</a> "opt_field_with_dfl" .!= "default_val"
--   v2 &lt;- o <a>.:</a>  "mandatory_field"
--   v3 &lt;- o <a>.:?</a> "opt_field2"
--   </pre>
(.!=) :: Parser (Maybe a) -> a -> Parser a

-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
--   duplicate keys arise, later keys and their associated values win.
object :: [Pair] -> Value

-- | Parse any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for <a>value</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith</a>.
json :: Parser Value

-- | Parse any JSON value.
--   
--   This is a strict version of <a>json</a> which avoids building up
--   thunks during parsing; it performs all conversions immediately. Prefer
--   this version if most of the JSON data needs to be accessed.
--   
--   This function is an alias for <a>value'</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith'</a>.
json' :: Parser Value
parseIndexedJSON :: (Value -> Parser a) -> Int -> Value -> Parser a
instance GHC.Show.Show Data.Aeson.AesonException
instance GHC.Exception.Type.Exception Data.Aeson.AesonException


-- | Functions to mechanically derive <a>JSONFun</a> and <a>FromJSON</a>
--   instances. Note that you need to enable the <tt>TemplateHaskell</tt>
--   language extension in order to use this module.
--   
--   An example shows how instances are generated for arbitrary data types.
--   First we define a data type:
--   
--   <pre>
--   data D a = Nullary
--            | Unary Int
--            | Product String Char a
--            | Record { testOne   :: Double
--                     , testTwo   :: Bool
--                     , testThree :: D a
--                     } deriving Eq
--   </pre>
--   
--   Next we derive the necessary instances. Note that we make use of the
--   feature to change record field names. In this case we drop the first 4
--   characters of every field name. We also modify constructor names by
--   lower-casing them:
--   
--   <pre>
--   $(<a>deriveJSON</a> <a>defaultOptions</a>{<a>fieldLabelModifier</a> = <a>drop</a> 4, <a>constructorTagModifier</a> = map toLower} ''D)
--   </pre>
--   
--   Now we can use the newly created instances.
--   
--   <pre>
--   d :: D <a>Int</a>
--   d = Record { testOne = 3.14159
--              , testTwo = <a>True</a>
--              , testThree = Product "test" 'A' 123
--              }
--   </pre>
--   
--   <pre>
--   fromJSON (toJSON d) == Success d
--   </pre>
--   
--   This also works for data family instances, but instead of passing in
--   the data family name (with double quotes), we pass in a data family
--   instance constructor (with a single quote):
--   
--   <pre>
--   data family DF a
--   data instance DF Int = DF1 Int
--                        | DF2 Int Int
--                        deriving Eq
--   
--   $(<a>deriveJSON</a> <a>defaultOptions</a> 'DF1)
--   -- Alternatively, one could pass 'DF2 instead
--   </pre>
--   
--   Please note that you can derive instances for tuples using the
--   following syntax:
--   
--   <pre>
--   -- FromJSON and ToJSON instances for 4-tuples.
--   $(<a>deriveJSON</a> <a>defaultOptions</a> ''(,,,))
--   </pre>
--   
--   If you derive <a>JSONFun</a> for a type that has no constructors, the
--   splice will require enabling <tt>EmptyCase</tt> to compile.
module Data.Aeson.TH

-- | Options that specify how to encode/decode your datatype to/from JSON.
--   
--   Options can be set using record syntax on <a>defaultOptions</a> with
--   the fields below.
data Options

-- | Specifies how to encode constructors of a sum datatype.
data SumEncoding

-- | A constructor will be encoded to an object with a field
--   <a>tagFieldName</a> which specifies the constructor tag (modified by
--   the <a>constructorTagModifier</a>). If the constructor is a record the
--   encoded record fields will be unpacked into this object. So make sure
--   that your record doesn't have a field with the same label as the
--   <a>tagFieldName</a>. Otherwise the tag gets overwritten by the encoded
--   value of that field! If the constructor is not a record the encoded
--   constructor contents will be stored under the <a>contentsFieldName</a>
--   field.
TaggedObject :: String -> String -> SumEncoding
[tagFieldName] :: SumEncoding -> String
[contentsFieldName] :: SumEncoding -> String

-- | Constructor names won't be encoded. Instead only the contents of the
--   constructor will be encoded as if the type had a single constructor.
--   JSON encodings have to be disjoint for decoding to work properly.
--   
--   When decoding, constructors are tried in the order of definition. If
--   some encodings overlap, the first one defined will succeed.
--   
--   <i>Note:</i> Nullary constructors are encoded as strings (using
--   <a>constructorTagModifier</a>). Having a nullary constructor alongside
--   a single field constructor that encodes to a string leads to
--   ambiguity.
--   
--   <i>Note:</i> Only the last error is kept when decoding, so in the case
--   of malformed JSON, only an error for the last constructor will be
--   reported.
UntaggedValue :: SumEncoding

-- | A constructor will be encoded to an object with a single field named
--   after the constructor tag (modified by the
--   <a>constructorTagModifier</a>) which maps to the encoded contents of
--   the constructor.
ObjectWithSingleField :: SumEncoding

-- | A constructor will be encoded to a 2-element array where the first
--   element is the tag of the constructor (modified by the
--   <a>constructorTagModifier</a>) and the second element the encoded
--   contents of the constructor.
TwoElemArray :: SumEncoding

-- | Default encoding <a>Options</a>:
--   
--   <pre>
--   <a>Options</a>
--   { <a>fieldLabelModifier</a>      = id
--   , <a>constructorTagModifier</a>  = id
--   , <a>allNullaryToStringTag</a>   = True
--   , <a>omitNothingFields</a>       = False
--   , <a>sumEncoding</a>             = <a>defaultTaggedObject</a>
--   , <a>unwrapUnaryRecords</a>      = False
--   , <a>tagSingleConstructors</a>   = False
--   , <a>rejectUnknownFields</a>     = False
--   }
--   </pre>
defaultOptions :: Options

-- | Default <a>TaggedObject</a> <a>SumEncoding</a> options:
--   
--   <pre>
--   defaultTaggedObject = <a>TaggedObject</a>
--                         { <a>tagFieldName</a>      = "tag"
--                         , <a>contentsFieldName</a> = "contents"
--                         }
--   </pre>
defaultTaggedObject :: SumEncoding

-- | Generates both <a>JSONFun</a> and <a>FromJSON</a> instance
--   declarations for the given data type or data family instance
--   constructor.
--   
--   This is a convenience function which is equivalent to calling both
--   <a>deriveToJSON</a> and <a>deriveFromJSON</a>.
deriveJSON :: Options -> Name -> Q [Dec]

-- | Generates both <a>ToJSON1</a> and <a>FromJSON1</a> instance
--   declarations for the given data type or data family instance
--   constructor.
--   
--   This is a convenience function which is equivalent to calling both
--   <a>deriveToJSON1</a> and <a>deriveFromJSON1</a>.
deriveJSON1 :: Options -> Name -> Q [Dec]

-- | Generates both <a>ToJSON2</a> and <a>FromJSON2</a> instance
--   declarations for the given data type or data family instance
--   constructor.
--   
--   This is a convenience function which is equivalent to calling both
--   <a>deriveToJSON2</a> and <a>deriveFromJSON2</a>.
deriveJSON2 :: Options -> Name -> Q [Dec]

-- | Generates a <a>JSONFun</a> instance declaration for the given data
--   type or data family instance constructor.
deriveToJSON :: Options -> Name -> Q [Dec]

-- | Generates a <a>ToJSON1</a> instance declaration for the given data
--   type or data family instance constructor.
deriveToJSON1 :: Options -> Name -> Q [Dec]

-- | Generates a <a>ToJSON2</a> instance declaration for the given data
--   type or data family instance constructor.
deriveToJSON2 :: Options -> Name -> Q [Dec]

-- | Generates a <a>FromJSON</a> instance declaration for the given data
--   type or data family instance constructor.
deriveFromJSON :: Options -> Name -> Q [Dec]

-- | Generates a <a>FromJSON1</a> instance declaration for the given data
--   type or data family instance constructor.
deriveFromJSON1 :: Options -> Name -> Q [Dec]

-- | Generates a <a>FromJSON2</a> instance declaration for the given data
--   type or data family instance constructor.
deriveFromJSON2 :: Options -> Name -> Q [Dec]

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a <a>ToJSONFun</a>.
mkToJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a <a>ToJSONFun</a> by using the
--   given encoding function on occurrences of the last type parameter.
mkLiftToJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a <a>ToJSONFun</a> by using the
--   given encoding functions on occurrences of the last two type
--   parameters.
mkLiftToJSON2 :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a JSON string.
mkToEncoding :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a JSON string by using the given
--   encoding function on occurrences of the last type parameter.
mkLiftToEncoding :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a JSON string by using the given
--   encoding functions on occurrences of the last two type parameters.
mkLiftToEncoding2 :: Options -> Name -> Q Exp

-- | Generates a lambda expression which parses the JSON encoding of the
--   given data type or data family instance constructor.
mkParseJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which parses the JSON encoding of the
--   given data type or data family instance constructor by using the given
--   parsing function on occurrences of the last type parameter.
mkLiftParseJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which parses the JSON encoding of the
--   given data type or data family instance constructor by using the given
--   parsing functions on occurrences of the last two type parameters.
mkLiftParseJSON2 :: Options -> Name -> Q Exp
instance GHC.Classes.Ord Data.Aeson.TH.Arity
instance GHC.Classes.Eq Data.Aeson.TH.Arity
instance GHC.Enum.Enum Data.Aeson.TH.Arity
instance GHC.Classes.Eq Data.Aeson.TH.StarKindStatus
instance Data.Aeson.TH.LookupField a
instance Data.Aeson.TH.LookupField (GHC.Maybe.Maybe a)


-- | Like <tt><a>Data.Aeson.QQ</a></tt> but without interpolation.
module Data.Aeson.QQ.Simple

-- | Converts a string representation of a JSON value into <a>Value</a> at
--   compile-time.
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   
--   import Data.Aeson (Value)
--   import Data.Aeson.QQ.Simple
--   
--   joe :: <a>Value</a>
--   joe = [aesonQQ|{ "name": "Joe", "age": 12 }|]
--   </pre>
aesonQQ :: QuasiQuoter


-- | Convertion to and from <tt>aeson</tt> <a>Value</a>.
module Data.Aeson.Decoding

-- | Efficiently deserialize a JSON value from a strict <a>ByteString</a>.
--   If this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
decode :: FromJSON a => ByteString -> Maybe a

-- | Like <a>decodeStrict</a> but returns an error message when decoding
--   fails.
eitherDecode :: FromJSON a => ByteString -> Either String a

-- | Like <a>decode</a> but throws an <a>AesonException</a> when decoding
--   fails.
throwDecode :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Efficiently deserialize a JSON value from a strict <a>ByteString</a>.
--   If this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
decodeStrict :: FromJSON a => ByteString -> Maybe a

-- | Like <a>decodeStrict</a> but returns an error message when decoding
--   fails.
eitherDecodeStrict :: FromJSON a => ByteString -> Either String a

-- | Like <a>decodeStrict</a> but throws an <a>AesonException</a> when
--   decoding fails.
throwDecodeStrict :: forall a m. (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Convert <a>Tokens</a> to <a>Value</a>.
toEitherValue :: Tokens k e -> Either e (Value, k)
