Text.JSON

json-0.11: Support for serialising Haskell to and from JSON

Safe Haskell | Safe-Inferred
Language | Haskell2010

Text.JSON

Contents

- JSON Types
- Serialization to and from JSValues
- Encoding and Decoding
- Wrapper Types
- Serialization to and from Strings.
  - Reading JSON
  - Writing JSON
  - Instance helpers

Description

Serialising Haskell values to and from JSON values.

Synopsis

- data JSValue
  - = JSNull
  - | JSBool !Bool
  - | JSRational Bool !Rational
  - | JSString JSString
  - | JSArray [JSValue]
  - | JSObject (JSObject JSValue)
- class JSON a where
  - readJSON :: JSValue -> Result a
  - showJSON :: a -> JSValue
  - readJSONs :: JSValue -> Result [a]
  - showJSONs :: [a] -> JSValue
- data Result a
  - = Ok a
  - | Error String
- encode :: JSON a => a -> String
- decode :: JSON a => String -> Result a
- encodeStrict :: JSON a => a -> String
- decodeStrict :: JSON a => String -> Result a
- data JSString
- toJSString :: String -> JSString
- fromJSString :: JSString -> String
- data JSObject e
- toJSObject :: [(String, a)] -> JSObject a
- fromJSObject :: JSObject e -> [(String, e)]
- resultToEither :: Result a -> Either String a
- readJSNull :: GetJSON JSValue
- readJSBool :: GetJSON JSValue
- readJSString :: GetJSON JSValue
- readJSRational :: GetJSON Rational
- readJSArray :: GetJSON JSValue
- readJSObject :: GetJSON JSValue
- readJSValue :: GetJSON JSValue
- showJSNull :: ShowS
- showJSBool :: Bool -> ShowS
- showJSArray :: [JSValue] -> ShowS
- showJSRational :: Rational -> ShowS
- showJSRational' :: Bool -> Rational -> ShowS
- showJSObject :: JSObject JSValue -> ShowS
- showJSValue :: JSValue -> ShowS
- makeObj :: [(String, JSValue)] -> JSValue
- valFromObj :: JSON a => String -> JSObject JSValue -> Result a
- class JSKey a where
  - toJSKey :: a -> String
  - fromJSKey :: String -> Maybe a
- encJSDict :: (JSKey a, JSON b) => [(a, b)] -> JSValue
- decJSDict :: (JSKey a, JSON b) => String -> JSValue -> Result [(a, b)]

# JSON Types

data JSValue #

JSON values

The type to which we encode Haskell values. There's a set of primitives, and a couple of heterogenous collection types.

Objects:

An object structure is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). A name is a string. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name.

Arrays:

An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas.

Only valid JSON can be constructed this way

Constructors

JSNull |
JSBool !Bool |
JSRational Bool !Rational |
JSString JSString |
JSArray [JSValue] |
JSObject (JSObject JSValue) |

#### Instances

Instances details

IsString JSValue # |
Instance details Defined in Text.JSON.Types Methods fromString :: String -> JSValue #
Read JSValue # |
Instance details Defined in Text.JSON.Types Methods readsPrec :: Int -> ReadS JSValue # readList :: ReadS [JSValue] # readPrec :: ReadPrec JSValue # readListPrec :: ReadPrec [JSValue] #
Show JSValue # |
Instance details Defined in Text.JSON.Types Methods showsPrec :: Int -> JSValue -> ShowS # show :: JSValue -> String # showList :: [JSValue] -> ShowS #
Eq JSValue # |
Instance details Defined in Text.JSON.Types Methods (==) :: JSValue -> JSValue -> Bool # (/=) :: JSValue -> JSValue -> Bool #
Ord JSValue # |
Instance details Defined in Text.JSON.Types Methods compare :: JSValue -> JSValue -> Ordering # (<) :: JSValue -> JSValue -> Bool # (<=) :: JSValue -> JSValue -> Bool # (>) :: JSValue -> JSValue -> Bool # (>=) :: JSValue -> JSValue -> Bool # max :: JSValue -> JSValue -> JSValue # min :: JSValue -> JSValue -> JSValue #
JSON JSValue # | To ensure we generate valid JSON, we map Haskell types to JSValue internally, then pretty print that.
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result JSValue # showJSON :: JSValue -> JSValue # readJSONs :: JSValue -> Result [JSValue] # showJSONs :: [JSValue] -> JSValue #

# Serialization to and from JSValues

class JSON a where #

The class of types serialisable to and from JSON

Minimal complete definition

readJSON, showJSON

Methods

readJSON :: JSValue -> Result a #

showJSON :: a -> JSValue #

readJSONs :: JSValue -> Result [a] #

showJSONs :: [a] -> JSValue #

#### Instances

Instances details

JSON ByteString # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result ByteString # showJSON :: ByteString -> JSValue # readJSONs :: JSValue -> Result [ByteString] # showJSONs :: [ByteString] -> JSValue #
JSON ByteString # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result ByteString # showJSON :: ByteString -> JSValue # readJSONs :: JSValue -> Result [ByteString] # showJSONs :: [ByteString] -> JSValue #
JSON IntSet # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result IntSet # showJSON :: IntSet -> JSValue # readJSONs :: JSValue -> Result [IntSet] # showJSONs :: [IntSet] -> JSValue #
JSON Int16 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Int16 # showJSON :: Int16 -> JSValue # readJSONs :: JSValue -> Result [Int16] # showJSONs :: [Int16] -> JSValue #
JSON Int32 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Int32 # showJSON :: Int32 -> JSValue # readJSONs :: JSValue -> Result [Int32] # showJSONs :: [Int32] -> JSValue #
JSON Int64 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Int64 # showJSON :: Int64 -> JSValue # readJSONs :: JSValue -> Result [Int64] # showJSONs :: [Int64] -> JSValue #
JSON Int8 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Int8 # showJSON :: Int8 -> JSValue # readJSONs :: JSValue -> Result [Int8] # showJSONs :: [Int8] -> JSValue #
JSON Word16 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Word16 # showJSON :: Word16 -> JSValue # readJSONs :: JSValue -> Result [Word16] # showJSONs :: [Word16] -> JSValue #
JSON Word32 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Word32 # showJSON :: Word32 -> JSValue # readJSONs :: JSValue -> Result [Word32] # showJSONs :: [Word32] -> JSValue #
JSON Word64 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Word64 # showJSON :: Word64 -> JSValue # readJSONs :: JSValue -> Result [Word64] # showJSONs :: [Word64] -> JSValue #
JSON Word8 # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Word8 # showJSON :: Word8 -> JSValue # readJSONs :: JSValue -> Result [Word8] # showJSONs :: [Word8] -> JSValue #
JSON Ordering # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Ordering # showJSON :: Ordering -> JSValue # readJSONs :: JSValue -> Result [Ordering] # showJSONs :: [Ordering] -> JSValue #
JSON JSString # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result JSString # showJSON :: JSString -> JSValue # readJSONs :: JSValue -> Result [JSString] # showJSONs :: [JSString] -> JSValue #
JSON JSValue # | To ensure we generate valid JSON, we map Haskell types to JSValue internally, then pretty print that.
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result JSValue # showJSON :: JSValue -> JSValue # readJSONs :: JSValue -> Result [JSValue] # showJSONs :: [JSValue] -> JSValue #
JSON Text # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Text # showJSON :: Text -> JSValue # readJSONs :: JSValue -> Result [Text] # showJSONs :: [Text] -> JSValue #
JSON Integer # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Integer # showJSON :: Integer -> JSValue # readJSONs :: JSValue -> Result [Integer] # showJSONs :: [Integer] -> JSValue #
JSON () # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result () # showJSON :: () -> JSValue # readJSONs :: JSValue -> Result [()] # showJSONs :: [()] -> JSValue #
JSON Bool # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Bool # showJSON :: Bool -> JSValue # readJSONs :: JSValue -> Result [Bool] # showJSONs :: [Bool] -> JSValue #
JSON Char # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Char # showJSON :: Char -> JSValue # readJSONs :: JSValue -> Result [Char] # showJSONs :: [Char] -> JSValue #
JSON Double # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Double # showJSON :: Double -> JSValue # readJSONs :: JSValue -> Result [Double] # showJSONs :: [Double] -> JSValue #
JSON Float # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Float # showJSON :: Float -> JSValue # readJSONs :: JSValue -> Result [Float] # showJSONs :: [Float] -> JSValue #
JSON Int # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Int # showJSON :: Int -> JSValue # readJSONs :: JSValue -> Result [Int] # showJSONs :: [Int] -> JSValue #
JSON Word # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result Word # showJSON :: Word -> JSValue # readJSONs :: JSValue -> Result [Word] # showJSONs :: [Word] -> JSValue #
JSON a => JSON (IntMap a) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (IntMap a) # showJSON :: IntMap a -> JSValue # readJSONs :: JSValue -> Result [IntMap a] # showJSONs :: [IntMap a] -> JSValue #
(Ord a, JSON a) => JSON (Set a) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (Set a) # showJSON :: Set a -> JSValue # readJSONs :: JSValue -> Result [Set a] # showJSONs :: [Set a] -> JSValue #
JSON a => JSON (JSObject a) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (JSObject a) # showJSON :: JSObject a -> JSValue # readJSONs :: JSValue -> Result [JSObject a] # showJSONs :: [JSObject a] -> JSValue #
JSON a => JSON (Maybe a) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (Maybe a) # showJSON :: Maybe a -> JSValue # readJSONs :: JSValue -> Result [Maybe a] # showJSONs :: [Maybe a] -> JSValue #
JSON a => JSON [a] # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result [a] # showJSON :: [a] -> JSValue # readJSONs :: JSValue -> Result [[a]] # showJSONs :: [[a]] -> JSValue #
(Ord a, JSON a, JSON b) => JSON (Map a b) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (Map a b) # showJSON :: Map a b -> JSValue # readJSONs :: JSValue -> Result [Map a b] # showJSONs :: [Map a b] -> JSValue #
(Ix i, JSON i, JSON e) => JSON (Array i e) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (Array i e) # showJSON :: Array i e -> JSValue # readJSONs :: JSValue -> Result [Array i e] # showJSONs :: [Array i e] -> JSValue #
(JSON a, JSON b) => JSON (Either a b) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (Either a b) # showJSON :: Either a b -> JSValue # readJSONs :: JSValue -> Result [Either a b] # showJSONs :: [Either a b] -> JSValue #
(JSON a, JSON b) => JSON (a, b) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (a, b) # showJSON :: (a, b) -> JSValue # readJSONs :: JSValue -> Result [(a, b)] # showJSONs :: [(a, b)] -> JSValue #
(JSON a, JSON b, JSON c) => JSON (a, b, c) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (a, b, c) # showJSON :: (a, b, c) -> JSValue # readJSONs :: JSValue -> Result [(a, b, c)] # showJSONs :: [(a, b, c)] -> JSValue #
(JSON a, JSON b, JSON c, JSON d) => JSON (a, b, c, d) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (a, b, c, d) # showJSON :: (a, b, c, d) -> JSValue # readJSONs :: JSValue -> Result [(a, b, c, d)] # showJSONs :: [(a, b, c, d)] -> JSValue #

# Encoding and Decoding

data Result a #

A type for parser results

Constructors

Ok a |
Error String |

#### Instances

Instances details

Alternative Result # |
Instance details Defined in Text.JSON Methods empty :: Result a # (<|>) :: Result a -> Result a -> Result a # some :: Result a -> Result [a] # many :: Result a -> Result [a] #
Applicative Result # |
Instance details Defined in Text.JSON Methods pure :: a -> Result a # (<*>) :: Result (a -> b) -> Result a -> Result b # liftA2 :: (a -> b -> c) -> Result a -> Result b -> Result c # (*>) :: Result a -> Result b -> Result b # (<*) :: Result a -> Result b -> Result a #
Functor Result # |
Instance details Defined in Text.JSON Methods fmap :: (a -> b) -> Result a -> Result b # (<$) :: a -> Result b -> Result a #
Monad Result # |
Instance details Defined in Text.JSON Methods (>>=) :: Result a -> (a -> Result b) -> Result b # (>>) :: Result a -> Result b -> Result b # return :: a -> Result a #
MonadPlus Result # |
Instance details Defined in Text.JSON Methods mzero :: Result a # mplus :: Result a -> Result a -> Result a #
MonadFail Result # |
Instance details Defined in Text.JSON Methods fail :: String -> Result a #
Show a => Show (Result a) # |
Instance details Defined in Text.JSON Methods showsPrec :: Int -> Result a -> ShowS # show :: Result a -> String # showList :: [Result a] -> ShowS #
Eq a => Eq (Result a) # |
Instance details Defined in Text.JSON Methods (==) :: Result a -> Result a -> Bool # (/=) :: Result a -> Result a -> Bool #

encode :: JSON a => a -> String #

Encode a Haskell value into a string, in JSON format.

This is a superset of JSON, as types other than Array and Object are allowed at the top level.

decode :: JSON a => String -> Result a #

Decode a String representing a JSON value (either an object, array, bool, number, null)

This is a superset of JSON, as types other than Array and Object are allowed at the top level.

encodeStrict :: JSON a => a -> String #

Encode a value as a String in strict JSON format. This follows the spec, and requires all values at the top level to be wrapped in either an Array or Object. JSON types to be an Array or Object.

decodeStrict :: JSON a => String -> Result a #

Decode a String representing a strict JSON value. This follows the spec, and requires top level JSON types to be an Array or Object.

# Wrapper Types

data JSString #

Strings can be represented a little more efficiently in JSON

#### Instances

Instances details

IsString JSString # |
Instance details Defined in Text.JSON.Types Methods fromString :: String -> JSString #
Read JSString # |
Instance details Defined in Text.JSON.Types Methods readsPrec :: Int -> ReadS JSString # readList :: ReadS [JSString] # readPrec :: ReadPrec JSString # readListPrec :: ReadPrec [JSString] #
Show JSString # |
Instance details Defined in Text.JSON.Types Methods showsPrec :: Int -> JSString -> ShowS # show :: JSString -> String # showList :: [JSString] -> ShowS #
Eq JSString # |
Instance details Defined in Text.JSON.Types Methods (==) :: JSString -> JSString -> Bool # (/=) :: JSString -> JSString -> Bool #
Ord JSString # |
Instance details Defined in Text.JSON.Types Methods compare :: JSString -> JSString -> Ordering # (<) :: JSString -> JSString -> Bool # (<=) :: JSString -> JSString -> Bool # (>) :: JSString -> JSString -> Bool # (>=) :: JSString -> JSString -> Bool # max :: JSString -> JSString -> JSString # min :: JSString -> JSString -> JSString #
JSKey JSString # |
Instance details Defined in Text.JSON Methods toJSKey :: JSString -> String # fromJSKey :: String -> Maybe JSString #
JSON JSString # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result JSString # showJSON :: JSString -> JSValue # readJSONs :: JSValue -> Result [JSString] # showJSONs :: [JSString] -> JSValue #

toJSString :: String -> JSString #

Turn a Haskell string into a JSON string.

fromJSString :: JSString -> String #

data JSObject e #

As can association lists

#### Instances

Instances details

Read e => Read (JSObject e) # |
Instance details Defined in Text.JSON.Types Methods readsPrec :: Int -> ReadS (JSObject e) # readList :: ReadS [JSObject e] # readPrec :: ReadPrec (JSObject e) # readListPrec :: ReadPrec [JSObject e] #
Show e => Show (JSObject e) # |
Instance details Defined in Text.JSON.Types Methods showsPrec :: Int -> JSObject e -> ShowS # show :: JSObject e -> String # showList :: [JSObject e] -> ShowS #
Eq e => Eq (JSObject e) # |
Instance details Defined in Text.JSON.Types Methods (==) :: JSObject e -> JSObject e -> Bool # (/=) :: JSObject e -> JSObject e -> Bool #
Ord e => Ord (JSObject e) # |
Instance details Defined in Text.JSON.Types Methods compare :: JSObject e -> JSObject e -> Ordering # (<) :: JSObject e -> JSObject e -> Bool # (<=) :: JSObject e -> JSObject e -> Bool # (>) :: JSObject e -> JSObject e -> Bool # (>=) :: JSObject e -> JSObject e -> Bool # max :: JSObject e -> JSObject e -> JSObject e # min :: JSObject e -> JSObject e -> JSObject e #
JSON a => JSON (JSObject a) # |
Instance details Defined in Text.JSON Methods readJSON :: JSValue -> Result (JSObject a) # showJSON :: JSObject a -> JSValue # readJSONs :: JSValue -> Result [JSObject a] # showJSONs :: [JSObject a] -> JSValue #

toJSObject :: [(String, a)] -> JSObject a #

Make JSON object out of an association list.

fromJSObject :: JSObject e -> [(String, e)] #

resultToEither :: Result a -> Either String a #

Map Results to Eithers

# Serialization to and from Strings.

## Reading JSON

readJSNull :: GetJSON JSValue #

Read the JSON null type

readJSBool :: GetJSON JSValue #

Read the JSON Bool type

readJSString :: GetJSON JSValue #

Read the JSON String type

readJSRational :: GetJSON Rational #

Read an Integer or Double in JSON format, returning a Rational

readJSArray :: GetJSON JSValue #

Read a list in JSON format

readJSObject :: GetJSON JSValue #

Read an object in JSON format

readJSValue :: GetJSON JSValue #

Read one of several possible JS types

## Writing JSON

showJSNull :: ShowS #

Write the JSON null type

showJSBool :: Bool -> ShowS #

Write the JSON Bool type

showJSArray :: [JSValue] -> ShowS #

Show a list in JSON format

showJSRational :: Rational -> ShowS #

Show a Rational in JSON format

showJSRational' :: Bool -> Rational -> ShowS #

showJSObject :: JSObject JSValue -> ShowS #

Show an association list in JSON format

showJSValue :: JSValue -> ShowS #

Show JSON values

## Instance helpers

makeObj :: [(String, JSValue)] -> JSValue #

valFromObj :: JSON a => String -> JSObject JSValue -> Result a #

Pull a value out of a JSON object.

class JSKey a where #

Haskell types that can be used as keys in JSON objects.

Methods

toJSKey :: a -> String #

fromJSKey :: String -> Maybe a #

#### Instances

Instances details

JSKey JSString # |
Instance details Defined in Text.JSON Methods toJSKey :: JSString -> String # fromJSKey :: String -> Maybe JSString #
JSKey String # |
Instance details Defined in Text.JSON Methods toJSKey :: String -> String # fromJSKey :: String -> Maybe String #
JSKey Int # |
Instance details Defined in Text.JSON Methods toJSKey :: Int -> String # fromJSKey :: String -> Maybe Int #

encJSDict :: (JSKey a, JSON b) => [(a, b)] -> JSValue #

Encode an association list as `JSObject` value.

decJSDict :: (JSKey a, JSON b) => String -> JSValue -> Result [(a, b)] #

Decode a `JSObject` value into an association list.