Data.JsonStream.Parser

An incremental applicative-style JSON parser, suitable for high performance memory efficient stream parsing.

The parser is using Data.Aeson types and FromJSON instance, it can be easily combined with aeson monadic parsing instances when appropriate.

How to use this library

>>> parseByteString value "[1,2,3]" :: [[Int]]
[[1,2,3]]

The value parser matches any FromJSON value. The above command is essentially identical to the aeson decode function; the parsing process can generate more objects, therefore the results is [a].

json-stream style parsing would rather look like this:

>>> parseByteString (array value) "[1,2,3]" :: [Int]
[1,2,3]

Parsers can be combinated using <*> and <|> operators. These operators cause parallel parsing and yield some combination of the parsed values.

JSON: text = [{"name": "John", "age": 20}, {"age": 30, "name": "Frank"} ]
>>> let parser = array $ (,) <$> objectWithKey "name" value
                             <*> objectWithKey "age" value
>>> parseByteString  parser text :: [(Text,Int)]
[("John",20),("Frank",30)]

When parsing larger values, it is advisable to use lazy ByteStrings as the chunking of the ByteStrings causes the parsing to continue more efficently because less state is needed to be held in memory with parallel parsers.

More examples are available on https://github.com/ondrap/json-stream.

The Parser type

data Parser a

A representation of the parser.

Instances

Alternative Parser

Functor Parser

Applicative Parser

data ParseOutput a

Result of parsing. Contains continuations to continue parsing.

Constructors

ParseYield a (ParseOutput a)

Returns a value from a parser.

ParseNeedData (ByteString -> ParseOutput a)

Parser needs more data to continue parsing.

ParseFailed String

Parsing failed, error is reported.

ParseDone ByteString

Parsing finished, unparsed data is returned.

Parsing functions

runParser :: Parser a -> ParseOutput a

Run streaming parser, immediately returns ParseNeedData.

runParser' :: Parser a -> ByteString -> ParseOutput a

Run streaming parser with initial input.

parseByteString :: Parser a -> ByteString -> [a]

Parse a bytestring, generate lazy list of parsed values. If an error occurs, throws an exception.

parseLazyByteString :: Parser a -> ByteString -> [a]

Parse a lazy bytestring, generate lazy list of parsed values. If an error occurs, throws an exception.

Basic JSON parsers

value :: FromJSON a => Parser a

Match FromJSON value.

objectWithKey :: Text -> Parser a -> Parser a

Match only specific key of an object.

objectItems :: Parser a -> Parser (Text, a)

Match all key-value pairs of an object, return them as a tuple.

objectValues :: Parser a -> Parser a

Match all key-value pairs of an object, return only values.

array :: Parser a -> Parser a

Match all items of an array.

arrayWithIndex :: Int -> Parser a -> Parser a

Match n'th item of an array.

indexedArray :: Parser a -> Parser (Int, a)

Match all items of an array, add index to output.

Parsing modifiers

filterI :: (a -> Bool) -> Parser a -> Parser a

Let only items matching a condition pass

toList :: Parser a -> Parser [a]

Fetch yields of a function and return them as list.

defaultValue :: a -> Parser a -> Parser a

Returns a value if none is found upstream.

catchFail :: Parser a -> Parser a

Catch an error in underlying parser.