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.

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.Unsafe 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 in 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 appened.

decode :: (Monad m, FromJSON b) => StateT (Producer ByteString m r) m (Either DecodingError (Int, b))

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

Returns either the decoded entitiy and the number of decoded bytes, or a DecodingError in case of failures.

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 Producer restricts its output to them. If you prefer to ignore the standard and decode any Value, then use decode from the Pipes.Aeson.Unsafe module.

decodeMany

Arguments

:: (Monad m, FromJSON b)

=> Producer ByteString m r

Producer from which to draw JSON.

-> Producer (Int, b) m (Either (DecodingError, Producer ByteString m r) r)

Continuously decode the JSON output from the given Producer, sending downstream pairs of each successfully decoded entity together with the number of bytes consumed in order to produce it. Whitespace in between JSON content is ignored.

This Producer runs until it either runs out of input or until a decoding failure occurs, in which case it returns Left with a DecodingError and a Producer with any leftovers. You can use errorP to turn the Either return value into an ErrorT monad transformer.

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

Types

data DecodingError

An error while decoding a JSON value.

Constructors

ParserError ParsingError

An Attoparsec error that happened while parsing the raw JSON string.

ValueError 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

Monad m => Error (DecodingError, Producer a m r)