11.39 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 rfc.json - 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 rfc.json - JSON parsing and construction, for the detail of these conditions.

Function: json-error-reason err ¶

[SRFI-180]{srfi.180} Returns a string explaining the reason for 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 rfc.json - 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 rfc.json - 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.