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

Portability | portable
Stability | provisional
Maintainer | Sigbjorn Finne <sof@galois.com>
Safe Haskell | Safe-Inferred

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

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 Source

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

Eq JSValue |
Ord JSValue |
Read JSValue |
Show JSValue |
Typeable JSValue |
JSON JSValue | To ensure we generate valid JSON, we map Haskell types to JSValue internally, then pretty print that.

# Serialization to and from JSValues

class JSON a where Source

The class of types serialisable to and from JSON

Methods

readJSON :: JSValue -> Result aSource

showJSON :: a -> JSValue Source

readJSONs :: JSValue -> Result [a]Source

showJSONs :: [a] -> JSValue Source

Instances

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

# Encoding and Decoding

data Result a Source

A type for parser results

Constructors

Ok a |
Error String |

Instances

Monad Result |
Functor Result |
MonadPlus Result |
Applicative Result |
Alternative Result |
Eq a => Eq (Result a) |
Show a => Show (Result a) |

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

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 aSource

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 Source

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 aSource

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 Source

Strings can be represented a little more efficiently in JSON

Instances

Eq JSString |
Ord JSString |
Read JSString |
Show JSString |
Typeable JSString |
JSKey JSString |
JSON JSString |

toJSString :: String -> JSString Source

Turn a Haskell string into a JSON string.

fromJSString :: JSString -> String Source

data JSObject e Source

As can association lists

Instances

Typeable1 JSObject |
Eq e => Eq (JSObject e) |
Ord e => Ord (JSObject e) |
Read e => Read (JSObject e) |
Show e => Show (JSObject e) |
JSON a => JSON (JSObject a) |

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

Make JSON object out of an association list.

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

resultToEither :: Result a -> Either String aSource

Map Results to Eithers

# Serialization to and from Strings.

## Reading JSON

readJSNull :: GetJSON JSValue Source

Read the JSON null type

readJSBool :: GetJSON JSValue Source

Read the JSON Bool type

readJSString :: GetJSON JSValue Source

Read the JSON String type

readJSRational :: GetJSON Rational Source

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

readJSArray :: GetJSON JSValue Source

Read a list in JSON format

readJSObject :: GetJSON JSValue Source

Read an object in JSON format

readJSValue :: GetJSON JSValue Source

Read one of several possible JS types

## Writing JSON

showJSNull :: ShowS Source

Write the JSON null type

showJSBool :: Bool -> ShowS Source

Write the JSON Bool type

showJSArray :: [JSValue] -> ShowS Source

Show a list in JSON format

showJSRational :: Rational -> ShowS Source

Show a Rational in JSON format

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

showJSObject :: JSObject JSValue -> ShowS Source

Show an association list in JSON format

showJSValue :: JSValue -> ShowS Source

Show JSON values

## Instance helpers

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

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

Pull a value out of a JSON object.

class JSKey a where Source

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

Methods

toJSKey :: a -> String Source

fromJSKey :: String -> Maybe aSource

Instances

JSKey Int |
JSKey String |
JSKey JSString |

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

Encode an association list as `JSObject` value.

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

Decode a `JSObject` value into an association list.