本文へ移動
Hikari 仕様

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):
    • 成功時: Ok(value) — value は §1 の enum Value
    • 失敗時: Err(e) — e は回復可能エラーオブジェクト { kind, message |} (§6)

復号規則:

  • 数値: 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:
    • 成功時: Ok(text) — text は JSON テキストの String
    • 失敗時: Err(e) — value (またはその一部) が §1 で JSON に写せないとき。e は { kind, message |} (§6)

符号化規則:

  • §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)。