pipes-aeson-0.4.1.5: Encode and decode JSON streams using Aeson and Pipes.

Safe Haskell | None
Language | Haskell98

Pipes.Aeson

Contents

- Encoding
- Decoding
  - Including lengths
- Types

Description

This module allows you to encode and decode JSON values flowing downstream through Pipes streams.

This module builds on top of the `aeson`, `pipes` and `pipes-parse` libraries, and assumes you know how to use them. Please read the examples in Pipes.Parse.Tutorial to understand how to use these functions.

In this module, the following type synonym compatible with the `lens`, `lens-family` and `lens-family-core` libraries is used but not exported:

    type Lens' s a = forall f . Functor f => (a -> f a) -> (s -> f s)

Synopsis

- encodeArray :: Monad m => Array -> Producer' ByteString m ()
- encodeObject :: Monad m => Object -> Producer' ByteString m ()
- decode :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError a))
- decoded :: (Monad m, FromJSON a, ToJSON a) => (Value -> Either Object Array) -> Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r))
- decodeL :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError (Int, a)))
- decodedL :: (Monad m, FromJSON a, ToJSON a) => (Value -> Either Object Array) -> Lens' (Producer ByteString m r) (Producer (Int, a) m (Either (DecodingError, Producer ByteString m r) r))
- data DecodingError
  - = AttoparsecError ParsingError
  - | FromJSONError String

# Encoding

Encode `Array` or `Object` values as JSON and send them downstream, possibly in more than one `ByteString` chunk.

Note: The JSON RFC-4627 standard only allows arrays or objects as top-level entities, which is why these functions restrict their input to them. If you prefer to ignore the standard and encode any `Value`, then use `encode` from the Pipes.Aeson.Unchecked module.

encodeArray :: Monad m => Array -> Producer' ByteString m () Source

Encode an `Array` as JSON and send it downstream,

Hint: You can easily turn this `Producer'` into a `Pipe` that encodes `Array` values as JSON as they flow downstream using:

    for cat encodeArray :: Monad m => Pipe Array ByteString m r

encodeObject :: Monad m => Object -> Producer' ByteString m () Source

Encode an `Object` as JSON and send it downstream,

Hint: You can easily turn this `Producer'` into a `Pipe` that encodes `Object` values as JSON as they flow downstream using:

    for cat encodeObject :: Monad m => Pipe Object ByteString m r

# Decoding

Decoding JSON as a Haskell value involves two different steps:

- Parsing a raw JSON `ByteString` into an `Object` or an `Array`.
- Converting the obtained `Object` or `Array` to the desired `FromJSON` instance.

Any of those steps can fail, in which case a `DecodingError` will report the precise error and at which step it happened.

decode :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError a)) Source

Decodes an `Object` or `Array` JSON value from the underlying state.

It returns `Nothing` if the underlying `Producer` is exhausted, otherwise it returns either the decoded entity or a `DecodingError` in case of error.

Note: The JSON RFC-4627 standard only allows arrays or objects as top-level entities, which is why this `Parser` restricts its output to them. If you prefer to ignore the standard and decode any `Value`, then use `decode` from the Pipes.Aeson.Unchecked module.

decoded Source

Arguments

:: (Monad m, FromJSON a, ToJSON a) |
=> (Value -> Either Object Array) | A witness that `a` can be represented either as an `Object` or as an `Array`. The passed in `Value` is ``toJSON` a`
-> Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r)) |

Improper lens that turns a stream of raw JSON input into a stream of `FromJSON` and back.

By improper lens we mean that in practice you can't expect the Monad Morphism Laws to be true when using `decoded` with `zoom`.

    zoom decoded (return r) /= return r
    zoom decoded (m >>= k)  /= zoom m >>= zoom . f

Note: The JSON RFC-4627 standard only allows arrays or objects as top-level entities, which is why this function restricts its stream values to them. If you prefer to ignore the standard and encode or decode any `Value`, then use `decoded` from the Pipes.Aeson.Unchecked module.

## Including lengths

decodeL :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError (Int, a))) Source

Like `decode`, except it also returns the length of JSON input that was consumed in order to obtain the value, not including the length of whitespace before nor after the parsed JSON input.

decodedL Source

Arguments

:: (Monad m, FromJSON a, ToJSON a) |
=> (Value -> Either Object Array) | A witness that `a` can be represented either as an `Object` or as an `Array`. The passed in `Value` is ``toJSON` a`
-> Lens' (Producer ByteString m r) (Producer (Int, a) m (Either (DecodingError, Producer ByteString m r) r)) |

Like `decoded`, except it also tags each decoded entity with the length of JSON input that was consumed in order to obtain the value, not including the length of whitespace between each parsed JSON input.

# Types

data DecodingError Source

An error while decoding a JSON value.

Constructors

AttoparsecError ParsingError | An `attoparsec` error that happened while parsing the raw JSON string.
FromJSONError String | An `aeson` error that happened while trying to convert a `Value` to an `FromJSON` instance, as reported by `Error`.

Instances

Eq DecodingError Source |
Data DecodingError Source |
Show DecodingError Source |
Exception DecodingError Source |
Error DecodingError Source |
Error (DecodingError, Producer a m r) Source | This instance allows using `errorP` with `decoded` and `decodedL`