Skip to content

overview.md

Latest commit

 

History

History
96 lines (67 loc) · 4.65 KB

overview.md

File metadata and controls

96 lines (67 loc) · 4.65 KB
Raw

API対応表：概要と命名規則

同じ概念・同じ機能を全言語に提供している。違うのは名前の綴りだけである。

このページは綴りの変換規則を示す。実際の対応表は次の3つ。

  • NBT（タグ、読み書き、SNBT）
  • Anvil（リージョンファイル）
  • World（ワールド、チャンク、ブロック）

1. 論理名という考え方

本ライブラリは、まず言語に依存しない論理名でAPIを定義し、各言語はそこから機械的に変換した名前を使う。

論理名          read_file
    ↓
C#              NbtIo.ReadFile(path)
Java            NbtIo.readFile(path, null)
TypeScript      readFile(path)
Python          read_file(path)
Rust            read_file(path, &NbtReadOptions::default())

こうしておくと「C#でWriteBytesを足したのにRustにwrite_bytesが無い」といった取りこぼしを、spec/tools/check_docs_sync.pyが機械的に見つけられる（→ adr/0009）。

対応表の「論理名」列がこれにあたる。

2. 変換規則

種別 論理名 C# Java TypeScript Python Rust
型・列挙 NbtCompound NbtCompound NbtCompound NbtCompound NbtCompound NbtCompound
列挙の値 long_array LongArray LONG_ARRAY LongArray LONG_ARRAY LongArray
メソッド read_file ReadFile() readFile() readFile() read_file() read_file()
取得子 data_version DataVersion dataVersion() dataVersion data_version data_version()
設定子 set_data_version DataVersion setDataVersion() dataVersion data_version set_data_version()
定数 TARGET_DATA_VERSION TargetDataVersion TARGET_DATA_VERSION TARGET_DATA_VERSION TARGET_DATA_VERSION TARGET_DATA_VERSION

真偽値を返す取得子は論理名をis_* / has_*で始める（is_fully_generated、has_block_states）。

詳しくは仕様00の3章。

3. モジュールと名前空間

言語 取り込み方
C# using SpringNBTLibrary.Nbt; / .Anvil / .World
Java import io.github.scriptarts.springnbt.nbt.*; / .anvil / .world
TypeScript import { ... } from "spring-nbt-library";（/nbt /anvil /worldのサブパスも可）
Python from spring_nbt_library.nbt import ...
Rust use spring_nbt_library::nbt::*;

C#とJavaには自由関数が無いため、read_fileのようなモジュール関数は静的クラス（NbtIo、Snbt、Mutf8、SpringNbt）に置いている。 対応表では「（モジュール関数）」の欄にまとめてある。

4. 言語ごとに揃わないところ

言語の性質上どうしても揃えられない箇所は、機能一覧の「言語ごとの差異」に理由つきで集約している。要点だけ挙げると次のとおり。

箇所 差異
TAG_Longの値 TypeScriptのみbigint
TAG_Stringの値 Rustのみ2形態の列挙（孤立サロゲートを保持するため）
タグの表現 RustはNbtTag列挙のバリアントで、数値と配列のタグには個別の型が無い（NbtByteではなくNbtTag::Byte(i8)）。TypeScriptのNbtTagはNbtByteなどのクラスの合併型
エラー RustのみResult<T, Error>。他4言語は例外
例外の型名 C# / JavaはSpringNbtException、TypeScript / PythonはSpringNbtError、RustはError
session.lock C# / Java / Python(POSIX)のみ確認する（adr/0008）

ErrorCodeの値は全言語で一致する。分類と使い分けはガイド06を参照。

5. この対応表の作られ方

各ページの表は実装から自動生成している。 人手で書くと必ず実装から遅れるため、spec/tools/extract_api.pyが全言語のソースから公開APIを抜き出し、check_docs_sync.pyが表を組み立てる。

# 実装に合わせて表を書き直す
python3 spec/tools/check_docs_sync.py --write

# ずれていないか確かめる（CIで実行）
python3 spec/tools/check_docs_sync.py

説明文は基準実装であるC#のドキュメントコメントから取っている。 説明を直したいときはC#のソースを直す。