yesod-core-1.2.0.4: Creation of type-safe, RESTful web applications.

Safe Haskell | None

Yesod.Core.Json

Contents

- Convert from a JSON value
- Convert to a JSON value
- Produce JSON values
- Convenience functions

Synopsis

- defaultLayoutJson :: (Yesod site, ToJSON a) => WidgetT site IO () -> HandlerT site IO a -> HandlerT site IO TypedContent
- jsonToRepJson :: (Monad m, ToJSON a) => a -> m Value
- parseJsonBody :: (MonadHandler m, FromJSON a) => m (Result a)
- parseJsonBody_ :: (MonadHandler m, FromJSON a) => m a
- data Value
  - = Object !Object
  - | Array !Array
  - | String !Text
  - | Number !Number
  - | Bool !Bool
  - | Null
- class ToJSON a where
  - toJSON :: a -> Value
- class FromJSON a where
  - parseJSON :: Value -> Parser a
- array :: ToJSON a => [a] -> Value
- object :: [Pair] -> Value
- (.=) :: ToJSON a => Text -> a -> Pair
- (.:) :: FromJSON a => Object -> Text -> Parser a
- jsonOrRedirect :: (MonadHandler m, ToJSON a) => Route (HandlerSite m) -> a -> m Value
- acceptsJson :: MonadHandler m => m Bool

# Convert from a JSON value

defaultLayoutJson

Arguments

:: (Yesod site, ToJSON a) |
=> WidgetT site IO () | HTML
-> HandlerT site IO a | JSON
-> HandlerT site IO TypedContent |

Provide both an HTML and JSON representation for a piece of data, using the default layout for the HTML output (`defaultLayout`).

Since: 0.3.0

jsonToRepJson :: (Monad m, ToJSON a) => a -> m Value

Wraps a data type in a `RepJson`. The data type must support conversion to JSON via `ToJSON`.

Since: 0.3.0

# Convert to a JSON value

parseJsonBody :: (MonadHandler m, FromJSON a) => m (Result a)

Parse the request body to a data type as a JSON value. The data type must support conversion from JSON via `FromJSON`. If you want the raw JSON value, just ask for a ``Result` `Value``.

Since: 0.3.0

parseJsonBody_ :: (MonadHandler m, FromJSON a) => m a

Same as `parseJsonBody`, but return an invalid args response on a parse error.

# Produce JSON values

data Value

A JSON value represented as a Haskell value.

Constructors

Object !Object |
Array !Array |
String !Text |
Number !Number |
Bool !Bool |
Null |

Instances

Eq Value |
Show Value |
Typeable Value |
IsString Value |
ToJSON Value |
FromJSON Value |
NFData Value |
Hashable Value |
ToJavascript Value |
ToTypedContent Value |
HasContentType Value |
ToContent Value |

class ToJSON a where

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

Methods

toJSON :: a -> Value

Instances

ToJSON Bool |
ToJSON Char |
ToJSON Double |
ToJSON Float |
ToJSON Int |
ToJSON Int8 |
ToJSON Int16 |
ToJSON Int32 |
ToJSON Int64 |
ToJSON Integer |
ToJSON Word |
ToJSON Word8 |
ToJSON Word16 |
ToJSON Word32 |
ToJSON Word64 |
ToJSON () |
ToJSON ByteString |
ToJSON Number |
ToJSON Text |
ToJSON UTCTime |
ToJSON DotNetTime |
ToJSON Value |
ToJSON ByteString |
ToJSON Text |
ToJSON IntSet |
ToJSON ZonedTime |
ToJSON [Char] |
ToJSON a => ToJSON [a] |
ToJSON (Ratio Integer) |
ToJSON a => ToJSON (Maybe a) |
HasResolution a => ToJSON (Fixed a) |
ToJSON a => ToJSON (Dual a) |
ToJSON a => ToJSON (First a) |
ToJSON a => ToJSON (Last a) |
ToJSON a => ToJSON (IntMap a) |
ToJSON a => ToJSON (Set a) |
ToJSON a => ToJSON (HashSet a) |
ToJSON a => ToJSON (Vector a) |
(Vector Vector a, ToJSON a) => ToJSON (Vector a) |
(Storable a, ToJSON a) => ToJSON (Vector a) |
(Prim a, ToJSON a) => ToJSON (Vector a) |
(ToJSON a, ToJSON b) => ToJSON (Either a b) |
(ToJSON a, ToJSON b) => ToJSON (a, b) |
ToJSON v => ToJSON (HashMap String v) |
ToJSON v => ToJSON (HashMap ByteString v) |
ToJSON v => ToJSON (HashMap Text v) |
ToJSON v => ToJSON (HashMap ByteString v) |
ToJSON v => ToJSON (HashMap Text v) |
ToJSON v => ToJSON (Map String v) |
ToJSON v => ToJSON (Map ByteString v) |
ToJSON v => ToJSON (Map Text v) |
ToJSON v => ToJSON (Map ByteString v) |
ToJSON v => ToJSON (Map Text v) |
(ToJSON a, ToJSON b, ToJSON c) => ToJSON (a, b, c) |
(ToJSON a, ToJSON b, ToJSON c, ToJSON d) => ToJSON (a, b, c, d) |

class FromJSON a where

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

Methods

parseJSON :: Value -> Parser a

Instances

FromJSON Bool |
FromJSON Char |
FromJSON Double |
FromJSON Float |
FromJSON Int |
FromJSON Int8 |
FromJSON Int16 |
FromJSON Int32 |
FromJSON Int64 |
FromJSON Integer |
FromJSON Word |
FromJSON Word8 |
FromJSON Word16 |
FromJSON Word32 |
FromJSON Word64 |
FromJSON () |
FromJSON ByteString |
FromJSON Number |
FromJSON Text |
FromJSON UTCTime |
FromJSON DotNetTime |
FromJSON Value |
FromJSON ByteString |
FromJSON Text |
FromJSON IntSet |
FromJSON ZonedTime |
FromJSON [Char] |
FromJSON a => FromJSON [a] |
FromJSON (Ratio Integer) |
FromJSON a => FromJSON (Maybe a) |
HasResolution a => FromJSON (Fixed a) |
FromJSON a => FromJSON (Dual a) |
FromJSON a => FromJSON (First a) |
FromJSON a => FromJSON (Last a) |
FromJSON a => FromJSON (IntMap a) |
(Ord a, FromJSON a) => FromJSON (Set a) |
(Eq a, Hashable a, FromJSON a) => FromJSON (HashSet a) |
FromJSON a => FromJSON (Vector a) |
(Vector Vector a, FromJSON a) => FromJSON (Vector a) |
(Storable a, FromJSON a) => FromJSON (Vector a) |
(Prim a, FromJSON a) => FromJSON (Vector a) |
(FromJSON a, FromJSON b) => FromJSON (Either a b) |
(FromJSON a, FromJSON b) => FromJSON (a, b) |
FromJSON v => FromJSON (HashMap String v) |
FromJSON v => FromJSON (HashMap ByteString v) |
FromJSON v => FromJSON (HashMap Text v) |
FromJSON v => FromJSON (HashMap ByteString v) |
FromJSON v => FromJSON (HashMap Text v) |
FromJSON v => FromJSON (Map String v) |
FromJSON v => FromJSON (Map ByteString v) |
FromJSON v => FromJSON (Map Text v) |
FromJSON v => FromJSON (Map ByteString v) |
FromJSON v => FromJSON (Map Text v) |
(FromJSON a, FromJSON b, FromJSON c) => FromJSON (a, b, c) |
(FromJSON a, FromJSON b, FromJSON c, FromJSON d) => FromJSON (a, b, c, d) |

array :: ToJSON a => [a] -> Value

Convert a list of values to an `Array`.

object :: [Pair] -> Value

Create a `Value` from a list of name/value `Pair`s. If duplicate keys arise, earlier keys and their associated values win.

(.=) :: ToJSON a => Text -> a -> Pair

Construct a `Pair` from a key and a value.

(.:) :: FromJSON a => Object -> Text -> Parser a

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.

# Convenience functions

jsonOrRedirect

Arguments

:: (MonadHandler m, ToJSON a) |
=> Route (HandlerSite m) | Redirect target
-> a | Data to send via JSON
-> m Value |

jsonOrRedirect simplifies the scenario where a POST handler sends a different response based on Accept headers:

1. 200 with JSON data if the client prefers `application/json` (e.g. AJAX, see `acceptsJSON`).
2. 3xx otherwise, following the PRG pattern.

acceptsJson :: MonadHandler m => m Bool

Returns `True` if the client prefers `application/json` as indicated by the `Accept` HTTP header.