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


-- | 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 <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 <tt>System.DateTime</tt>
--   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
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 <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.
--   
--   When writing an instance, use <a>empty</a>, <tt>mzero</tt>, or
--   <a>fail</a> to make a conversion fail, e.g. if an <a>Object</a> is
--   missing a required key, or the value is of the wrong type.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--      parseJSON (<a>Object</a> v) = Coord    <a>&lt;$&gt;</a>
--                             v <a>.:</a> "x" <a>&lt;*&gt;</a>
--                             v <a>.:</a> "y"
--   
--   -- A non-<a>Object</a> value is of the wrong type, so use <tt>mzero</tt> to fail.
--      parseJSON _          = <tt>mzero</tt>
--   </pre>
--   
--   Note the use of the <tt>OverloadedStrings</tt> language extension
--   which enables <a>Text</a> values to be written as string literals.
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   three 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 will probably be more efficient than the
--   following two options:</li>
--   <li><a>Data.Aeson.Generic</a> provides a generic <tt>fromJSON</tt>
--   function that parses to any type which is an instance of
--   <tt>Data</tt>.</li>
--   <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
--   <tt>DefaultSignatures</tt> language extensions, <tt>parseJSON</tt>
--   will have a default generic implementation.</li>
--   </ul>
--   
--   To use this, simply add a <tt>deriving <a>Generic</a></tt> clause to
--   your datatype and declare a <tt>FromJSON</tt> instance for your
--   datatype without giving a definition for <tt>parseJSON</tt>.
--   
--   For example the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--   </pre>
class FromJSON a where parseJSON = fmap to . gParseJSON
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 <a>Parser</a>.
parse :: (a -> Parser b) -> a -> Result b

-- | Run a <a>Parser</a> with an <a>Either</a> result type.
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.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--      toJSON (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   </pre>
--   
--   Note the use of the <tt>OverloadedStrings</tt> language extension
--   which enables <a>Text</a> values to be written as string literals.
--   
--   Instead of manually writing your <a>ToJSON</a> instance, there are
--   three 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 will probably be more efficient than the
--   following two options:</li>
--   <li><a>Data.Aeson.Generic</a> provides a generic <tt>toJSON</tt>
--   function that accepts any type which is an instance of
--   <tt>Data</tt>.</li>
--   <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
--   <tt>DefaultSignatures</tt> language extensions (GHC 7.2 and newer),
--   <tt>toJSON</tt> will have a default generic implementation.</li>
--   </ul>
--   
--   To use the latter option, simply add a <tt>deriving
--   <a>Generic</a></tt> clause to your datatype and declare a
--   <tt>ToJSON</tt> instance for your datatype without giving a definition
--   for <tt>toJSON</tt>.
--   
--   For example the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord
--   </pre>
class ToJSON a where toJSON = gToJSON . from
toJSON :: ToJSON a => a -> Value

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

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

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

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

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

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

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>empty</a> 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 '(.:?)' 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
--   <a>empty</a> 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 <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 '(.:)'
--   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


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

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

-- | Efficiently serialize a JSON value as a lazy <a>ByteString</a>.
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:
--   
--   <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. 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 <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 top-level JSON value. This must be either an object or an
--   array, per RFC 4627.
--   
--   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.
json' :: Parser Value

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


-- | JSON handling using <a>Generics</a>.
--   
--   This is based on the <a>Generic</a> package originally written by
--   Lennart Augustsson.
module Data.Aeson.Generic

-- | 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.
--   
--   This function parses immediately, but defers conversion. See
--   <a>json</a> for details.
decode :: Data 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.
--   
--   This function parses and performs conversion immediately. See
--   <a>json'</a> for details.
decode' :: Data a => ByteString -> Maybe a

-- | Efficiently serialize a JSON value as a lazy <a>ByteString</a>.
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 <a>ByteString</a>. If
--   this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   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.
--   
--   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>.
encode :: ToJSON a => a -> ByteString

-- | 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 <a>UTCTime</a> that uses the same non-standard
--   serialization format as Microsoft .NET, whose <tt>System.DateTime</tt>
--   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
fromDotNetTime :: DotNetTime -> UTCTime

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   When writing an instance, use <a>empty</a>, <tt>mzero</tt>, or
--   <a>fail</a> to make a conversion fail, e.g. if an <a>Object</a> is
--   missing a required key, or the value is of the wrong type.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--      parseJSON (<a>Object</a> v) = Coord    <a>&lt;$&gt;</a>
--                             v <a>.:</a> "x" <a>&lt;*&gt;</a>
--                             v <a>.:</a> "y"
--   
--   -- A non-<a>Object</a> value is of the wrong type, so use <tt>mzero</tt> to fail.
--      parseJSON _          = <tt>mzero</tt>
--   </pre>
--   
--   Note the use of the <tt>OverloadedStrings</tt> language extension
--   which enables <a>Text</a> values to be written as string literals.
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   three 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 will probably be more efficient than the
--   following two options:</li>
--   <li><a>Data.Aeson.Generic</a> provides a generic <tt>fromJSON</tt>
--   function that parses to any type which is an instance of
--   <tt>Data</tt>.</li>
--   <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
--   <tt>DefaultSignatures</tt> language extensions, <tt>parseJSON</tt>
--   will have a default generic implementation.</li>
--   </ul>
--   
--   To use this, simply add a <tt>deriving <a>Generic</a></tt> clause to
--   your datatype and declare a <tt>FromJSON</tt> instance for your
--   datatype without giving a definition for <tt>parseJSON</tt>.
--   
--   For example the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--   </pre>
class FromJSON a where parseJSON = fmap to . gParseJSON
parseJSON :: 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.
--   
--   An example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--      toJSON (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   </pre>
--   
--   Note the use of the <tt>OverloadedStrings</tt> language extension
--   which enables <a>Text</a> values to be written as string literals.
--   
--   Instead of manually writing your <a>ToJSON</a> instance, there are
--   three 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 will probably be more efficient than the
--   following two options:</li>
--   <li><a>Data.Aeson.Generic</a> provides a generic <tt>toJSON</tt>
--   function that accepts any type which is an instance of
--   <tt>Data</tt>.</li>
--   <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
--   <tt>DefaultSignatures</tt> language extensions (GHC 7.2 and newer),
--   <tt>toJSON</tt> will have a default generic implementation.</li>
--   </ul>
--   
--   To use the latter option, simply add a <tt>deriving
--   <a>Generic</a></tt> clause to your datatype and declare a
--   <tt>ToJSON</tt> instance for your datatype without giving a definition
--   for <tt>toJSON</tt>.
--   
--   For example the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord
--   </pre>
class ToJSON a where toJSON = gToJSON . from
toJSON :: ToJSON a => a -> Value

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

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

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

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

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

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

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>empty</a> 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 '(.:?)' 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
--   <a>empty</a> 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 <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 '(.:)'
--   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. 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 <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.
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.
--   
--   <pre>
--   $(<a>deriveJSON</a> (<tt>drop</tt> 4) ''D)
--   </pre>
--   
--   This will result in the following (simplified) code to be spliced in
--   your program:
--   
--   <pre>
--   import Control.Applicative
--   import Control.Monad
--   import Data.Aeson
--   import Data.Aeson.TH
--   import qualified Data.HashMap.Strict as H
--   import qualified Data.Text as T
--   import qualified Data.Vector as V
--   
--   instance <a>ToJSON</a> a =&gt; <a>ToJSON</a> (D a) where
--       <a>toJSON</a> =
--         \value -&gt;
--           case value of
--             Nullary -&gt;
--                 <a>object</a> [T.pack "Nullary" .= <a>toJSON</a> ([] :: [()])]
--             Unary arg1 -&gt;
--                 <a>object</a> [T.pack "Unary" .= <a>toJSON</a> arg1]
--             Product arg1 arg2 arg3 -&gt;
--                 <a>object</a> [ T.pack "Product"
--                          .= (<a>Array</a> $ <a>create</a> $ do
--                                mv &lt;- <a>unsafeNew</a> 3
--                                <a>unsafeWrite</a> mv 0 (<a>toJSON</a> arg1)
--                                <a>unsafeWrite</a> mv 1 (<a>toJSON</a> arg2)
--                                <a>unsafeWrite</a> mv 2 (<a>toJSON</a> arg3)
--                                return mv)
--                        ]
--             Record arg1 arg2 arg3 -&gt;
--                 <a>object</a> [ T.pack "Record"
--                          .= <a>object</a> [ T.pack "One"   <a>.=</a> arg1
--                                    , T.pack "Two"   <a>.=</a> arg2
--                                    , T.pack "Three" <a>.=</a> arg3
--                                    ]
--                        ]
--   </pre>
--   
--   <pre>
--   instance <a>FromJSON</a> a =&gt; <a>FromJSON</a> (D a) where
--       <a>parseJSON</a> =
--         \value -&gt;
--           case value of
--             <a>Object</a> obj -&gt;
--               case H.toList obj of
--                 [(conKey, conVal)] -&gt;
--                   case conKey of
--                     _ | conKey == T.pack "Nullary" -&gt;
--                           case conVal of
--                             <a>Array</a> arr -&gt;
--                               if V.null arr
--                               then pure Nullary
--                               else fail "&lt;error message&gt;"
--                             _ -&gt; fail "&lt;error message&gt;"
--                       | conKey == T.pack "Unary" -&gt;
--                           case conVal of
--                             arg -&gt; Unary &lt;$&gt; parseJSON arg
--                       | conKey == T.pack "Product" -&gt;
--                           case conVal of
--                             <a>Array</a> arr -&gt;
--                               if V.length arr == 3
--                               then Product &lt;$&gt; <a>parseJSON</a> (arr <a>unsafeIndex</a> 0)
--                                            &lt;*&gt; <a>parseJSON</a> (arr <a>unsafeIndex</a> 1)
--                                            &lt;*&gt; <a>parseJSON</a> (arr <a>unsafeIndex</a> 2)
--                               else fail "&lt;error message&gt;"
--                             _ -&gt; fail "&lt;error message&gt;"
--                       | conKey == T.pack "Record" -&gt;
--                           case conVal of
--                             <a>Object</a> recObj -&gt;
--                               if H.size recObj == 3
--                               then Record &lt;$&gt; recObj <tt>.:</tt> T.pack "One"
--                                           &lt;*&gt; recObj <tt>.:</tt> T.pack "Two"
--                                           &lt;*&gt; recObj <tt>.:</tt> T.pack "Three"
--                               else fail "&lt;error message&gt;"
--                             _ -&gt; fail "&lt;error message&gt;"
--                       | otherwise -&gt; fail "&lt;error message&gt;"
--                 _ -&gt; fail "&lt;error message&gt;"
--             _ -&gt; fail "&lt;error message&gt;"
--   </pre>
--   
--   Note that every "&lt;error message&gt;" is in fact a descriptive
--   message which provides as much information as is reasonable about the
--   failed parse.
--   
--   Now we can use the newly created instances.
--   
--   <pre>
--   d :: D <tt>Int</tt>
--   d = Record { testOne = 3.14159
--              , testTwo = <tt>True</tt>
--              , testThree = Product "test" 'A' 123
--              }
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromJSON (toJSON d) == Success d
--   &gt; True
--   </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> id ''(,,,))
--   </pre>
module Data.Aeson.TH

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

-- | Generates a <a>ToJSON</a> instance declaration for the given data
--   type.
--   
--   Example:
--   
--   <pre>
--   data Foo = Foo <tt>Char</tt> <tt>Int</tt>
--   $(<a>deriveToJSON</a> <a>id</a> ''Foo)
--   </pre>
--   
--   This will splice in the following code:
--   
--   <pre>
--   instance <a>ToJSON</a> Foo where
--        <a>toJSON</a> =
--            \value -&gt; case value of
--                        Foo arg1 arg2 -&gt; <a>Array</a> $ <a>create</a> $ do
--                          mv &lt;- <a>unsafeNew</a> 2
--                          <a>unsafeWrite</a> mv 0 (<a>toJSON</a> arg1)
--                          <a>unsafeWrite</a> mv 1 (<a>toJSON</a> arg2)
--                          return mv
--   </pre>
deriveToJSON :: (String -> String) -> Name -> Q [Dec]

-- | Generates a <a>FromJSON</a> instance declaration for the given data
--   type.
--   
--   Example:
--   
--   <pre>
--   data Foo = Foo Char Int
--   $(<a>deriveFromJSON</a> id ''Foo)
--   </pre>
--   
--   This will splice in the following code:
--   
--   <pre>
--   instance <a>FromJSON</a> Foo where
--       <a>parseJSON</a> =
--           \value -&gt; case value of
--                       <a>Array</a> arr -&gt;
--                         if (V.length arr == 2)
--                         then Foo &lt;$&gt; <a>parseJSON</a> (arr <a>unsafeIndex</a> 0)
--                                  &lt;*&gt; <a>parseJSON</a> (arr <a>unsafeIndex</a> 1)
--                         else fail "&lt;error message&gt;"
--                       other -&gt; fail "&lt;error message&gt;"
--   </pre>
deriveFromJSON :: (String -> String) -> Name -> Q [Dec]

-- | Generates a lambda expression which encodes the given data type as
--   JSON.
--   
--   Example:
--   
--   <pre>
--   data Foo = Foo Int
--   </pre>
--   
--   <pre>
--   encodeFoo :: Foo -&gt; <a>Value</a>
--   encodeFoo = $(<a>mkToJSON</a> id ''Foo)
--   </pre>
--   
--   This will splice in the following code:
--   
--   <pre>
--   \value -&gt; case value of Foo arg1 -&gt; <a>toJSON</a> arg1
--   </pre>
mkToJSON :: (String -> String) -> Name -> Q Exp

-- | Generates a lambda expression which parses the JSON encoding of the
--   given data type.
--   
--   Example:
--   
--   <pre>
--   data Foo = Foo <tt>Int</tt>
--   </pre>
--   
--   <pre>
--   parseFoo :: <a>Value</a> -&gt; <a>Parser</a> Foo
--   parseFoo = $(<a>mkParseJSON</a> id ''Foo)
--   </pre>
--   
--   This will splice in the following code:
--   
--   <pre>
--   \value -&gt; case value of arg -&gt; Foo &lt;$&gt; <a>parseJSON</a> arg
--   </pre>
mkParseJSON :: (String -> String) -> Name -> Q Exp
