-- 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 Data.Aeson
--   module below.
--   
--   For release notes, see
--   https://github.com/bos/aeson/blob/master/release-notes.markdown
--   
--   Parsing performance on a late 2010 MacBook Pro (2.66GHz Core i7), for
--   mostly-English tweets from Twitter's JSON search API:
--   
--   
--   
- 0.8 KB, 32-bit GHC 6.12.3: 30538 msg/sec (24.9 MB/sec)
--   
- 0.8 KB, 64-bit GHC 7.0.3: 31204 msg/sec (25.4 MB/sec)
--   
- 6.4 KB, 32-bit GHC 6.12.3: 6731 msg/sec (42.3 MB/sec)
--   
- 6.4 KB, 64-bit GHC 7.0.3: 6627 msg/sec (41.7 MB/sec)
--   
- 11.8 KB, 32-bit GHC 6.12.3: 3751 msg/sec (43.2 MB/sec)
--   
- 11.8 KB, 64-bit GHC 7.0.3: 3381 msg/sec (38.9 MB/sec)
--   
- 31.2 KB, 32-bit GHC 6.12.3: 1306 msg/sec (39.8 MB/sec)
--   
- 31.2 KB, 64-bit GHC 7.0.3: 1132 msg/sec (34.5 MB/sec)
--   
- 61.5 KB, 32-bit GHC 6.12.3: 616 msg/sec (37.0 MB/sec)
--   
- 61.5 KB, 64-bit GHC 7.0.3: 534 msg/sec (32.1 MB/sec)
--   
--   
--   Handling heavily-escaped text is a little more work. Here is parsing
--   performance with Japanese tweets, where much of the text is entirely
--   Unicode-escaped.
--   
--   
--   
- 14.6 KB, 32-bit GHC 6.12.3: 2315 msg/sec (33.1 MB/sec)
--   
- 14.6 KB, 64-bit GHC 7.0.3: 1986 msg/sec (28.4 MB/sec)
--   
- 44.1 KB, 32-bit GHC 6.12.3: 712 msg/sec (30.7 MB/sec)
--   
- 44.1 KB, 64-bit GHC 7.0.3: 634 msg/sec (27.3 MB/sec)
--   
- 82.9 KB, 32-bit GHC 6.12.3: 377 msg/sec (30.5 MB/sec)
--   
- 82.9 KB, 64-bit GHC 7.0.3: 332 msg/sec (26.9 MB/sec)
--   
--   
--   Encoding performance on the same machine and data:
--   
--   
--   
- English, 854 bytes: 43439 msg/sec (35.4 MB/sec)
--   
- English, 6.4 KB: 7127 msg/sec (44.8 MB/sec)
--   
- Engish, 61.5 KB: 765 msg/sec (46.0 MB/sec)
--   
- Japanese, 14.6 KB: 4727 msg/sec (67.5 MB/sec)
--   
- Japanese, 44.1 KB: 1505 msg/sec (64.8 MB/sec)
--   
--   
--   (A note on naming: in Greek mythology, Aeson was the father of Jason.)
@package aeson
@version 0.6.2.1

-- | 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 :: !Number -> Value
Bool :: !Bool -> Value
Null :: Value

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

-- | The empty array.
emptyArray :: Value

-- | A key/value pair for an Object.
type Pair = (Text, Value)

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

-- | The empty object.
emptyObject :: Value

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

-- | Fail parsing due to a type mismatch, with a descriptive message.
typeMismatch :: String -> Value -> Parser a

-- | A continuation-based parser type.
data Parser a

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

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   When writing an instance, use empty, mzero, or
--   fail to make a conversion fail, e.g. if an Object is
--   missing a required key, or the value is of the wrong type.
--   
--   An example type and instance:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--      parseJSON (Object v) = Coord    <$>
--                             v .: "x" <*>
--                             v .: "y"
--   
--   -- A non-Object value is of the wrong type, so use mzero to fail.
--      parseJSON _          = mzero
--   
--   
--   Note the use of the OverloadedStrings language extension
--   which enables Text values to be written as string literals.
--   
--   Instead of manually writing your FromJSON instance, there are
--   three options to do it automatically:
--   
--   
--   
- Data.Aeson.TH provides template-haskell functions which
--   will derive an instance at compile-time. The generated instance is
--   optimized for your type so will probably be more efficient than the
--   following two options:
--   
- Data.Aeson.Generic provides a generic fromJSON
--   function that parses to any type which is an instance of
--   Data.
--   
- If your compiler has support for the DeriveGeneric and
--   DefaultSignatures language extensions, parseJSON
--   will have a default generic implementation.
--   
--   
--   To use this, simply add a deriving Generic clause to
--   your datatype and declare a FromJSON instance for your
--   datatype without giving a definition for parseJSON.
--   
--   For example the previous example can be simplified to just:
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--   
--   
--   Note that, instead of using DefaultSignatures, it's also
--   possible to parameterize the generic decoding using
--   genericParseJSON applied to your encoding/decoding
--   Options:
--   
--   
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON defaultOptions
--   
class FromJSON a where parseJSON = genericParseJSON defaultOptions
parseJSON :: 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 Parser.
parse :: (a -> Parser b) -> a -> Result b

-- | Run a Parser with an Either result type.
parseEither :: (a -> Parser b) -> a -> Either String b

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

-- | A type that can be converted to JSON.
--   
--   An example type and instance:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--      toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--   
--   Note the use of the OverloadedStrings language extension
--   which enables Text values to be written as string literals.
--   
--   Instead of manually writing your ToJSON instance, there are
--   three options to do it automatically:
--   
--   
--   
- Data.Aeson.TH provides template-haskell functions which
--   will derive an instance at compile-time. The generated instance is
--   optimized for your type so will probably be more efficient than the
--   following two options:
--   
- Data.Aeson.Generic provides a generic toJSON
--   function that accepts any type which is an instance of
--   Data.
--   
- If your compiler has support for the DeriveGeneric and
--   DefaultSignatures language extensions (GHC 7.2 and newer),
--   toJSON will have a default generic implementation.
--   
--   
--   To use the latter option, simply add a deriving
--   Generic clause to your datatype and declare a
--   ToJSON instance for your datatype without giving a definition
--   for toJSON.
--   
--   For example the previous example can be simplified to just:
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord
--   
--   
--   Note that, instead of using DefaultSignatures, it's also
--   possible to parameterize the generic encoding using
--   genericToJSON applied to your encoding/decoding Options:
--   
--   
--   instance ToJSON Coord where
--       toJSON = genericToJSON defaultOptions
--   
class ToJSON a where toJSON = genericToJSON defaultOptions
toJSON :: ToJSON a => a -> Value

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

-- | Class of generic representation types (Rep) that can be
--   converted from JSON.
class GFromJSON f
gParseJSON :: GFromJSON f => Options -> Value -> Parser (f a)

-- | Class of generic representation types (Rep) that can be
--   converted to JSON.
class GToJSON f
gToJSON :: GToJSON f => Options -> f a -> Value

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

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

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

-- | withObject expected f value applies f to the
--   Text when value is a String and fails using
--   typeMismatch expected otherwise.
withText :: String -> (Text -> Parser a) -> Value -> Parser a

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

-- | withObject expected f value applies f to the
--   Number when value is a Number and fails using
--   typeMismatch expected otherwise.
withNumber :: String -> (Number -> Parser a) -> Value -> Parser a

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

-- | Construct a Pair from a key and a value.
(.=) :: ToJSON a => Text -> a -> Pair

-- | Retrieve the value associated with the given key of an Object.
--   The result is empty 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 must be
--   present in an object for it to be valid. If the key and value are
--   optional, use '(.:?)' instead.
(.:) :: FromJSON a => Object -> Text -> Parser a

-- | Retrieve the value associated with the given key of an Object.
--   The result is Nothing if the key is not present, or
--   empty 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 '(.:)' instead.
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)

-- | Helper for use in combination with .:? 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 '(.:)'
--   instead.
--   
--   Example usage:
--   
--   
--   v1 <- o .:? "opt_field_with_dfl" .!= "default_val"
--   v2 <- o .:  "mandatory_field"
--   v3 <- o .:? "opt_field2"
--   
(.!=) :: Parser (Maybe a) -> a -> Parser a

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

-- | Options that specify how to encode/decode your datatype to/from JSON.
data Options
Options :: (String -> String) -> (String -> String) -> Bool -> Bool -> SumEncoding -> 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 True the constructors of a datatype, with all nullary
--   constructors, will be encoded to just a string with the constructor
--   tag. If False the encoding will always follow the
--   sumEncoding.
allNullaryToStringTag :: Options -> Bool

-- | If True record fields with a Nothing value will be
--   omitted from the resulting object. If False the resulting
--   object will include those fields mapping to null.
omitNothingFields :: Options -> Bool

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

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

-- | A constructor will be encoded to an object with a field
--   tagFieldName which specifies the constructor tag (modified by
--   the constructorTagModifier). 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
--   tagFieldName. 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 contentsFieldName
--   field.
TaggedObject :: String -> String -> SumEncoding
tagFieldName :: SumEncoding -> String
contentsFieldName :: SumEncoding -> String

-- | A constructor will be encoded to an object with a single field named
--   after the constructor tag (modified by the
--   constructorTagModifier) 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
--   constructorTagModifier) and the second element the encoded
--   contents of the constructor.
TwoElemArray :: SumEncoding

-- | Default encoding Options:
--   
--   
--   Options
--   { fieldLabelModifier      = id
--   , constructorTagModifier  = id
--   , allNullaryToStringTag   = True
--   , omitNothingFields       = False
--   , sumEncoding             = defaultTaggedObject
--   }
--   
defaultOptions :: Options

-- | Default TaggedObject SumEncoding options:
--   
--   
--   defaultTaggedObject = TaggedObject
--                         { tagFieldName      = "tag"
--                         , contentsFieldName = "contents"
--                         }
--   
defaultTaggedObject :: SumEncoding

-- | Efficiently serialize a JSON value.
--   
--   Most frequently, you'll probably want to encode straight to UTF-8 (the
--   standard JSON encoding) using encode.
--   
--   You can convert a Builder (as returned by fromValue) to
--   a string using e.g. toLazyText.
module Data.Aeson.Encode

-- | Encode a JSON value to a Builder. You can convert this to a
--   string using e.g. toLazyText, or encode straight to UTF-8 (the
--   standard JSON encoding) using encode.
fromValue :: Value -> Builder

-- | Efficiently serialize a JSON value as a lazy ByteString.
encode :: ToJSON a => a -> ByteString

-- | 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:
--   
--   
--   
- 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.
--   
- Conversion of a JSON value to a Haskell value. This may be either
--   immediate (strict) or deferred (lazy); see below for details.
--   
--   
--   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. This must be either an object or an
--   array, per RFC 4627.
--   
--   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.
json :: Parser Value

-- | Parse any JSON value. You should usually json 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 eval 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 top-level JSON value. This must be either an object or an
--   array, per RFC 4627.
--   
--   This is a strict version of json 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.
json' :: Parser Value

-- | Strict version of value. See also json'.
value' :: Parser Value

-- | JSON handling using Generics.
--   
--   This is based on the Generic package originally written by
--   Lennart Augustsson.

-- | Deprecated: This module will be REMOVED in version 0.7.0.0.
--   Please switch to GHC generics or Data.Aeson.TH instead. These
--   alternatives are less buggy, faster, and more configurable. 
module Data.Aeson.Generic

-- | Efficiently deserialize a JSON value from a lazy ByteString. If
--   this fails due to incomplete or invalid input, Nothing is
--   returned.
--   
--   This function parses immediately, but defers conversion. See
--   json for details.
decode :: Data a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a lazy ByteString. If
--   this fails due to incomplete or invalid input, Nothing is
--   returned.
--   
--   This function parses and performs conversion immediately. See
--   json' for details.
decode' :: Data a => ByteString -> Maybe a

-- | Efficiently serialize a JSON value as a lazy ByteString.
encode :: Data a => a -> ByteString
fromJSON :: Data a => Value -> Result a
toJSON :: Data a => a -> Value

-- | 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 ByteString. If
--   this fails due to incomplete or invalid input, Nothing is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace. This restriction is necessary to ensure
--   that if data is being lazily read from a file handle, the file handle
--   will be closed in a timely fashion once the document has been parsed.
--   
--   This function parses immediately, but defers conversion. See
--   json for details.
decode :: FromJSON a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a lazy ByteString. If
--   this fails due to incomplete or invalid input, Nothing is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace. This restriction is necessary to ensure
--   that if data is being lazily read from a file handle, the file handle
--   will be closed in a timely fashion once the document has been parsed.
--   
--   This function parses and performs conversion immediately. See
--   json' for details.
decode' :: FromJSON a => ByteString -> Maybe a

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

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

-- | Efficiently serialize a JSON value as a lazy ByteString.
encode :: ToJSON a => a -> ByteString

-- | Efficiently deserialize a JSON value from a strict ByteString.
--   If this fails due to incomplete or invalid input, Nothing 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
--   json for details.
decodeStrict :: FromJSON a => ByteString -> Maybe a

-- | Efficiently deserialize a JSON value from a lazy ByteString. If
--   this fails due to incomplete or invalid input, Nothing 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
--   json' for details.
decodeStrict' :: FromJSON a => ByteString -> Maybe a

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

-- | Like decodeStrict' 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 :: !Number -> Value
Bool :: !Bool -> Value
Null :: Value

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

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

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

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   When writing an instance, use empty, mzero, or
--   fail to make a conversion fail, e.g. if an Object is
--   missing a required key, or the value is of the wrong type.
--   
--   An example type and instance:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--      parseJSON (Object v) = Coord    <$>
--                             v .: "x" <*>
--                             v .: "y"
--   
--   -- A non-Object value is of the wrong type, so use mzero to fail.
--      parseJSON _          = mzero
--   
--   
--   Note the use of the OverloadedStrings language extension
--   which enables Text values to be written as string literals.
--   
--   Instead of manually writing your FromJSON instance, there are
--   three options to do it automatically:
--   
--   
--   
- Data.Aeson.TH provides template-haskell functions which
--   will derive an instance at compile-time. The generated instance is
--   optimized for your type so will probably be more efficient than the
--   following two options:
--   
- Data.Aeson.Generic provides a generic fromJSON
--   function that parses to any type which is an instance of
--   Data.
--   
- If your compiler has support for the DeriveGeneric and
--   DefaultSignatures language extensions, parseJSON
--   will have a default generic implementation.
--   
--   
--   To use this, simply add a deriving Generic clause to
--   your datatype and declare a FromJSON instance for your
--   datatype without giving a definition for parseJSON.
--   
--   For example the previous example can be simplified to just:
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--   
--   
--   Note that, instead of using DefaultSignatures, it's also
--   possible to parameterize the generic decoding using
--   genericParseJSON applied to your encoding/decoding
--   Options:
--   
--   
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON defaultOptions
--   
class FromJSON a where parseJSON = genericParseJSON defaultOptions
parseJSON :: FromJSON a => Value -> Parser a

-- | The result of running a Parser.
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.
--   
--   An example type and instance:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--      toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--   
--   Note the use of the OverloadedStrings language extension
--   which enables Text values to be written as string literals.
--   
--   Instead of manually writing your ToJSON instance, there are
--   three options to do it automatically:
--   
--   
--   
- Data.Aeson.TH provides template-haskell functions which
--   will derive an instance at compile-time. The generated instance is
--   optimized for your type so will probably be more efficient than the
--   following two options:
--   
- Data.Aeson.Generic provides a generic toJSON
--   function that accepts any type which is an instance of
--   Data.
--   
- If your compiler has support for the DeriveGeneric and
--   DefaultSignatures language extensions (GHC 7.2 and newer),
--   toJSON will have a default generic implementation.
--   
--   
--   To use the latter option, simply add a deriving
--   Generic clause to your datatype and declare a
--   ToJSON instance for your datatype without giving a definition
--   for toJSON.
--   
--   For example the previous example can be simplified to just:
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord
--   
--   
--   Note that, instead of using DefaultSignatures, it's also
--   possible to parameterize the generic encoding using
--   genericToJSON applied to your encoding/decoding Options:
--   
--   
--   instance ToJSON Coord where
--       toJSON = genericToJSON defaultOptions
--   
class ToJSON a where toJSON = genericToJSON defaultOptions
toJSON :: ToJSON a => a -> Value

-- | Class of generic representation types (Rep) that can be
--   converted from JSON.
class GFromJSON f
gParseJSON :: GFromJSON f => Options -> Value -> Parser (f a)

-- | Class of generic representation types (Rep) that can be
--   converted to JSON.
class GToJSON f
gToJSON :: GToJSON f => Options -> f a -> Value

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

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

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

-- | withObject expected f value applies f to the
--   Text when value is a String and fails using
--   typeMismatch expected otherwise.
withText :: String -> (Text -> Parser a) -> Value -> Parser a

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

-- | withObject expected f value applies f to the
--   Number when value is a Number and fails using
--   typeMismatch expected otherwise.
withNumber :: String -> (Number -> Parser a) -> Value -> Parser a

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

-- | Construct a Pair from a key and a value.
(.=) :: ToJSON a => Text -> a -> Pair

-- | Retrieve the value associated with the given key of an Object.
--   The result is empty 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 must be
--   present in an object for it to be valid. If the key and value are
--   optional, use '(.:?)' instead.
(.:) :: FromJSON a => Object -> Text -> Parser a

-- | Retrieve the value associated with the given key of an Object.
--   The result is Nothing if the key is not present, or
--   empty 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 '(.:)' instead.
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)

-- | Helper for use in combination with .:? 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 '(.:)'
--   instead.
--   
--   Example usage:
--   
--   
--   v1 <- o .:? "opt_field_with_dfl" .!= "default_val"
--   v2 <- o .:  "mandatory_field"
--   v3 <- o .:? "opt_field2"
--   
(.!=) :: Parser (Maybe a) -> a -> Parser a

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

-- | Parse a top-level JSON value. This must be either an object or an
--   array, per RFC 4627.
--   
--   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.
json :: Parser Value

-- | Parse a top-level JSON value. This must be either an object or an
--   array, per RFC 4627.
--   
--   This is a strict version of json 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.
json' :: Parser Value

-- | Functions to mechanically derive ToJSON and FromJSON
--   instances. Note that you need to enable the TemplateHaskell
--   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:
--   
--   
--   data D a = Nullary
--            | Unary Int
--            | Product String Char a
--            | Record { testOne   :: Double
--                     , testTwo   :: Bool
--                     , testThree :: D a
--                     } deriving Eq
--   
--   
--   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:
--   
--   
--   $(deriveJSON defaultOptions{fieldLabelModifier = drop 4, constructorTagModifier = map toLower} ''D)
--   
--   
--   Now we can use the newly created instances.
--   
--   
--   d :: D Int
--   d = Record { testOne = 3.14159
--              , testTwo = True
--              , testThree = Product "test" 'A' 123
--              }
--   
--   
--   
--   >>> fromJSON (toJSON d) == Success d
--   > True
--   
--   
--   Please note that you can derive instances for tuples using the
--   following syntax:
--   
--   
--   -- FromJSON and ToJSON instances for 4-tuples.
--   $(deriveJSON defaultOptions ''(,,,))
--   
module Data.Aeson.TH

-- | Options that specify how to encode/decode your datatype to/from JSON.
data Options
Options :: (String -> String) -> (String -> String) -> Bool -> Bool -> SumEncoding -> 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 True the constructors of a datatype, with all nullary
--   constructors, will be encoded to just a string with the constructor
--   tag. If False the encoding will always follow the
--   sumEncoding.
allNullaryToStringTag :: Options -> Bool

-- | If True record fields with a Nothing value will be
--   omitted from the resulting object. If False the resulting
--   object will include those fields mapping to null.
omitNothingFields :: Options -> Bool

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

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

-- | A constructor will be encoded to an object with a field
--   tagFieldName which specifies the constructor tag (modified by
--   the constructorTagModifier). 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
--   tagFieldName. 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 contentsFieldName
--   field.
TaggedObject :: String -> String -> SumEncoding
tagFieldName :: SumEncoding -> String
contentsFieldName :: SumEncoding -> String

-- | A constructor will be encoded to an object with a single field named
--   after the constructor tag (modified by the
--   constructorTagModifier) 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
--   constructorTagModifier) and the second element the encoded
--   contents of the constructor.
TwoElemArray :: SumEncoding

-- | Default encoding Options:
--   
--   
--   Options
--   { fieldLabelModifier      = id
--   , constructorTagModifier  = id
--   , allNullaryToStringTag   = True
--   , omitNothingFields       = False
--   , sumEncoding             = defaultTaggedObject
--   }
--   
defaultOptions :: Options

-- | Default TaggedObject SumEncoding options:
--   
--   
--   defaultTaggedObject = TaggedObject
--                         { tagFieldName      = "tag"
--                         , contentsFieldName = "contents"
--                         }
--   
defaultTaggedObject :: SumEncoding

-- | Generates both ToJSON and FromJSON instance declarations
--   for the given data type.
--   
--   This is a convienience function which is equivalent to calling both
--   deriveToJSON and deriveFromJSON.
deriveJSON :: Options -> Name -> Q [Dec]

-- | Generates a ToJSON instance declaration for the given data
--   type.
deriveToJSON :: Options -> Name -> Q [Dec]

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

-- | Generates a lambda expression which encodes the given data type as
--   JSON.
mkToJSON :: Options -> Name -> Q Exp

-- | Generates a lambda expression which parses the JSON encoding of the
--   given data type.
mkParseJSON :: Options -> Name -> Q Exp
instance [incoherent] FromJSON a => LookupField (Maybe a)
instance [incoherent] FromJSON a => LookupField a
