Portability | portable |
---|---|
Stability | experimental |
Maintainer | Bryan O'Sullivan <bos@mailrank.com> |
Types and functions for working efficiently with JSON data.
(A note on naming: in Greek mythology, Aeson was the father of Jason.)
- data Value
- type Array = Vector Value
- type Object = Map Text Value
- newtype DotNetTime = DotNetTime {}
- class FromJSON a where
- data Result a
- fromJSON :: FromJSON a => Value -> Result a
- class ToJSON a where
- (.=) :: ToJSON a => Text -> a -> Pair
- (.:) :: FromJSON a => Object -> Text -> Parser a
- (.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)
- object :: [Pair] -> Value
- encode :: ToJSON a => a -> ByteString
- json :: Parser Value
Core JSON types
A JSON value represented as a Haskell value.
Convenience types
newtype DotNetTime Source
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.
Type conversion
A type that can be converted from JSON, with the possibility of failure.
When writing an instance, use 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:
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 usemzero
to fail. parseJSON _ =mzero
The result of running a Parser
.
fromJSON :: FromJSON a => Value -> Result aSource
Convert a value from JSON, failing if the types do not match.
A type that can be converted to JSON.
An example type and instance:
data Coord { x :: Double, y :: Double } instance ToJSON Coord where toJSON (Coord x y) =object
["x".=
x, "y".=
y]
Constructors and accessors
(.:) :: FromJSON a => Object -> Text -> Parser aSource
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 (Maybe a)Source
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.
Encoding and parsing
encode :: ToJSON a => a -> ByteStringSource
Efficiently serialize a JSON value as a lazy ByteString
.