-- 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 <tt>changelog.md</tt> file in the source distribution to learn
--   about any important changes between version.
@package pipes-aeson
@version 0.4.1.8


-- | This module exports facilities similar to those exported by the
--   <a>Pipes.Aeson</a> module, except they do not restrict the
--   <a>Value</a>s that might be encoded or decoded to be just valid
--   top-level values. That is, not only <a>Object</a>s or <a>Array</a>s,
--   according to to the RFC-4627 JSON standard.
module Pipes.Aeson.Unchecked

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

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

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

-- | Like <a>decode</a>, 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 <a>decoded</a>, 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 <tt>aeson</tt>, <tt>pipes</tt> and
--   <tt>pipes-parse</tt> libraries, and assumes you know how to use them.
--   Please read the examples in <a>Pipes.Parse.Tutorial</a> to understand
--   how to use these functions.
--   
--   In this module, the following type synonym compatible with the
--   <tt>lens</tt>, <tt>lens-family</tt> and <tt>lens-family-core</tt>
--   libraries is used but not exported:
--   
--   <pre>
--   type Lens' s a = forall f . <a>Functor</a> f =&gt; (a -&gt; f a) -&gt; (s -&gt; f s)
--   </pre>
module Pipes.Aeson

-- | Encode an <a>Array</a> as JSON and send it downstream,
--   
--   <i>Hint:</i> You can easily turn this <a>Producer'</a> into a
--   <a>Pipe</a> that encodes <a>Array</a> values as JSON as they flow
--   downstream using:
--   
--   <pre>
--   <a>for</a> <a>cat</a> <a>encodeArray</a> :: <a>Monad</a> m =&gt; <a>Pipe</a> <a>Array</a> <a>ByteString</a> m r
--   </pre>
encodeArray :: Monad m => Array -> Producer' ByteString m ()

-- | Encode an <a>Object</a> as JSON and send it downstream,
--   
--   <i>Hint:</i> You can easily turn this <a>Producer'</a> into a
--   <a>Pipe</a> that encodes <a>Object</a> values as JSON as they flow
--   downstream using:
--   
--   <pre>
--   <a>for</a> <a>cat</a> <a>encodeObject</a> :: <a>Monad</a> m =&gt; <a>Pipe</a> <a>Object</a> <a>ByteString</a> m r
--   </pre>
encodeObject :: Monad m => Object -> Producer' ByteString m ()

-- | Decodes an <a>Object</a> or <a>Array</a> JSON value from the
--   underlying state.
--   
--   It returns <a>Nothing</a> if the underlying <a>Producer</a> is
--   exhausted, otherwise it returns either the decoded entity or a
--   <a>DecodingError</a> in case of error.
--   
--   <i>Note:</i> The JSON RFC-4627 standard only allows arrays or objects
--   as top-level entities, which is why this <a>Parser</a> restricts its
--   output to them. If you prefer to ignore the standard and decode any
--   <a>Value</a>, then use <a>decode</a> from the
--   <a>Pipes.Aeson.Unchecked</a> module.
decode :: (Monad m, FromJSON a) => Parser ByteString m (Maybe (Either DecodingError a))

-- | <i>Improper lens</i> that turns a stream of raw JSON input into a
--   stream of <a>FromJSON</a> and back.
--   
--   By <i>improper lens</i> we mean that in practice you can't expect the
--   <i>Monad Morphism Laws</i> to be true when using <a>decoded</a> with
--   <a>zoom</a>.
--   
--   <pre>
--   <a>zoom</a> <a>decoded</a> (<a>return</a> r) /= <a>return</a> r
--   <a>zoom</a> <a>decoded</a> (m &gt;&gt;= k)  /= <a>zoom</a> m &gt;&gt;= <a>zoom</a> . f
--   </pre>
--   
--   <i>Note:</i> 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 <a>Value</a>, then use <a>decoded</a> from the
--   <a>Pipes.Aeson.Unchecked</a> 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 <a>decode</a>, 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 <a>decoded</a>, 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 <tt>attoparsec</tt> error that happened while parsing the raw JSON
--   string.
AttoparsecError :: ParsingError -> DecodingError

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