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


-- | Compatibility layer for aeson
--   
--   Compatibility layer for <tt>aeson</tt>
@package aeson-compat
@version 0.3.6


-- | Compatibility notices
--   
--   <ul>
--   <li><a>decode</a> etc. work as in <tt>aeson &gt;=0.9</tt></li>
--   <li>but it is generalised to work in any <a>MonadThrow</a> (that is
--   extra)</li>
--   <li><a>.:?</a> works as in <tt>aeson &lt;0.10</tt></li>
--   <li><a>.:!</a> works as <a>.:?</a> in <tt>aeson ==0.10</tt></li>
--   <li>Orphan instances <a>FromJSON</a> <tt>Day</tt> and <a>FromJSON</a>
--   <tt>LocalTime</tt> for <tt>aeson &lt;0.10</tt></li>
--   <li><a>Encoding</a> related functionality is not added. It's present
--   only with <tt>aeson &gt;=0.10</tt></li>
--   </ul>
module Data.Aeson.Compat

-- | Like original <a>decode</a> but in arbitrary <a>MonadThrow</a>.
--   
--   Parse a top-level JSON value, i.e. also strings, numbers etc.
decode :: (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Like original <a>decode'</a> but in arbitrary <a>MonadThrow</a>.
decode' :: (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Exception thrown by <a>decode</a> - family of functions in this
--   module.
newtype AesonException
AesonException :: String -> AesonException

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

-- | Like original <a>decodeStrict</a> but in arbitrary <a>MonadThrow</a>.
decodeStrict :: (FromJSON a, MonadThrow m) => ByteString -> m a

-- | Like original <a>decodeStrict'</a> but in arbitrary <a>MonadThrow</a>.
decodeStrict' :: (FromJSON a, MonadThrow m) => ByteString -> m 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

-- | An encoding of a JSON value.
data Encoding :: *

-- | Acquire the underlying bytestring builder.
fromEncoding :: Encoding -> 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:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--     parseJSON (<a>Object</a> v) = Coord    <a>&lt;$&gt;</a>
--                            v <tt>.:</tt> "x" <a>&lt;*&gt;</a>
--                            v <tt>.:</tt> "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.
--     parseJSON invalid    = <a>typeMismatch</a> "Coord" invalid
--   </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 will probably be more efficient than the
--   following two options:</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 FromJSON Coord
--   </pre>
--   
--   If <tt>DefaultSignatures</tt> doesn't give exactly the results you
--   want, you can customize the generic decoding with only a tiny amount
--   of effort, using <a>genericParseJSON</a> with your preferred
--   <a>Options</a>:
--   
--   <pre>
--   instance FromJSON Coord where
--       parseJSON = <a>genericParseJSON</a> <a>defaultOptions</a>
--   </pre>
class FromJSON a
parseJSON :: 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>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--     toJSON (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   
--     toEncoding (Coord x y) = <tt>pairs</tt> ("x" <a>.=</a> x <tt>&lt;&gt;</tt> "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 will probably be more efficient than the
--   following two options:</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 for your
--   datatype without giving definitions for <a>toJSON</a> or
--   <a>toEncoding</a>.
--   
--   For example, the previous example can be simplified to a more minimal
--   instance:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance ToJSON Coord where
--       toEncoding = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
--   
--   Why do we provide an implementation for <a>toEncoding</a> here? The
--   <a>toEncoding</a> function is a relatively new addition to this class.
--   To allow users of older versions of this library to upgrade without
--   having to edit all of their instances or encounter surprising
--   incompatibilities, the default implementation of <a>toEncoding</a>
--   uses <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>. Our one-liner
--   definition of <a>toEncoding</a> above bypasses the intermediate
--   <a>Value</a>.
--   
--   If <tt>DefaultSignatures</tt> doesn't give exactly the results you
--   want, you can customize the generic encoding with only a tiny amount
--   of effort, using <a>genericToJSON</a> and <a>genericToEncoding</a>
--   with your preferred <a>Options</a>:
--   
--   <pre>
--   instance ToJSON Coord where
--       toJSON     = <a>genericToJSON</a> <a>defaultOptions</a>
--       toEncoding = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
class ToJSON a

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: 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 ToJSON Coord where
--       toEncoding = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
toEncoding :: a -> Encoding

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

-- | Class of generic representation types (<a>Rep</a>) that can be
--   converted from JSON.
class GFromJSON (f :: * -> *)

-- | This method (applied to <a>defaultOptions</a>) is used as the default
--   generic implementation of <a>parseJSON</a>.
gParseJSON :: Options -> Value -> Parser (f a)

-- | Class of generic representation types (<a>Rep</a>) that can be
--   converted to JSON.
class GToJSON (f :: * -> *)

-- | This method (applied to <a>defaultOptions</a>) is used as the default
--   generic implementation of <a>toJSON</a>.
gToJSON :: Options -> f a -> Value

-- | Class of generic representation types (<a>Rep</a>) that can be
--   converted to a JSON <a>Encoding</a>.
class GToEncoding (f :: * -> *)

-- | This method (applied to <a>defaultOptions</a>) can be used as the
--   default generic implementation of <a>toEncoding</a>.
gToEncoding :: Options -> f a -> Encoding

-- | 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 (Rep a)) => Options -> 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, GToEncoding (Rep a)) => Options -> 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 (Rep a)) => Options -> Value -> Parser a

-- | 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
--   }
--   </pre>
defaultOptions :: Options

-- | <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>withText 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>withArray 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>withNumber 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.
withNumber :: String -> (Number -> Parser a) -> Value -> Parser a

-- | <tt>withScientific 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>withBool 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

-- | 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
--   <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 <a>.:</a> instead.
--   
--   This operator is consistent in <tt>aeson &gt;=0.7 &amp;&amp;
--   &lt;0.11</tt>
(.:?) :: (FromJSON a) => Object -> Text -> Parser (Maybe a)

-- | Like <a>.:?</a>, but the resulting parser will fail, if the key is
--   present but is <a>Null</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

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

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

-- | A JSON parser.
data Parser a :: * -> *
instance GHC.Show.Show Data.Aeson.Compat.AesonException
instance GHC.Exception.Exception Data.Aeson.Compat.AesonException
