Pipes.Aeson

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)

Encoding

encode :: Monad m => Either Object Array -> Producer' ByteString m ()

Encode an Array or Object as JSON and send it 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 this function restricts its input to them. If you prefer to ignore the standard and encode any Value, then use encode from the Pipes.Aeson.Unchecked module.

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

 for cat encode :: (Monad m) => Pipe (Either Object Array) 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 the step it happened.

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

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

Returns either the decoded entitiy, or a DecodingError in case of error.

Do not use this function if the underlying Producer has leading empty chunks or whitespace, otherwise you may get unexpected parsing errors.

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

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 (Either DecodingError (Int, a))

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

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

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

Data DecodingError

Show DecodingError

Typeable DecodingError

Exception DecodingError

Error DecodingError

Error (DecodingError, Producer a m r)

This instance allows using errorP with decoded and decodedL