Type class for encode & decode JSON.

A JSON value represented as a Haskell value.

The Object's payload is a key-value vector instead of a map, which parsed directly from JSON document. This design choice has following advantages:

• Allow different strategies handling duplicated keys.
• Allow different Map type to do further parsing, e.g. FlatMap
• Roundtrip without touching the original key-value order.
• Save time if constructing map is not neccessary, e.g. using a linear scan to find a key if only that key is needed.

Settings T.pack T.pack False

Generic encode/decode Settings

There should be no control characters in formatted texts since we don't escaping those field names or constructor names (defaultSettings relys on Haskell's lexical property). Otherwise encodeJSON will output illegal JSON string.

Decode a JSON bytes, return any trailing bytes.

Decode a JSON doc, only trailing JSON whitespace are allowed.

Decode a JSON text, return any trailing text.

Decode a JSON doc, only trailing JSON whitespace are allowed.

Type alias for a streaming parser, draw chunk from Monad m with a initial chunk, return result in Either err x.

Decode a JSON doc chunk.

Decode JSON doc chunks, return trailing bytes.

Directly encode data to JSON bytes.

This function use buildWith smallChunkSize to balance common use case, if you need fine tuning on memory usage, please use buildWith and a custom initial chunk size with encodeJSON.

Encode data to JSON bytes chunks.

Text version encode.

Directly encode data to JSON bytes.

'ValuePretty'' with 4 spaces indentation per level, e.g.

{
    "results":
    [
        {
            "from_user_id_str":"80430860",
            "profile_image_url":"http://a2.twimg.com/profile_images/536455139/icon32_normal.png",
            "created_at":"Wed, 26 Jan 2011 07:07:02 +0000",
            "from_user":"kazu_yamamoto",
            "id_str":"30159761706061824",
            "metadata":
            {
                "result_type":"recent"
            },
            "to_user_id":null,
            "text":"Haskell Server Pages って、まだ続いていたのか！",
            "id":30159761706061824,
            "from_user_id":80430860,
            "geo":null,
            "iso_language_code":"no",
            "to_user_id_str":null,
            "source":"<a href="http:/twitter.com">web</a>"
        }
    ],
    "max_id":30159761706061824,
    "since_id":0,
    "refresh_url":"?since_id=30159761706061824&q=haskell",
    "next_page":"?page=2&max_id=30159761706061824&rpp=1&q=haskell",
    "results_per_page":1,
    "page":1,
    "completed_in":1.2606e-2,
    "since_id_str":"0",
    "max_id_str":"30159761706061824",
    "query":"haskell"
}

Parse Value without consuming trailing bytes.

Parse Value, and consume all trailing JSON white spaces, if there're bytes left, parsing will fail.

Run a Converter with input value.

Converter provides a monadic interface to convert protocol IR (e.g.Value) to Haskell ADT.

Text version of fail.

Add (JSON) Path context to a converter

When converting a complex structure, it helps to annotate (sub)converters with context, so that if an error occurs, you can find its location.

withFlatMapR "Person" $ \o ->
  Person
    <$> o .: "name" <?> Key "name"
    <*> o .: "age" <?> Key "age"

(Standard methods like (.:) already do this.)

With such annotations, if an error occurs, you will get a (JSON) Path location of that error.

Add context to a failure message, indicating the name of the structure being converted.

prependContext "MyType" (fail "[error message]")
-- Error: "converting MyType failed, [error message]"

Elements of a (JSON) Value path used to describe the location of an error.

Error info with (JSON) Path info.

Produce an error message like converting XXX failed, expected XXX, encountered XXX.

withScientific name f value applies f to the Scientific number when value is a Number and fails using typeMismatch otherwise.

Warning: If you are converting from a scientific to an unbounded type such as Integer you may want to add a restriction on the size of the exponent (see withBoundedScientific) to prevent malicious input from filling up the memory of the target system.

Error message example

withScientific "MyType" f (String "oops")
-- Error: "converting MyType failed, expected Number, but encountered String"

withBoundedScientific name f value applies f to the Scientific number when value is a Number with exponent less than or equal to 1024.

@withRealFloat try to convert floating number with following rules:

• Use ±Infinity to represent out of range numbers.
• Convert Null as NaN

withBoundedScientific name f value applies f to the Scientific number when value is a Number and value is within minBound ~ maxBound.

Directly use Object as key-values for further converting.

Take a Object as an 'FM.FlatMap T.Text Value', on key duplication prefer first one.

Take a Object as an 'FM.FlatMap T.Text Value', on key duplication prefer last one.

Take a Object as an 'HM.HashMap T.Text Value', on key duplication prefer first one.

Take a Object as an 'HM.HashMap T.Text Value', on key duplication prefer last one.

Decode a nested JSON-encoded string.

Retrieve the value associated with the given key of an Object. The result is empty if the key is not present or the value cannot be converted to the desired type.

This accessor is appropriate if the key and value must be present in an object for it to be valid. If the key and value are optional, use .:? instead.

Retrieve the value associated with the given key of an Object. The result is Nothing if the key is not present or if its value is Null, or fail if the value cannot be converted to the desired type.

This accessor is most useful if the key and value can be absent from an object without affecting its validity. If the key and value are mandatory, use .: instead.

Retrieve the value associated with the given key of an Object. The result is Nothing if the key is not present or fail if the value cannot be converted to the desired type.

This differs from .:? by attempting to convert Null the same as any other JSON value, instead of interpreting it as Nothing.

Variant of .:? with explicit converter function.

Variant of .:! with explicit converter function.

Connect key and value to a tuple to be used with object.

Alias for Object . pack.

Connect key and value to a KVItem using colon, key will be escaped.

Add curly for comma connected KVItems.

A newtype for Builder, whose semigroup's instance is to connect two builder with comma.

Use : as separator to connect a label(no escape, only add quotes) with field builders.

Don't use chars which need escaped in label.

Use : as separator to connect a label(escape the label and add quotes) with field builders.

Escape text into JSON string and add double quotes, escaping rules:

   '\b':  "\b"
   '\f':  "\f"
   '\n':  "\n"
   '\r':  "\r"
   '\t':  "\t"
   '"':  "\""
   '\':  "\\"
   'DEL':  "\u007f"
   other chars <= 0x1F: "\u00XX"

add {...} to original builder.

add [...] to original builder.

Use , as separator to connect list of builders.

Use , as separator to connect a vector of builders.