11.39 srfi.180 - JSON

Module: srfi.180 ¶

このsrfiはJSONフォーマットをパーズ、および構築する手段を定義します。

Gaucheでは、このモジュールはrfc.jsonの上に実装されています (rfc.json - JSONのパーズと構築参照)。 特に、json-nesting-depth-limitパラメータはrfc.jsonのものと同じです。

Gaucheのrfc.jsonは、JSONオブジェクトとSchemeオブジェクト間のマッピングを カスタマイズできるという点でより柔軟です。一方、 srfi.180はストリーミングパーザとジェネレータを提供しており、 入力を全て読んでからパーズ結果を得るのではなく、入力を読みながら処理することができます。

述語とパラメータ

Function: json-error? obj ¶

[SRFI-180]{srfi.180} JSONのリーダとライターは、不正なJSON構文や、JSONで表現できないオブジェクトに 行き当たった場合、あるいは入力がパラメータjson-nesting-depth-limitや やjson-number-of-character-limitで示される限度を越えた場合に、 この述語を満たすコンディションオブジェクトを投げます。

Gaucheではsrfi.180はrfc.json上に実装されていて、 rfc.jsonはパーズ時のエラーには<json-parse-error>を、 構築時のエラーには<json-construct-error>を投げるので、 この述語はobjがそれらのクラスのどちらかのインスタンスであれば #tを返します。 これらのコンディションについてはrfc.json - JSONのパーズと構築を参照してください。

Function: json-error-reason err ¶

[SRFI-180]{srfi.180} errがJSONエラーオブジェクト (json-error?を満たすオブジェクト) であった場合、エラーの理由を説明する文字列を返します。

GaucheではJSONエラーオブジェクトは<json-parse-error>か <json-construct-error>コンディションタイプのインスタンスであり、 json-error-reasonは単にコンディションオブジェクトのmessageスロットの 値を返します。

Function: json-null? obj ¶

[SRFI-180]{srfi.180} objがシンボルnullであれば#tを、そうでなければ#fを返します。

Parameter: json-number-of-character-limit ¶

[SRFI-180]{srfi.180} 実数を値に持つパラメータです。json-generator、json-fold、 およびjson-readで入力のJSONテキストの文字数がこの値を越えた場合、 JSONエラーが投げられます。

JSONリーダ

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

[SRFI-180]{srfi.180} ストリーミングパーザ。 port-or-generatorは入力ポートか、文字のジェネレータでなければなりません。

この手続きは、呼ばれる度に、必要なだけ入力を読んで次のいずれかの値を返します。

文字列

JSON文字列

実数

JSON数値

#t, #f

JSONのtrueとfalse

null

JSONのnull

array-start

配列の開始。次に対応するarray-endが出てくるまで、 配列の要素をストリーミングで返す。

array-end

配列の終了。

object-start

オブジェクトの開始。この後、文字列のキーとJSONの値が交互に返される。 終了はobject-endで示される。

object-end

オブジェクトの終了。

EOF

ひとつのトップレベルのJSON値が全て読まれたら、ジェネレータは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のパーズと構築).

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

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.