Copyright	(c) 2011-2016 Bryan O'Sullivan (c) 2011 MailRank Inc.
License	BSD3
Maintainer	Bryan O'Sullivan <bos@serpentine.com>
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

Data.Aeson.Parser.Internal

Contents

Lazy parsers
Strict parsers
Helpers
- Handling objects with duplicate keys
Text literal unescaping

Description

Efficiently and correctly parse a JSON string. The string must be encoded as UTF-8.

Synopsis

json :: Parser Value
jsonEOF :: Parser Value
jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value
jsonLast :: Parser Value
jsonAccum :: Parser Value
jsonNoDup :: Parser Value
value :: Parser Value
jstring :: Parser Text
jstring_ :: Parser Text
scientific :: Parser Scientific
json' :: Parser Value
jsonEOF' :: Parser Value
jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value
jsonLast' :: Parser Value
jsonAccum' :: Parser Value
jsonNoDup' :: Parser Value
value' :: Parser Value
decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
fromListAccum :: [(Key, Value)] -> Object
parseListNoDup :: [(Key, Value)] -> Either String Object
unescapeText :: ByteString -> Either UnicodeException Text

Lazy parsers

json :: Parser 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.

jsonEOF :: Parser Value #

Parse a top-level JSON value followed by optional whitespace and end-of-input. See also: json.

jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value #

Parse any JSON value.

This parser is parameterized by a function to construct an Object from a raw list of key-value pairs, where duplicates are preserved. The pairs appear in reverse order from the source.

Examples

Expand

json keeps only the first occurrence of each key, using fromList.

json = jsonWith (Right . fromList)

jsonLast keeps the last occurrence of each key, using fromListWith (const id).

jsonLast = jsonWith (Right . fromListWith (const id))

jsonAccum keeps wraps all values in arrays to keep duplicates, using fromListAccum.

jsonAccum = jsonWith (Right . fromListAccum)

jsonNoDup fails if any object contains duplicate keys, using parseListNoDup.

jsonNoDup = jsonWith parseListNoDup

jsonLast :: Parser Value #

Variant of json which keeps only the last occurrence of every key.

jsonAccum :: Parser Value #

Variant of json wrapping all object mappings in Array to preserve key-value pairs with the same keys.

jsonNoDup :: Parser Value #

Variant of json which fails if any object contains duplicate keys.

value :: Parser Value #

Parse any JSON value. Synonym of json.

jstring :: Parser Text #

Parse a quoted JSON string.

jstring_ :: Parser Text #

Parse a string without a leading quote.

scientific :: Parser Scientific #

Parse a JSON number.

Strict parsers

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'.

jsonEOF' :: Parser Value #

Parse a top-level JSON value followed by optional whitespace and end-of-input. See also: json'.

jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value #

Strict version of jsonWith.

jsonLast' :: Parser Value #

Variant of json' which keeps only the last occurrence of every key.

jsonAccum' :: Parser Value #

Variant of json' wrapping all object mappings in Array to preserve key-value pairs with the same keys.

jsonNoDup' :: Parser Value #

Variant of json' which fails if any object contains duplicate keys.

value' :: Parser Value #

Strict version of value. Synonym of json'.

Helpers

decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a #

decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a #

eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a #

eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a #

Handling objects with duplicate keys

fromListAccum :: [(Key, Value)] -> Object #

fromListAccum kvs is an object mapping keys to arrays containing all associated values from the original list kvs.

>>> fromListAccum [("apple", Bool True), ("apple", Bool False), ("orange", Bool False)]
fromList [("apple",Array [Bool False,Bool True]),("orange",Array [Bool False])]

parseListNoDup :: [(Key, Value)] -> Either String Object #

fromListNoDup kvs fails if kvs contains duplicate keys.

Text literal unescaping

unescapeText :: ByteString -> Either UnicodeException Text #

Unescape JSON text literal.

This function is exporeted mostly for testing and benchmarking purposes.