11.37 srfi-180 - JSON

Module: srfi-180

This srfi defines the means of parsing and constructin JSON.

In Gauche, this module is implemented on top of rfc.json module (see JSON parsing and construction). Notably, the parameter json-nesting-depth-limit is the same as the one in rfc.json.

Gauche’s rfc.json is more flexible in terms of mapping JSON objects to Scheme objects. On the other hand, srfi-180 provides a streaming parser/generator, which allows the caller to process input as it is read, instead of waiting the entire input to be parsed.

Predicates and parameters

Function: json-error? obj

[SRFI-180] {srfi-180} JSON reader and writer raise a condition that satisfies this predicate when it encounters invalid JSON syntax and/or object, or the input exceeds the limits specified by json-nesting-depth-limit or json-number-of-character-limit parameters.

Since srfi-180 is implemented on top of rfc.json, which raises a condition <json-parse-error> for input and <json-construct-error> for the output, this predicate simply returns #t iff obj is an instance of either class. See JSON parsing and construction, for the detail of these conditions.

Function: json-error-reason err

[SRFI-180] {srfi-180} Returns a string explaining the reasonfor the error err, if err is a JSON error object (an object that satisfies json-error?).

In Gauche, a JSON error object is an instance of either <json-parse-error> or <json-construct-error>) conditions, and json-error-reason simply returns the content of its message slot.

Function: json-null? obj

[SRFI-180] {srfi-180} Returns #t iff obj is the symbol null.

Parameter: json-number-of-character-limit

[SRFI-180] {srfi-180} A parameter that holds a real value. If the number of characters of input JSON text exceeds the value while json-generator, json-fold or json-read is processing the input, a JSON error is thrown.

JSON reader

Function: json-generator :optional port-or-generator

[SRFI-180] {srfi-180} Streaming parser. The input port-or-generator must be an input port, or a char generator.

Each time it is called, it returns one of the following values, parsed from the input.

string

JSON string.

real number

JSON number.

#t, #f

JSON true and false

null

JSON null

array-start

The beginning of an array. What follows is the array’s element, up to the matching array-end.

array-end

The ending of an array.

object-start

The beginning of an object. What follows is alternating string keys and JSON values, up to the matching object-end.

object-end

The ending of an object.

EOF

After one top-level JSON value is read, the generator returns EOF.

The generator internally tracks the state, and raises <json-parse-error> when the input contains invalid JSON text. See also json-error? above.

If the input contains more than one toplevel JSON value, you have to call json-generator after the previous generator is exhausted.

Note that if a toplevel JSON value is a number, true, false or null, the parser need to read one character ahead to recognize the value. So the subsequent call of json-generator won’t read a character immediately following those values.

Generally, multiple toplevel values uses delimiters for each values so it won’t be an issue. See json-lines-read and json-sequence-read below.

Function: json-fold proc array-start array-end object-start object-end seed :optional port-or-generator

[SRFI-180] {srfi-180} A procedure to translate JSON pasring result to Scheme object on the fly.

The port-or-generator argument is either an input port, or a char generator, defaulted to the current input port. It is first passed to json-generator to get a generator of parser events. Then, json-fold retrieves value from the generator and take one of the following actions:

• If it generates a string, a number, a boolean or null, calls (proc obj seed) where obj is the generated value and seed is the current seed value, and make the result a new seed value.
• If it generates array-start, save the current seed, calls (array-start seed) and make the result a new seed value.
• If it generates array-end, calls (array-end seed), let the result be arr, recover the seed value saved at the corresponding array-start, and calls (proc arr recovered-seed). Let the result a new seed value.
• If it generates object-start, save the current seed, calls (object-start seed) and make the result a new seed value.
• If it generates object-end, calls (object-end seed), let the result be obj, recover the seed value saved at the corresponding object-start, and calls (proc obj recovered-seed). Let the result a new seed value.
• If it generates EOF, returns the seed value as the result of json-fold.

Function: json-read :optional port-or-generator

[SRFI-180] {srfi-180} Read one JSON value or object from port-or-generator, which should be an input port or a char generator. If it is omitted, the current input port is used.

JSON strings and numbers are mapped to Scheme strings and numbers. JSON true and false become #t and #f. JSON null becomes a symbol null. JSON arrays become Scheme vectors, and JSON objects become Scheme alist, in which keys are converted to symbols.

If the input contains invalid JSON text, a <json-parse-error> is thrown.

See also parse-json in rfc.json (see JSON parsing and construction).

(call-with-input-string
  "[{\"a\":1}, {\"b\":true, \"c\":\"foo\"}, null]"
  json-read)
  ⇒ #(((a . 1))
      ((b . #t) (c . "foo"))
      null)

Function: json-lines-read :optional port-or-generator

[SRFI-180] {srfi-180} Returns a generator that yields a JSON values at a time, read from the source in JSON Lines format (http://jsonlines.org/), which contains multiple toplevel JSON values separated with #\newline. The input port-or-generator should be an input port or a char generator, defaulted to the current input port.

See json-read above about the mapping from JSON values to Scheme values.

Function: json-sequence-read :optional port-or-generator

[SRFI-180] {srfi-180} Returns a generator that yields a JSON values at a time, read from the source in JSON Text Sequence format (RFC7464, https://tools.ietf.org/html/rfc7464). The input port-or-generator should be an input port or a char generator, defaulted to the current input port.

JSON Text Sequence can contain multiple JSON values, each one leaded by one or more consecutive U+001E. If it encounters text unparsable as JSON, that segment (until next U+001E) is silently ignored. Returns a list of read JSON values.

See json-read above about the mapping from JSON values to Scheme values.

See also construct-json in rfc.json (see JSON parsing and construction).

JSON writer

Function: json-accumulator port-or-accumlator

[SRFI-180] {srfi-180} This is dual to json-generator. The port-or-accumulator should be an output port or an accumulator that accepts a character or a string. This procedure returns an accumulator that accepts the events such as json-generator generates.

Function: json-write obj :optional port-or-accumulator

[SRFI-180] {srfi-180} Write obj as a JSON to port-or-accumulator, which must be an output port or an accumulator that accepts a character or a string.