For Gauche 0.9.10


Next: , Previous: , Up: ライブラリモジュール - SRFI   [Contents][Index]

11.35 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のパーズと構築). 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のパーズと構築, 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:

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のパーズと構築).

(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} Read 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.

Returns a list of read JSON values. A <json-parse-error> is thrown if it encounters invalid JSON text.

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

[SRFI-180] {srfi-180} Read JSON Text Sequence format (RFC7464, https://tools.ietf.org/html/rfc7464) from port-or-generator, which 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のパーズと構築).

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.


Next: , Previous: , Up: ライブラリモジュール - SRFI   [Contents][Index]