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


-- | Incremental applicative JSON parser
--   
--   Easy to use JSON parser fully supporting incremental parsing. Parsing
--   grammar in applicative form.
--   
--   The parser is compatibile with aeson and its FromJSON class. It is
--   possible to use aeson monadic parsing when appropriate.
--   
--   The parser supports constant-space safe incremental parsing regardless
--   of the input data. In addition to performance-critical parts written
--   in C, a lot of performance is gained by being less memory intensive
--   especially when used for stream parsing.
--   
--   <ul>
--   <li>WARNING: 0.4.0.0 has code-breaking semantic changes, see
--   changelog!</li>
--   </ul>
@package json-stream
@version 0.4.2.3


-- | An incremental applicative-style JSON parser, suitable for high
--   performance memory efficient stream parsing.
--   
--   The parser is using <a>Data.Aeson</a> types and <tt>FromJSON</tt>
--   instance, it can be easily combined with aeson monadic parsing
--   instances when appropriate.
module Data.JsonStream.Parser

-- | A representation of the parser.
data Parser a

-- | Result of parsing. Contains continuations to continue parsing.
data ParseOutput a

-- | Returns a value from a parser.
ParseYield :: a -> (ParseOutput a) -> ParseOutput a

-- | Parser needs more data to continue parsing.
ParseNeedData :: (ByteString -> ParseOutput a) -> ParseOutput a

-- | Parsing failed, error is reported.
ParseFailed :: String -> ParseOutput a

-- | Parsing finished, unparsed data is returned.
ParseDone :: ByteString -> ParseOutput a

-- | Run streaming parser, immediately returns <a>ParseNeedData</a>.
runParser :: Parser a -> ParseOutput a

-- | Run streaming parser with initial input.
runParser' :: Parser a -> ByteString -> ParseOutput a

-- | Parse a bytestring, generate lazy list of parsed values. If an error
--   occurs, throws an exception.
--   
--   <pre>
--   &gt;&gt;&gt; parseByteString (arrayOf integer) "[1,2,3,4]" :: [Int]
--   [1,2,3,4]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseByteString (arrayOf ("name" .: string)) "[{\"name\":\"KIWI\"}, {\"name\":\"BIRD\"}]"
--   ["KIWI","BIRD"]
--   </pre>
parseByteString :: Parser a -> ByteString -> [a]

-- | Parse a lazy bytestring, generate lazy list of parsed values. If an
--   error occurs, throws an exception.
parseLazyByteString :: Parser a -> ByteString -> [a]

-- | Deserialize a JSON value from lazy <a>ByteString</a>.
--   
--   If this fails due to incomplete or invalid input, <a>Nothing</a> is
--   returned.
--   
--   The input must consist solely of a JSON document, with no trailing
--   data except for whitespace.
decode :: FromJSON a => ByteString -> Maybe a

-- | Like <a>decode</a> but returns an error message when decoding fails.
eitherDecode :: FromJSON a => ByteString -> Either String a

-- | Like <a>decode</a>, but on strict <a>ByteString</a>
decodeStrict :: FromJSON a => ByteString -> Maybe a

-- | Like <a>eitherDecode</a>, but on strict <a>ByteString</a>
eitherDecodeStrict :: FromJSON a => ByteString -> Either String a

-- | Match <tt>FromJSON</tt> value. Calls parseJSON on the parsed value.
--   
--   <pre>
--   &gt;&gt;&gt; let json = "[{\"key1\": [1,2], \"key2\": [5,6]}]"
--   
--   &gt;&gt;&gt; parseByteString (arrayOf value) json :: [AE.Value]
--   [Object (fromList [("key2",Array [Number 5.0,Number 6.0]),("key1",Array [Number 1.0,Number 2.0])])]
--   </pre>
value :: FromJSON a => Parser a

-- | Parse string value, skip parsing otherwise.
string :: Parser Text

-- | Stops parsing string after the limit is reached. The string will not
--   be matched if it exceeds the size. The size is the size of escaped
--   string including escape characters.
safeString :: Int -> Parser Text

-- | Parse number, return in scientific format.
number :: Parser Scientific

-- | Parse to bounded integer type (not <a>Integer</a>). If you are using
--   integer numbers, use this parser. It skips the conversion JSON -&gt;
--   <a>Scientific</a> -&gt; <a>Int</a> and uses an <a>Int</a> directly.
integer :: forall i. (Integral i, Bounded i) => Parser i

-- | Parse to float/double.
real :: RealFloat a => Parser a

-- | Parse bool, skip if the type is not bool.
bool :: Parser Bool

-- | Match a null value.
jNull :: Parser ()

-- | Synonym for <a>objectWithKey</a>. Matches key in an object. The
--   <a>.:</a> operators can be chained.
--   
--   <pre>
--   &gt;&gt;&gt; let json = "{\"key1\": {\"nested-key\": 3}}"
--   
--   &gt;&gt;&gt; parseByteString ("key1" .: "nested-key" .: integer) json :: [Int]
--   [3]
--   </pre>
(.:) :: Text -> Parser a -> Parser a
infixr 7 .:

-- | Returns <a>Nothing</a> if value is null or does not exist or match.
--   Otherwise returns <a>Just</a> value.
--   
--   <pre>
--   key .:? val = optional (key .: val)
--   </pre>
(.:?) :: Text -> Parser a -> Parser (Maybe a)
infixr 7 .:?

-- | Return default value if the parsers on the left hand didn't produce a
--   result.
--   
--   <pre>
--   p .| defval = p &lt;|&gt; pure defval
--   </pre>
--   
--   The operator works on complete left side, the following statements are
--   equal:
--   
--   <pre>
--   Record &lt;$&gt;  "key1" .: "nested-key" .: value .| defaultValue
--   Record &lt;$&gt; (("key1" .: "nested-key" .: value) .| defaultValue)
--   </pre>
(.|) :: Parser a -> a -> Parser a
infixl 6 .|

-- | Synonym for <a>arrayWithIndexOf</a>. Matches n-th item in array.
--   
--   <pre>
--   &gt;&gt;&gt; parseByteString (arrayOf (1 .! bool)) "[ [1,true,null], [2,false], [3]]" :: [Bool]
--   [True,False]
--   </pre>
(.!) :: Int -> Parser a -> Parser a
infixr 7 .!

-- | Match only specific key of an object. This function will return only
--   the first matched value in an object even if the source JSON defines
--   the key multiple times (in violation of the specification).
objectWithKey :: Text -> Parser a -> Parser a

-- | Match all key-value pairs of an object, return them as a tuple. If the
--   source object defines same key multiple times, all values are matched.
objectItems :: Parser a -> Parser (Text, a)

-- | Match all key-value pairs of an object, return only values. If the
--   source object defines same key multiple times, all values are matched.
--   Keys are ignored.
objectValues :: Parser a -> Parser a

-- | Match all items of an array.
arrayOf :: Parser a -> Parser a

-- | Match nith item in an array.
arrayWithIndexOf :: Int -> Parser a -> Parser a

-- | Match all items of an array, add index to output.
indexedArrayOf :: Parser a -> Parser (Int, a)

-- | Parses a field with a possible null value.
nullable :: Parser a -> Parser (Maybe a)

-- | Let only items matching a condition pass.
--   
--   <pre>
--   &gt;&gt;&gt; parseByteString (filterI (&gt;5) $ arrayOf integer) "[1,2,3,4,5,6,7,8,9,0]" :: [Int]
--   [6,7,8,9]
--   </pre>
filterI :: (a -> Bool) -> Parser a -> Parser a

-- | Take maximum n matching items.
--   
--   <pre>
--   &gt;&gt;&gt; parseByteString (takeI 3 $ arrayOf integer) "[1,2,3,4,5,6,7,8,9,0]" :: [Int]
--   [1,2,3]
--   </pre>
takeI :: Int -> Parser a -> Parser a

-- | A back-door for lifting of possibly failing actions. If an action
--   fails with Left value, convert it into failure of parsing
mapWithFailure :: (a -> Either String b) -> Parser a -> Parser b

-- | Generate start/end values when an array is found, in between run a
--   parser. The inner parser is not run if an array is not found.
--   
--   <pre>
--   &gt;&gt;&gt; let test = "[[1,2,3],true,[],false,{\"key\":1}]" :: BS.ByteString
--   
--   &gt;&gt;&gt; parseByteString (arrayOf (arrayFound 10 20 (1 .! integer))) test :: [Int]
--   [10,2,20,10,20]
--   </pre>
arrayFound :: a -> a -> Parser a -> Parser a

-- | Generate start/end values when an object is found, in between run a
--   parser. The inner parser is not run if an array is not found.
objectFound :: a -> a -> Parser a -> Parser a
instance GHC.Base.Functor Data.JsonStream.Parser.ParseResult
instance GHC.Base.Functor Data.JsonStream.Parser.Parser
instance GHC.Base.Applicative Data.JsonStream.Parser.Parser
instance GHC.Base.Monoid (Data.JsonStream.Parser.Parser a)
instance Data.Semigroup.Semigroup (Data.JsonStream.Parser.Parser a)
instance GHC.Base.Alternative Data.JsonStream.Parser.Parser
