aeson-2.1.2.1: Fast JSON parsing and encoding

Copyright | (c) 2012-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

Contents

- Lazy parsers
  - Handling objects with duplicate keys
- Strict parsers
  - Handling objects with duplicate keys
- Decoding without FromJSON instances

Description

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

It can be useful to think of parsing as occurring in two phases:

- Identification of the textual boundaries of a JSON value. This is always strict, so that an invalid JSON document can be rejected as soon as possible.
- Conversion of a JSON value to a Haskell value. This may be either immediate (strict) or deferred (lazy); see below for details.

The question of whether to choose a lazy or strict parser is subtle, but it can have significant performance implications, resulting in changes in CPU use and memory footprint of 30% to 50%, or occasionally more. Measure the performance of your application with each!

Synopsis

- json :: Parser Value
- value :: Parser Value
- jstring :: Parser Text
- scientific :: Parser Scientific
- jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value
- jsonLast :: Parser Value
- jsonAccum :: Parser Value
- jsonNoDup :: Parser Value
- json' :: Parser Value
- value' :: Parser Value
- jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value
- jsonLast' :: Parser Value
- jsonAccum' :: Parser Value
- jsonNoDup' :: 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

# Lazy parsers

The `json` and `value` parsers decouple identification from conversion. Identification occurs immediately (so that an invalid JSON document can be rejected as early as possible), but conversion to a Haskell value is deferred until that value is needed.

This decoupling can be time-efficient if only a smallish subset of elements in a JSON value need to be inspected, since the cost of conversion is zero for uninspected elements. The trade off is an increase in memory usage, due to allocation of thunks for values that have not yet been converted.

json :: Parser Value Source #

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

value :: Parser Value Source #

Parse any JSON value. Synonym of `json`.

jstring :: Parser Text Source #

Parse a quoted JSON string.

scientific :: Parser Scientific Source #

Parse a JSON number.

## Handling objects with duplicate keys

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

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 Source #

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

jsonAccum :: Parser Value Source #

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

jsonNoDup :: Parser Value Source #

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

# Strict parsers

The `json'` and `value'` parsers combine identification with conversion. They consume more CPU cycles up front, but have a smaller memory footprint.

json' :: Parser Value Source #

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

value' :: Parser Value Source #

Strict version of `value`. Synonym of `json'`.

## Handling objects with duplicate keys

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

Strict version of `jsonWith`.

jsonLast' :: Parser Value Source #

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

jsonAccum' :: Parser Value Source #

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

jsonNoDup' :: Parser Value Source #

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

# Decoding without FromJSON instances

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

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

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

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