-- 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.
--   
--   Parsing performance on a late 2013 MacBook Pro (2.6GHz Core i7),
--   running 64-bit GHC 7.10.1, for mostly-English tweets from Twitter's
--   JSON search API:
--   
--   <ul>
--   <li>6.4 KB payloads, English: 7570 msg/sec (47.6 MB/sec)</li>
--   <li>14.6 KB payloads, Japanese: 3261 msg/sec (46.6 MB/sec)</li>
--   </ul>
--   
--   Encoding performance on the same machine and data:
--   
--   <ul>
--   <li>6.4 KB payloads, English: 22738 msg/sec (142.9 MB/sec)</li>
--   <li>14.6 KB payloads, Japanese: 15911 msg/sec (227.4 MB/sec)</li>
--   </ul>
--   
--   (A note on naming: in Greek mythology, Aeson was the father of Jason.)
@package aeson
@version 1.2.3.0


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

-- | Parse a top-level 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.
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. You should usually <a>json</a> in preference to
--   this function, as this function relaxes the object-or-array
--   requirement of RFC 4627.
--   
--   In particular, be careful in using this function if you think your
--   code might interoperate with Javascript. A naïve Javascript library
--   that parses JSON data using <tt>eval</tt> is vulnerable to attack
--   unless the encoded data represents an object or an array. JSON
--   implementations in other languages conform to that same restriction to
--   preserve interoperability and security.
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 a top-level 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.
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>value</a>. See also <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


-- | 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 a top-level 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.
json :: Parser Value

-- | Parse any JSON value. You should usually <a>json</a> in preference to
--   this function, as this function relaxes the object-or-array
--   requirement of RFC 4627.
--   
--   In particular, be careful in using this function if you think your
--   code might interoperate with Javascript. A naïve Javascript library
--   that parses JSON data using <tt>eval</tt> is vulnerable to attack
--   unless the encoded data represents an object or an array. JSON
--   implementations in other languages conform to that same restriction to
--   preserve interoperability and security.
value :: Parser Value

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

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

-- | Parse a top-level 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.
json' :: Parser Value

-- | Strict version of <a>value</a>. See also <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


-- | Internal types and functions.
--   
--   <b>Note</b>: all declarations in this module are unstable, and prone
--   to being changed at any time.
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 :: Text -> 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 '(.:)' 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


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
fromPico :: Pico -> Integer
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>Value</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 :: Text -> Encoding -> Series
pairStr :: String -> Encoding -> Series
pair' :: Encoding' Text -> Encoding -> Series
nullEncoding :: Encoding' a -> Bool
emptyArray_ :: Encoding
emptyObject_ :: Encoding
wrapObject :: Encoding' a -> Encoding
wrapArray :: Encoding' a -> Encoding
null_ :: Encoding
bool :: Bool -> Encoding
text :: Text -> Encoding' a
lazyText :: Text -> Encoding' a
string :: String -> Encoding' a
list :: (a -> Encoding) -> [a] -> Encoding

-- | Encode as JSON object
dict :: (k -> Encoding' Text) -> (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
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
doubleText :: Double -> Encoding' a
scientificText :: Scientific -> Encoding' a
day :: Day -> 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 Data.Semigroup.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>Value</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 :: Text -> Encoding -> Series
pairStr :: String -> Encoding -> Series
pair' :: Encoding' Text -> Encoding -> Series
nullEncoding :: Encoding' a -> Bool
emptyArray_ :: Encoding
emptyObject_ :: Encoding
text :: Text -> Encoding' a
lazyText :: Text -> Encoding' a
string :: String -> Encoding' a
list :: (a -> Encoding) -> [a] -> Encoding

-- | Encode as JSON object
dict :: (k -> Encoding' Text) -> (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
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
doubleText :: Double -> Encoding' a
scientificText :: Scientific -> Encoding' a
day :: Day -> 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

-- | 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 = (Text, Value)

-- | A JSON "object" (key/value map).
type Object = HashMap Text 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.
--   
--   Example usage:
--   
--   <pre>
--   instance FromJSON Coord where
--     parseJSON (<a>Object</a> v) = {- type matches, life is good -}
--     parseJSON wat        = <a>typeMismatch</a> "Coord" wat
--   </pre>
typeMismatch :: String -> Value -> Parser a

-- | A JSON parser.
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><tt>empty</tt> and <tt>mzero</tt> work, but are terse and
--   uninformative;</li>
--   <li><a>fail</a> yields a custom error message;</li>
--   <li><a>typeMismatch</a> produces an informative message for cases when
--   the value encountered is not of the expected type.</li>
--   </ul>
--   
--   An example type and instance using <a>typeMismatch</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 <tt>mzero</tt> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    = <a>typeMismatch</a> "Coord" invalid
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withNumber</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>
--   
--   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

-- | 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>
--   
--   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 to reasons:
--   
--   <ol>
--   <li>toEncoding 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) => Text -> v -> kv

-- | 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

-- | 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

-- | 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, in this example, <a>ToJSONKeyText</a> will be used instead of
--   <a>ToJSONKeyValue</a>. 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>String</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>String</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>String</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 -> Text) -> !(a -> Encoding' Text) -> 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

-- | 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>
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>String</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>String</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

-- | uses <a>coerce</a> (<a>unsafeCoerce</a> in older GHCs)
FromJSONKeyCoerce :: !(CoerceText a) -> FromJSONKeyFunction a

-- | conversion from <a>Text</a> that always succeeds
FromJSONKeyText :: !(Text -> a) -> FromJSONKeyFunction a

-- | conversion from <a>Text</a> that may fail
FromJSONKeyTextParser :: !(Text -> Parser a) -> FromJSONKeyFunction a

-- | conversion for non-textual keys
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 unconstrainted 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

-- | 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>
--   
--   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 = 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

-- | This method (applied to <a>defaultOptions</a>) is used as the default
--   generic implementation of <a>parseJSON</a> (if the <tt>arity</tt> is
--   <a>Zero</a>) or <a>liftParseJSON</a> (if the <tt>arity</tt> is
--   <a>One</a>).
gParseJSON :: GFromJSON arity f => Options -> FromArgs arity a -> Value -> Parser (f a)

-- | 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
[NoFromArgs] :: FromArgs Zero a
[From1Args] :: (Value -> Parser a) -> (Value -> Parser [a]) -> FromArgs One a
type GToJSON = GToJSON Value
type GToEncoding = GToJSON Encoding

-- | 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
[NoToArgs] :: ToArgs res Zero a
[To1Args] :: (a -> res) -> ([a] -> res) -> ToArgs res One 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> expected f value</tt> applies <tt>f</tt> to the
--   <a>Object</a> when <tt>value</tt> is an <a>Object</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withObject :: String -> (Object -> Parser a) -> Value -> Parser a

-- | <tt><a>withText</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Text</a> when <tt>value</tt> is a <a>String</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
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 using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withArray :: String -> (Array -> Parser a) -> Value -> Parser a

-- | <tt><a>withNumber</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Number</a> when <tt>value</tt> is a <a>Number</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.

-- | <i>Deprecated: Use withScientific instead</i>
withNumber :: String -> (Number -> Parser a) -> Value -> Parser a

-- | <tt><a>withScientific</a> expected 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 <tt><a>typeMismatch</a> expected</tt> otherwise.
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a

-- | <tt><a>withBool</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Bool</a> when <tt>value</tt> is a <a>Bool</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: (FromJSON a) => 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 -> Text -> 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 -> Text -> 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 -> Text -> 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, earlier keys and their associated values win.
object :: [Pair] -> Value

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

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

-- | Function variant of <a>.:!</a>.
parseFieldMaybe' :: (FromJSON a) => Object -> Text -> 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 -> Text -> Parser a

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

-- | Variant of <a>.:!</a> with explicit parser function.
explicitParseFieldMaybe' :: (Value -> Parser a) -> Object -> Text -> 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>String</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>.
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

-- | 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
--   }
--   </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


-- | 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>encodeToBuilder</tt> 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 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 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

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

-- | Like <a>decodeStrict'</a> but returns an error message when decoding
--   fails.
eitherDecodeStrict' :: (FromJSON a) => ByteString -> Either String 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 = HashMap Text 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

-- | 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><tt>empty</tt> and <tt>mzero</tt> work, but are terse and
--   uninformative;</li>
--   <li><a>fail</a> yields a custom error message;</li>
--   <li><a>typeMismatch</a> produces an informative message for cases when
--   the value encountered is not of the expected type.</li>
--   </ul>
--   
--   An example type and instance using <a>typeMismatch</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 <tt>mzero</tt> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    = <a>typeMismatch</a> "Coord" invalid
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withNumber</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>
--   
--   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>
--   
--   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 to reasons:
--   
--   <ol>
--   <li>toEncoding 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) => Text -> v -> kv

-- | 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, in this example, <a>ToJSONKeyText</a> will be used instead of
--   <a>ToJSONKeyValue</a>. 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>String</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>String</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>String</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 -> Text) -> !(a -> Encoding' Text) -> 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>
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>String</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>String</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

-- | uses <a>coerce</a> (<a>unsafeCoerce</a> in older GHCs)
FromJSONKeyCoerce :: !(CoerceText a) -> FromJSONKeyFunction a

-- | conversion from <a>Text</a> that always succeeds
FromJSONKeyText :: !(Text -> a) -> FromJSONKeyFunction a

-- | conversion from <a>Text</a> that may fail
FromJSONKeyTextParser :: !(Text -> Parser a) -> FromJSONKeyFunction a

-- | conversion for non-textual keys
FromJSONKeyValue :: !(Value -> Parser a) -> 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>
--   
--   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 = 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

-- | This method (applied to <a>defaultOptions</a>) is used as the default
--   generic implementation of <a>parseJSON</a> (if the <tt>arity</tt> is
--   <a>Zero</a>) or <a>liftParseJSON</a> (if the <tt>arity</tt> is
--   <a>One</a>).
gParseJSON :: GFromJSON arity f => Options -> FromArgs arity a -> Value -> Parser (f a)

-- | 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
[NoFromArgs] :: FromArgs Zero a
[From1Args] :: (Value -> Parser a) -> (Value -> Parser [a]) -> FromArgs One a
type GToJSON = GToJSON Value
type GToEncoding = GToJSON Encoding

-- | 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
[NoToArgs] :: ToArgs res Zero a
[To1Args] :: (a -> res) -> ([a] -> res) -> ToArgs res One 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
--   }
--   </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>.
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

-- | 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

-- | <tt><a>withObject</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Object</a> when <tt>value</tt> is an <a>Object</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withObject :: String -> (Object -> Parser a) -> Value -> Parser a

-- | <tt><a>withText</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Text</a> when <tt>value</tt> is a <a>String</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
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 using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withArray :: String -> (Array -> Parser a) -> Value -> Parser a

-- | <tt><a>withNumber</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Number</a> when <tt>value</tt> is a <a>Number</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.

-- | <i>Deprecated: Use withScientific instead</i>
withNumber :: String -> (Number -> Parser a) -> Value -> Parser a

-- | <tt><a>withScientific</a> expected 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 <tt><a>typeMismatch</a> expected</tt> otherwise.
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a

-- | <tt><a>withBool</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Bool</a> when <tt>value</tt> is a <a>Bool</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: (FromJSON a) => 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 -> Text -> 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 -> Text -> 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 -> Text -> 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, earlier keys and their associated values win.
object :: [Pair] -> Value

-- | Parse a top-level 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.
json :: Parser Value

-- | Parse a top-level 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.
json' :: Parser Value


-- | Functions to mechanically derive <a>ToJSON</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>
--   &gt;&gt;&gt; fromJSON (toJSON d) == Success d
--   &gt; True
--   </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>
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
--   }
--   </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>ToJSON</a> and <a>FromJSON</a> instance declarations
--   for the given data type or data family instance constructor.
--   
--   This is a convienience 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 convienience 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 convienience function which is equivalent to calling both
--   <a>deriveToJSON2</a> and <a>deriveFromJSON2</a>.
deriveJSON2 :: Options -> Name -> Q [Dec]

-- | Generates a <a>ToJSON</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>Value</a>.
mkToJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which encodes the given data type or
--   data family instance constructor as a <a>Value</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>Value</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.Eq Data.Aeson.TH.StarKindStatus
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 Data.Aeson.TH.LookupField a
instance Data.Aeson.TH.LookupField (GHC.Base.Maybe a)
instance Data.Aeson.TH.LookupField (Data.Semigroup.Option a)


-- | This module is left to supply limited backwards-compatibility.

-- | <i>Deprecated: Use Data.Aeson or Data.Aeson.Text instead</i>
module Data.Aeson.Encode
encode :: ToJSON a => a -> ByteString
encodeToTextBuilder :: Value -> Builder
