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

Safe HaskellNone
LanguageHaskell98

Pipes.Aeson

Contents

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

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:

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.