attoparsec-aeson-2.2.0.1: Parsing of aeson's Value with attoparsec

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 | Safe-Inferred
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.