-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Encode and decode JSON streams using Aeson and Pipes.
--   
--   Utilities to encode and decode Pipes streams of JSON.
--   
--   See the changelog.md file in the source distribution to learn
--   about any important changes between version.
@package pipes-aeson
@version 0.4.1.5

-- | This module exports facilities similar to those exported by the
--   Pipes.Aeson module, except they do not restrict the
--   Values that might be encoded or decoded to be just valid
--   top-level values. That is, not only Objects or Arrays,
--   according to to the RFC-4627 JSON standard.
module Pipes.Aeson.Unchecked

-- | Like encode, except it accepts any ToJSON instance, not
--   just Array or Object.
encode :: (Monad m, ToJSON a) => a -> Producer' ByteString m ()

-- | Like decode, except it will decode any FromJSON
--   instance, not just Array or Object.
decode :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError a))

-- | Like decoded, except it will decode and decode any
--   FromJSON and ToJSON instance, not just Array or
--   Object.
decoded :: (Monad m, FromJSON a, ToJSON a) => Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r))

-- | 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 between each parsed JSON input.
decodeL :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError (Int, a)))

-- | 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.
decodedL :: (Monad m, FromJSON a, ToJSON a) => Lens' (Producer ByteString m r) (Producer (Int, a) m (Either (DecodingError, Producer ByteString m r) r))

-- | 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)
--   
module Pipes.Aeson

-- | 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
--   
encodeArray :: Monad m => Array -> Producer' ByteString m ()

-- | 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
--   
encodeObject :: Monad m => Object -> Producer' ByteString m ()

-- | 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.
decode :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError a))

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

-- | 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.
decodeL :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError (Int, a)))

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

-- | An error while decoding a JSON value.
data DecodingError

-- | An attoparsec error that happened while parsing the raw JSON
--   string.
AttoparsecError :: ParsingError -> DecodingError

-- | An aeson error that happened while trying to convert a
--   Value to an FromJSON instance, as reported by
--   Error.
FromJSONError :: String -> DecodingError
