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


-- | Parsing of aeson's Value with attoparsec
--   
--   Parsing of aeson's Value with attoparsec, originally from aeson.
@package attoparsec-aeson
@version 2.2.2.0


-- | Efficiently and correctly parse a JSON string. The string must be
--   encoded as UTF-8.
module Data.Aeson.Parser.Internal

-- | Parse any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for <a>value</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith</a>.
json :: Parser Value

-- | Parse a top-level JSON value followed by optional whitespace and
--   end-of-input. See also: <a>json</a>.
jsonEOF :: Parser Value

-- | Parse any JSON value.
--   
--   This parser is parameterized by a function to construct an
--   <a>Object</a> from a raw list of key-value pairs, where duplicates are
--   preserved. The pairs appear in <b>reverse order</b> from the source.
--   
--   <h4><b>Examples</b></h4>
--   
--   <a>json</a> keeps only the first occurrence of each key, using
--   <a>fromList</a>.
--   
--   <pre>
--   <a>json</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromList</a>)
--   </pre>
--   
--   <a>jsonLast</a> keeps the last occurrence of each key, using
--   <tt><a>fromListWith</a> (<a>const</a> <a>id</a>)</tt>.
--   
--   <pre>
--   <a>jsonLast</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromListWith</a> (<a>const</a> <a>id</a>))
--   </pre>
--   
--   <a>jsonAccum</a> keeps wraps all values in arrays to keep duplicates,
--   using <a>fromListAccum</a>.
--   
--   <pre>
--   <a>jsonAccum</a> = <a>jsonWith</a> (<a>Right</a> . <a>fromListAccum</a>)
--   </pre>
--   
--   <a>jsonNoDup</a> fails if any object contains duplicate keys, using
--   <a>parseListNoDup</a>.
--   
--   <pre>
--   <a>jsonNoDup</a> = <a>jsonWith</a> <a>parseListNoDup</a>
--   </pre>
jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json</a> which keeps only the last occurrence of every
--   key.
jsonLast :: Parser Value

-- | Variant of <a>json</a> wrapping all object mappings in <a>Array</a> to
--   preserve key-value pairs with the same keys.
jsonAccum :: Parser Value

-- | Variant of <a>json</a> which fails if any object contains duplicate
--   keys.
jsonNoDup :: Parser Value

-- | Parse any JSON value. Synonym of <a>json</a>.
value :: Parser Value

-- | Parse a quoted JSON string.
jstring :: Parser Text

-- | Parse a string without a leading quote.
jstring_ :: Parser Text

-- | Parse a JSON number.
scientific :: Parser Scientific

-- | Parse any JSON value.
--   
--   This is a strict version of <a>json</a> which avoids building up
--   thunks during parsing; it performs all conversions immediately. Prefer
--   this version if most of the JSON data needs to be accessed.
--   
--   This function is an alias for <a>value'</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith'</a>.
json' :: Parser Value

-- | Parse a top-level JSON value followed by optional whitespace and
--   end-of-input. See also: <a>json'</a>.
jsonEOF' :: Parser Value

-- | Strict version of <a>jsonWith</a>.
jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json'</a> which keeps only the last occurrence of every
--   key.
jsonLast' :: Parser Value

-- | Variant of <a>json'</a> wrapping all object mappings in <a>Array</a>
--   to preserve key-value pairs with the same keys.
jsonAccum' :: Parser Value

-- | Variant of <a>json'</a> which fails if any object contains duplicate
--   keys.
jsonNoDup' :: Parser Value

-- | Strict version of <a>value</a>. Synonym of <a>json'</a>.
value' :: Parser Value
decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a

-- | <tt><a>fromListAccum</a> kvs</tt> is an object mapping keys to arrays
--   containing all associated values from the original list <tt>kvs</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; fromListAccum [("apple", Bool True), ("apple", Bool False), ("orange", Bool False)]
--   fromList [("apple",Array [Bool False,Bool True]),("orange",Array [Bool False])]
--   </pre>
fromListAccum :: [(Key, Value)] -> Object

-- | <tt><tt>fromListNoDup</tt> kvs</tt> fails if <tt>kvs</tt> contains
--   duplicate keys.
parseListNoDup :: [(Key, Value)] -> Either String Object

-- | Unescape JSON text literal.
--   
--   This function is exporeted mostly for testing and benchmarking
--   purposes.
unescapeText :: ByteString -> Either UnicodeException Text


-- | Efficiently and correctly parse a JSON string. The string must be
--   encoded as UTF-8.
--   
--   It can be useful to think of parsing as occurring in two phases:
--   
--   <ul>
--   <li>Identification of the textual boundaries of a JSON value. This is
--   always strict, so that an invalid JSON document can be rejected as
--   soon as possible.</li>
--   <li>Conversion of a JSON value to a Haskell value. This may be either
--   immediate (strict) or deferred (lazy); see below for details.</li>
--   </ul>
--   
--   The question of whether to choose a lazy or strict parser is subtle,
--   but it can have significant performance implications, resulting in
--   changes in CPU use and memory footprint of 30% to 50%, or occasionally
--   more. Measure the performance of your application with each!
module Data.Aeson.Parser

-- | Parse any JSON value.
--   
--   The conversion of a parsed value to a Haskell value is deferred until
--   the Haskell value is needed. This may improve performance if only a
--   subset of the results of conversions are needed, but at a cost in
--   thunk allocation.
--   
--   This function is an alias for <a>value</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith</a>.
json :: Parser Value

-- | Parse any JSON value. Synonym of <a>json</a>.
value :: Parser Value

-- | Parse a quoted JSON string.
jstring :: Parser Text

-- | Parse a JSON number.
scientific :: Parser Scientific

-- | Parse any JSON value.
--   
--   This parser is parameterized by a function to construct an
--   <a>Object</a> from a raw list of key-value pairs, where duplicates are
--   preserved. The pairs appear in <b>reverse order</b> from the source.
--   
--   <h4><b>Examples</b></h4>
--   
--   <a>json</a> keeps only the first occurrence of each key, using
--   <a>fromList</a>.
--   
--   <pre>
--   <a>json</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromList</a>)
--   </pre>
--   
--   <a>jsonLast</a> keeps the last occurrence of each key, using
--   <tt><a>fromListWith</a> (<a>const</a> <a>id</a>)</tt>.
--   
--   <pre>
--   <a>jsonLast</a> = <a>jsonWith</a> (<a>Right</a> <a>.</a> <a>fromListWith</a> (<a>const</a> <a>id</a>))
--   </pre>
--   
--   <a>jsonAccum</a> keeps wraps all values in arrays to keep duplicates,
--   using <a>fromListAccum</a>.
--   
--   <pre>
--   <a>jsonAccum</a> = <a>jsonWith</a> (<a>Right</a> . <a>fromListAccum</a>)
--   </pre>
--   
--   <a>jsonNoDup</a> fails if any object contains duplicate keys, using
--   <a>parseListNoDup</a>.
--   
--   <pre>
--   <a>jsonNoDup</a> = <a>jsonWith</a> <a>parseListNoDup</a>
--   </pre>
jsonWith :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json</a> which keeps only the last occurrence of every
--   key.
jsonLast :: Parser Value

-- | Variant of <a>json</a> wrapping all object mappings in <a>Array</a> to
--   preserve key-value pairs with the same keys.
jsonAccum :: Parser Value

-- | Variant of <a>json</a> which fails if any object contains duplicate
--   keys.
jsonNoDup :: Parser Value

-- | Parse any JSON value.
--   
--   This is a strict version of <a>json</a> which avoids building up
--   thunks during parsing; it performs all conversions immediately. Prefer
--   this version if most of the JSON data needs to be accessed.
--   
--   This function is an alias for <a>value'</a>. In aeson 0.8 and earlier,
--   it parsed only object or array types, in conformance with the
--   now-obsolete RFC 4627.
--   
--   <h4>Warning</h4>
--   
--   If an object contains duplicate keys, only the first one will be kept.
--   For a more flexible alternative, see <a>jsonWith'</a>.
json' :: Parser Value

-- | Strict version of <a>value</a>. Synonym of <a>json'</a>.
value' :: Parser Value

-- | Strict version of <a>jsonWith</a>.
jsonWith' :: ([(Key, Value)] -> Either String Object) -> Parser Value

-- | Variant of <a>json'</a> which keeps only the last occurrence of every
--   key.
jsonLast' :: Parser Value

-- | Variant of <a>json'</a> wrapping all object mappings in <a>Array</a>
--   to preserve key-value pairs with the same keys.
jsonAccum' :: Parser Value

-- | Variant of <a>json'</a> which fails if any object contains duplicate
--   keys.
jsonNoDup' :: Parser Value
decodeWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
decodeStrictWith :: Parser Value -> (Value -> Result a) -> ByteString -> Maybe a
eitherDecodeWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
eitherDecodeStrictWith :: Parser Value -> (Value -> IResult a) -> ByteString -> Either (JSONPath, String) a
