std:json — JSON 直列化 (decode / parse / stringify)
標準ライブラリモジュール (index.md)。本書中の裸の §N は本書の節を指す。言語の意味論は ../language-spec.md を参照。
import json := "std:json" は decode / parse / stringify と型 Value を公開する namespace object を json に束縛する。Hikari のネイティブ値と JSON テキストを双方向に写すコーデック。外部システムとのデータ交換 (設定ファイル・API・ログ等) のための基盤である。
std:fs / std:term と違い I/O を伴わず、純粋・同期 (Future を返さない)。parse / stringify は String 上の純粋関数で、テキストの読み書き自体は呼び出し側が std:fs 等で行う。
import json := "std:json" import { decode, parse, stringify } := "std:json" type User := { name: String, age: Int, tags: List(String) |} match decode("{\"name\":\"a\",\"age\":30,\"tags\":[\"x\",\"y\"]}", type User) { Ok(u) => print(u.name) # "a" (u の静的型は User) Err(e) => print(e.message) # 構文不正・型不一致のいずれも Err } # スキーマが分からない場合は Value のタグで分岐する (§1) match parse(text) { Ok(json.Value.Object(m)) => match m.get("name") { Some(json.Value.String(name)) => print(name) _ => print("?") } Ok(_) => print("object expected") Err(e) => print(e.message) } stringify({ name := "a", age := 30 |}, 0) #> Ok("{\"name\":\"a\",\"age\":30}")
| 名前 | 形 | 意味 |
|---|---|---|
decode |
decode(text, type T) |
JSON テキスト text を 型 T の値として復号し、Result(T) を返す (同期)。型が合わなければ Err。§2.1 |
parse |
parse(text) |
JSON テキスト text を Value へ復号し、Result(Value) を返す (同期)。スキーマが実行時にしか分からない場合に使う |
stringify |
stringify(value, indent) |
Hikari 値 value を JSON テキストへ符号化し、Result を返す (同期)。indent が 0 ならコンパクト。省略できない (index.md) |
本モジュールは効果を1 つも持たない(../language-spec.md §17.9)。
スキーマが分かっているなら decode を使う。 結果型は Result(T) で、入力の型違いは Err になる。
スキーマが分からない場合は parse の Result(Value) を使い、タグで値の種類を判定して payload を取り出す。
以下の例では import json := "std:json" で束縛したものとして json.parse 等で記す。
1. 値と JSON の対応
std:json は JSON の値を表す enum Value を型メンバーとして公開する (json.Value)。
enum Value := { export { Null, Bool(value), Int(value), Float(value), String(value), Array(value), Object(value) }, Null := {}, Bool := { value: Bool |}, Int := { value: Int |}, Float := { value: Float |}, String := { value: String |}, Array := { value: List(Value) |}, Object := { value: InsertionMap(String, Value) |} | OneOf(Null, Bool, Int, Float, String, Array, Object) }
parse は各 JSON 値を対応するタグで包む。object のキーは文字列で、値は再帰的に Value になる。
stringify は Value を受理し、タグが表す JSON 種別へ写す。一般の enum を対応外とする規則の例外である。
Hikari の値には JSON に写せないもの (関数・タプル・Bytes・range) がある。std:json は次の値を扱い、読み戻しの型と正規化を §5 に定める。対応は次のとおり:
| Hikari 値 | JSON | 備考 |
|---|---|---|
| Int | number | Int は任意精度 (language-spec.md §7)。number は整数値のみ受理する。詳細は §3 / §4 |
| Float | number | 表記は言語の正準形 (最短往復形。小数点も指数も含まないときは .0 を補う。§4)。parse は整数値でない number を Value.Float へ復号する (§3)。整数値の Float (2.0) は parse では Value.Int へ戻るので、Float のまま読み戻すには型を宣言して decode を使う (§5) |
| String | string | UTF-8。要素は rune (language-spec.md §7.2.1) |
| Bool | bool | true / false |
Unit () |
null | |
| List | array | 順序を保つ |
InsertionMap(String, V) (map.md) |
object | 値 V が符号化に対応すること。キーの順序を保つ。parse は Value.Object の payload に InsertionMap(String, Value) を持つ |
Option(E) |
null / E の写像 |
stringify の入力としてのみ受理する。None は null、Some(v) は v を写したものになる (Some の包みは JSON に出ない)。null は Unit () と区別できないので、読み戻しは型を宣言して decode を使う (§2.1 の Option(E)・§5) |
| record (body 省略) | object | stringify の入力としてのみ受理する。スロット宣言順を保つ。受理の条件は値の種別ではなく属性 — body が省略形 (language-spec.md §2.2) で、全スロットが値を持つ (束縛済みまたはデフォルト値あり) こと |
JSON に写せない Hikari 値 (stringify は落とさずに Err({ kind := "unsupported", … |}) を返す。§6):
| Hikari 値 | 理由 |
|---|---|
| 関数 / body 持ちオブジェクト (closure) | JSON に振る舞いの表現が無い |
| Tuple | JSON に対応物が無く、array にすると List と区別できない (復元で曖昧、language-spec.md §7.3) |
| Bytes | JSON に生バイト列の表現が無い (base64 等の規約は持ち込まない)。テキスト化したいなら b.to_string! で String にしてから渡す (language-spec.md §7.2.2) |
Option / json.Value 以外のタグ付きの値 (enum の値・Result) |
JSON にタグの表現が無い (タグ名を持ち込む規約は置かない) |
| range (遅延シーケンス) | 直接は写せない。array にしたいなら r.map({ x | x }) 等で List に実体化してから渡す (language-spec.md §7.6) |
Float は有限値なら写せるが、NaN / ±Inf は JSON に number 表現が無いため stringify が Err({ kind := "unsupported", … |}) を返す (§4)。
2. json.decode
- 引数:
text(String) と型引数type Tの 2 個。Tは呼び出しで埋める型スロットへの実引数で、型式として読む (language-spec.md §17.4.1)。型でないものを書くと静的エラーになる。textが非 String なら静的エラーになる。 - 同期。
Resultを直接返す - 戻り値:
Result(T, Error) - 成功時:
Ok(v)—vは型Tの値。v.matches(type T)は真である - 失敗時:
Err(e)—eは回復可能エラーオブジェクト{ kind, message |}(§6)
復号は 2 段で行う。まず JSON テキストを構文解析し、次に T に沿って Hikari 値を組み立てる。 型は復号の指示であって事後の検査ではない — 同じ JSON でも T が違えば違う形の値になる (object を record に組むか InsertionMap に組むかなど)。
decode(text, type json.Value) は parse(text) と同じ値を返す。
json.Value は対象型のどの位置にも書ける。部分的に形が分からないフィールドやコンテナー要素にも使える。
2.1 型ごとの復号規則
T |
受理する JSON | 規則 |
|---|---|---|
Int |
number | 整数値のみ (§3 の parse と同じ規則)。小数は type_mismatch (下記) |
Float |
number | 整数・小数のいずれも受理し Float にする |
String |
string | |
Bool |
bool | |
Unit |
null | |
Option(E) |
null / E が受理するもの |
null は None。キー自体が無い場合も None (§2.2)。それ以外は Some に包む |
List(E) |
array | 各要素を E で復号 |
| Tuple | array | 要素数が一致すること。各要素を対応する型で復号 |
| record | object | 宣言フィールドだけを取り出す。詳細は §2.2 |
InsertionMap(String, V) (map.md) |
object | キーは String のまま写し、各値を V で復号する。InsertionMap(String, json.Value) なら各値を Value として復号する。キー型が String 以外の InsertionMap(K, V) は対応外 (JSON のキーは常に文字列) |
NonZero(T) (language-spec.md §17.7) |
number | 基底型で復号したのち 0 でないことを確かめる。0 なら type_mismatch |
json.Value |
任意 | §3 の規則で対応するタグに包む |
整数かどうかは綴りで決める。 1e-5000 は Float にすると 0.0 になるが、値が 0 なのではなく 0 へ丸まっただけなので、Int の位置では type_mismatch である。判定は number トークンそのものを見て行い、Float へ写した後の値では行わない — 整数の負のゼロ -0 (Int では 0) と小数 -1.5e-5000 は Float ではどちらも -0.0 になり、値からは区別が付かない。
対応外の型 — Any・json.Value 以外の enum (タグ付きデータ)・関数型・Bytes・range・不透明型 (std:time の Instant 等)・型変数・Never — が対象型のどの位置に含まれていても、呼び出し位置で Error とする。復号できない型を静的な診断なしに Err にすると、書き手の型の書き間違いと入力データの不正が同じ経路で返ってしまうためである。
総称型は型引数を置換して検査し、再帰先にも同じ規則を適用する。
例えば、再帰先でMapのキー型が String から List(String) へ変わる型は、入力にその再帰先の値が無くても対応外である。
json.Value 以外の enum を対応外にするのは、JSON にタグ付き和の表現規約が無く、規約を決めること自体が独立した設計判断になるためである。和が要る場合は Option を使うか、タグを持つ record として復号してから自分で match する。
2.2 record の復号
T が record 型のとき、宣言されたフィールドだけを JSON object から取り出して組み立てる。
- 欠落したフィールドは
type_mismatch。ただしフィールドの型がOption(E)のときはキーが無くてよく、その場合Noneになる。null が入っている場合と区別しない - 宣言に無いキーは無視する。JSON 側がフィールドを増やしても復号が壊れないため (前方互換) である。Hikari の record が幅構造型で「宣言より多くのフィールドを持つ値」を認めているのとも揃う
- フィールド値は宣言型で再帰的に復号する。入れ子の record・
List・Optionはそのまま入れ子で書ける
type Server := { host: String, port: Int, tls: Option(Bool) |} type Config := { name: String, servers: List(Server) |} json.decode("{\"name\":\"p\",\"servers\":[{\"host\":\"a\",\"port\":80}]}", type Config) #> Ok({ name := "p", servers := [{ host := "a", port := 80, tls := None |}] |}) json.decode("{\"name\":\"p\"}", type Config) #> Err({ kind := "type_mismatch", message := "json.decode: missing field 'servers'" |}) json.decode("{\"name\":\"p\",\"servers\":[{\"host\":\"a\",\"port\":\"80\"}]}", type Config) #> Err({ kind := "type_mismatch", message := "json.decode: .servers.0.port: expected Int, got a string" |})
2.3 エラーの位置
type_mismatch の message には値へ到達したパスを含める。パスは . 区切りで、名前は record のフィールド名・数字は配列の添字である (.servers.0.port)。ルート直下の不一致はパスを省く。
構文が壊れている場合の kind は syntax で、parse と同じ規則・同じ文面になる (§6)。JSON として不正なのか、JSON としては正しいが型に合わないのかを kind で区別できる。
2.4 静的な結果型
第 2 引数は型式なので、書いた地点で静的に解ける (language-spec.md §17.1「型式の位置」)。decode の結果型は常に Result(T, Error) に確定する。
型は値ではない (language-spec.md §17 冒頭) ので、型を変数に入れて実行時に選ぶ書き方 (ty := Config; decode(text, type ty)) は無い。スキーマが実行時にしか分からないデータは decode(text, type json.Value) か parse (§3) で読む。
2.5 ラップしても結果型は運べる
decode の静的シグネチャは { String, type a | Result(a) } である (language-spec.md §17.4.1)。
対象型と結果型を同じ型変数で結んでいるだけなので、ユーザー定義の関数でも同じことが書ける。
my_decode := { text: String, type a | json.decode(text, type a) } # 結果型は Result(a)
cfg := my_decode(text, type Config) # 結果型は Result(Config) に確定する
type a は呼び出しで埋める型スロットで、本体の json.decode(text, type a) は受け取った型をそのまま型引数として渡す。
3. json.parse
- 引数:
text(String) 1 個。非 String を渡すと静的エラー - 同期。
FutureではなくResultを直接返す - 戻り値は
Result(Value):
復号規則:
- 数値: JSON number が 整数値 のとき
Value.Int(language-spec.md §7)、そうでないときValue.Float。整数かどうかは綴りで決める (1・1.0・2e3・1e400・-0は整数値なので Int、1.5・1e-3は Float)。桁数には実装定義の上限があり、整数値の綴りが超えるとErr({ kind := "unsupported_number", … |})(入れ子の深さに上限があるのと同じ資源の防壁である)。数えるのは展開後の桁数で、指数表記は短い綴りが長い整数になる —1e300000は 9 文字だが 300001 桁である。上限は実際の JSON に現れる整数 (64 bit で 20 桁・256 bit で 78 桁・RSA-8192 の法で 2467 桁) を通す幅に採る。Float への読みは 2 進の最近接へ丸める (0.1は0.1に最も近い Float になる)。Float の範囲を超える小数は±Inf、0 へ丸まる小数は0.0(符号は保つ) になる - object:
Value.Object。payload はstd:mapのInsertionMap(String, Value)(map.md)。エントリはソース出現順に並ぶ (m.keys()がこの順を返す) ので、JSON のキー順がそのまま保たれる。値はm.get(k)で引き、m.each { k, v | … }で反復する。キーは JSON の任意の文字列で、Hikari の識別子として不正な文字 (-/ 空白等) を含み得るため record では表せない — record のスロットは書いた時点で名前が決まっているフィールドであり、キーで引く辞書ではない (language-spec.md §7.5)。同一キーが複数現れた場合は 後勝ち・位置維持 (InsertionMapのinsertと同じ規律。map.md §3) - array:
Value.Array。payload は固定長 (plain) のList(Value)(language-spec.md §7.4)。要素は出現順 - string:
Value.String。JSON のエスケープ (\n\t\"\\\/\b\f\r・\uXXXX) を解釈。\uXXXXのサロゲートペアは 1 つの code point に合成する。対にならないサロゲートはsyntax— 上位だけ・下位だけ・上位が 2 つ続く形はいずれも受けない。Hikari の String は UTF-8 で (language-spec.md §7.2.1)、単独のサロゲートに対応する符号位置が無いためである - bool →
Value.Bool - null →
Value.Null - 値の前後の空白 (space / tab / CR / LF) は許容。値の後ろに非空白が残る場合は
Err({ kind := "syntax", … |})(1 ファイル = 1 値)。空入力・トークン不正・文字列未終端・不正エスケープもsyntax - 入力は UTF-8 とみなす。不正な UTF-8 は
syntax - 入れ子の深さには実装定義の上限があり、超過時は
Err({ kind := "depth", … |})(スタック保護)
parse は Result を直接返す (Future ではない) ので、std:fs のような ! での await は不要。値が要るだけなら parse(text).unwrap! でもよい。
match json.parse(text) { Ok(v) => use(v) Err(e) => match e.kind { "syntax" => print("not valid JSON") "unsupported_number" => print("integer too long") _ => print(e.message) } }
4. json.stringify
- 引数:
(value, indent)の 2 引数。indentは省略できない (index.md) indentは 非負の Int。0で コンパクト (区切りに余分な空白を入れない)。正の整数nで pretty-print (1 段ごとに半角空白n個でインデントし、改行を入れる)indentが非 Int なら静的エラー。負のときは呼び出し位置でError(panic 型, language-spec.md §16)- 同期。
Resultを直接返す - 戻り値は
Result:
符号化規則:
- §1 の対応に従う。
InsertionMapはm.keys()の順 (= 挿入順)、record はm.names()の順 (= 宣言順) で出力し、いずれも出力順は決定的 - 数値の表記: Int は十進表記 (任意精度)。Float は言語の正準形と同じ最短往復形で、小数点も指数も含まないときは
.0を補う (2.0→2.0、57.4→57.4、1e21→1e+21)。いずれも valid な JSON number である。NaN/±Infは number として書けないためErr({ kind := "unsupported", … |})を返す - 空のコンテナー:
[]と{}は別の値なので (language-spec.md §7.4)、そのまま写す — 空 List は[](空 array)、空オブジェクトは{}(空 object) になる - String のエスケープ: JSON 必須のエスケープ (
"・\・U+0000〜U+001F の制御文字) のみを行う。/はエスケープしない。非 ASCII 文字は生の UTF-8 のまま 出力する (\uXXXXには逃がさない) - 制御文字は
\b・\t・\n・\f・\rを短縮エスケープ、それ以外のU+0000〜U+001Fを\uXXXXにする。\b(U+0008)/\f(U+000C) は短縮形で出し、U+2028/U+2029は(非 ASCII として)生のまま出す。どちらも valid な JSON でparseの解釈は不変。 - §1 後段の「JSON に写せない値」を含む場合は 落とさずに
Err({ kind := "unsupported", … |})。messageには該当値の種別と、可能なら到達位置を含める - 入れ子の深さ: 符号化にも実装定義の深さ上限があり、
parseの上限 (§3) を下回らない。
parseで読めた値は、数値が符号化に対応する限り深さ上限で書き戻しを妨げられない (§5)。上限を超える入れ子と、自分自身を含む循環した構造はここで止まりErr({ kind := "unsupported", … |})を返す (循環は JSON に写せる形を持たない)
json.stringify({ name := "a", items := [1, 2, 3] |}, 0) #> Ok("{\"name\":\"a\",\"items\":[1,2,3]}") json.stringify({ a := 1 |}, 2) #> Ok("{\n \"a\": 1\n}") json.stringify({ port := Some(8080), tls := None |}, 0) #> Ok("{\"port\":8080,\"tls\":null}")
5. 往復則
v が json.Value で、数値の桁数・入れ子の深さが読み取りの上限内にあり、
Float が有限で整数値でないとき、次の往復は値等価で v に一致する。
object のキー順と、空の array / object の区別も保つ。
(json.parse json.stringify(v, 0).unwrap!).unwrap!
整数値の Float は parse では閉じない。 Value.Float(2.0) は 2.0 と書かれ、
parse では Value.Int(2) に戻る。Float を Float のまま読み戻すには、
その位置を Float と宣言した decode を使う。
ネイティブ値の往復も、その形を対象型に書いて decode で閉じる。
record は宣言フィールドに従って組み立てられ、Option(E) は null を None に、
それ以外を Some に復号する。ただし Some(()) と Some(None) は null に符号化され、
None として戻る。
json.decode(json.stringify(v, 0).unwrap!, type T).unwrap!
stringify に渡した record を parse で読むと Value.Object になり、
ネイティブの List・String・Bool なども対応する Value のタグに包まれる。
ネイティブ値そのものと == で一致するという保証ではない。
桁数の上限を超える Int は parse で戻らない。 stringify は Int を桁数に依らず書くが、parse の側は上限を持つ (§3) ので、プログラムが組んだ極端に長い整数は書けても読み戻せない。上限は実際の JSON に現れる整数を通す幅に採ってあり、この非対称は深さの上限が parse と stringify で揃っているのと逆向きである — あちらは読めたものを必ず書けるようにするための揃えで、こちらは読む側だけが外から来た綴りを受けるので、書く側を縛っても守りにならない。
ただし往復は 正規化を伴う ため、テキストレベルでも安定しない点に注意:
parseは数値・文字列を Hikari 値へまとめるので、json.stringify(json.parse(t).unwrap!, 0)は空白・数値表記 (1.0→1、2e3→2000)・エスケープ表現が正規化され、元テキストtと一字一句一致するとは限らない- 空のコンテナーは §4 のとおり種類ごとに写るので、
[]は array、{}は object として往復する
履歴やキャッシュの一致判定は、テキスト比較ではなく parse 後の値を == (language-spec.md §9.1 の再帰的構造等価) で比べること。
import json := "std:json" import mp := "std:map" import assert := "std:assert" v: json.Value := json.Value.Object(mp.insertion.of [ ("items", json.Value.Array([json.Value.Int(1), json.Value.Null])) ]) assert.equal(json.decode("{\"items\":[1,null]}", type json.Value).unwrap!, v) assert.equal((json.parse json.stringify(v, 0).unwrap!).unwrap!, v) assert.equal(json.parse json.stringify(json.Value.Float(2.0), 0).unwrap!, Ok(json.Value.Int(2)))
6. エラーモデル
失敗時の e は回復可能エラーオブジェクト { kind, message |} (language-spec.md §16)。std:json が返す正規 kind (閉じた一覧):
| 関数 | kind | 意味 |
|---|---|---|
decode / parse |
syntax |
JSON として不正 (トークン不正・未終端・不正エスケープ・末尾の余剰・空入力・不正 UTF-8) |
decode / parse |
unsupported_number |
整数値の number の桁数が実装定義の上限を超える (§3)。decode では対象型が Float のときは発生しない — そちらは桁数に依らず Float へ読む (上限を超える綴りも Inf になるだけで、整数へ展開しない) |
decode / parse |
depth |
入れ子が実装定義の深さ上限を超えた |
decode |
type_mismatch |
JSON としては正しいが対象型に合わない (フィールド欠落・型違い・要素数不一致・NonZero(T) に 0)。message に到達パスを含む (§2.3) |
stringify |
unsupported |
value が §1 で JSON に写せない要素 (関数・Tuple・Bytes・range・Option / json.Value 以外のタグ付きの値) か、number として書けない Float (NaN / ±Inf) を含む。入れ子が深さ上限を超える場合 (循環した構造を含む。§4) も同じ kind である |
message は json.decode: ... のように関数名を含む人間可読文字列。分岐は match res { Ok(v) => … Err(e) => match e.kind { ... } } で kind により行い、message の文字列マッチに依存しないこと。非 String の text・非 Int の indent は静的エラー。負の indent・decode の第 2 引数が復号に対応しない型 (§2.1) は回復可能エラーではなく、呼び出し位置で Error (panic 型, language-spec.md §16) になる。入力データの不正 (Err) と書き手のプログラムのエラー (Error) を経路で分ける。 引数を省いた呼びはエラーではなく部分適用になる (index.md)。