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

-- | Compatibility layer for aeson
--   
--   Compatibility layer for aeson
@package aeson-compat
@version 0.3.9

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

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

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

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

-- | 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.
--   
--   This is implemented in terms of the ToJSON class's
--   toEncoding method.
encode :: ToJSON a => a -> ByteString

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

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

-- | Often used synonym for Encoding'.
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 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

-- | 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
--   Object could be missing a required key, an Array 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:
--   
--   
--   
- fail yields a custom error message: it is the recommended
--   way of reporting a failure;
--   
- empty (or mzero) is uninformative: use it when the
--   error is meant to be caught by some (<|>);
--   
- typeMismatch can be used to report a failure when the
--   encountered value is not of the expected JSON type; unexpected
--   is an appropriate alternative when more than one type may be expected,
--   or to keep the expected type implicit.
--   
--   
--   prependFailure (or modifyFailure) add more information
--   to a parser's error messages.
--   
--   An example type and instance using typeMismatch and
--   prependFailure:
--   
--   
--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--       parseJSON (Object v) = Coord
--           <$> v .: "x"
--           <*> v .: "y"
--   
--       -- We do not expect a non-Object value here.
--       -- We could use empty to fail, but typeMismatch
--       -- gives a much more informative error message.
--       parseJSON invalid    =
--           prependFailure "parsing Coord failed, "
--               (typeMismatch "Object" invalid)
--   
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions withObject, withScientific,
--   etc. are provided. Their use is to be preferred when possible, since
--   they are more terse. Using withObject, we can rewrite the above
--   instance (assuming the same language extension and data type) as:
--   
--   
--   instance FromJSON Coord where
--       parseJSON = withObject "Coord" $ \v -> Coord
--           <$> v .: "x"
--           <*> v .: "y"
--   
--   
--   Instead of manually writing your FromJSON instance, there are
--   two 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 it will probably be more efficient than the
--   following option.
--   
- The compiler can provide a default generic implementation for
--   parseJSON.
--   
--   
--   To use the second, 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 = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--   
--   
--   The default implementation will be equivalent to parseJSON =
--   genericParseJSON defaultOptions; if you need
--   different options, you can customize the generic decoding by defining:
--   
--   
--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON customOptions
--   
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
parseJSONList :: 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.
--   
--   Instances in general must specify toJSON and
--   should (but don't need to) specify toEncoding.
--   
--   An example type and instance:
--   
--   
--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--     toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--     toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)
--   
--   
--   Instead of manually writing your ToJSON instance, there are two
--   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 it will probably be more efficient than the
--   following option.
--   
- The compiler can provide a default generic implementation for
--   toJSON.
--   
--   
--   To use the second, simply add a deriving Generic
--   clause to your datatype and declare a ToJSON instance. If you
--   require nothing other than defaultOptions, it is sufficient to
--   write (and this is the only alternative where the default
--   toJSON implementation is sufficient):
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--   
--   
--   If on the other hand you wish to customize the generic decoding, you
--   have to implement both methods:
--   
--   
--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance ToJSON Coord where
--       toJSON     = genericToJSON customOptions
--       toEncoding = genericToEncoding customOptions
--   
--   
--   Previous versions of this library only had the toJSON method.
--   Adding toEncoding had two reasons:
--   
--   
--   
- toEncoding is more efficient for the common case that the output
--   of toJSON is directly serialized to a ByteString.
--   Further, expressing either method in terms of the other would be
--   non-optimal.
--   
- The choice of defaults allows a smooth transition for existing
--   users: Existing instances that do not define toEncoding still
--   compile and have the correct semantics. This is ensured by making the
--   default implementation of toEncoding use toJSON. This
--   produces correct results, but since it performs an intermediate
--   conversion to a Value, it will be less efficient than directly
--   emitting an Encoding. (this also means that specifying nothing
--   more than instance ToJSON Coord would be sufficient as a
--   generically decoding instance, but there probably exists no good
--   reason to not specify toEncoding in new instances.)
--   
class ToJSON a

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

-- | Encode a Haskell value as JSON.
--   
--   The default implementation of this method creates an intermediate
--   Value using toJSON. 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 must provide an
--   implementation for this method. The easiest way to do so is by having
--   your types implement Generic using the DeriveGeneric
--   extension, and then have GHC generate a method body as follows.
--   
--   
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--   
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
infixr 8 .=

-- | Class of generic representation types that can be converted from JSON.
class GFromJSON arity (f :: Type -> Type)
type GToJSON = GToJSON Value
type GToEncoding = GToJSON Encoding

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | 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.
--   
--   This operator is consistent in aeson >=0.7 &&
--   <0.11
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe 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 differs from .:? by attempting to parse Null the
--   same as any other JSON value, instead of interpreting it as
--   Nothing.
(.:!) :: 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 any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for value. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   
Warning
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see jsonWith.
json :: Parser Value

-- | Parse any JSON value.
--   
--   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.
--   
--   This function is an alias for value'. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   
Warning
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see jsonWith'.
json' :: Parser Value

-- | Parse any JSON value. Synonym of json.
value :: Parser Value

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

-- | A JSON parser. N.B. This might not fit your usual understanding of
--   "parser". Instead you might like to think of Parser as a "parse
--   result", i.e. a parser to which the input has already been applied.
data Parser a
instance GHC.Show.Show Data.Aeson.Compat.AesonException
instance GHC.Exception.Type.Exception Data.Aeson.Compat.AesonException
