012fc1930f
- Extract Copilot's BID converter code to src/bid-converter-copilot/ for future use - Create comprehensive plugin migration request document for Copilot - Target 13 built-in boxes for plugin conversion (HTTP, GUI, Audio, etc.) - Preserve existing nyash.toml-based plugin system - Reorganize docs/説明書/reference/ structure for better organization
69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
FileBox × BID-FFI 対応表（Nyash API ↔ Plugin ABI）
|
||
|
||
概要
|
||
- 目的: Nyash言語における `FileBox` のAPIを、BID-FFIプラグイン実装（C ABI）と正確に対応付ける。
|
||
- 設置: C:\git\nyash-project\nyash\docs\説明書\reference\box-design\filebox-bid-mapping.md（Windowsパス例）
|
||
|
||
前提
|
||
- BID-FFI v1（2段階応答/ShortBuffer=-1）
|
||
- TLVヘッダ: `u16 version(=1)`, `u16 argc`
|
||
- TLVエントリ: `u8 tag`, `u8 reserved(0)`, `u16 size`, payload
|
||
- 主要タグ: 1=Bool, 2=I32, 3=I64, 4=F32, 5=F64, 6=String, 7=Bytes, 8=Handle(u64), 9=Void
|
||
|
||
メソッドID（プラグイン側）
|
||
- 0: birth(instance生成) → 戻り値: u32 instance_id（暫定）
|
||
- 1: open(String path, String mode) → Void
|
||
- 2: read(I32 size) → Bytes
|
||
- 3: write(Bytes data) → I32（書込バイト数）
|
||
- 4: close() → Void
|
||
- 0xFFFF_FFFF: fini（破棄）
|
||
|
||
Nyash API ↔ Plugin ABI 対応
|
||
- 構築: `new FileBox(path: string)`
|
||
- 既定動作: プラグイン設定が有効な場合、birth→open(path, "rw") を内部実行
|
||
- フォールバック: プラグインが無効/未設定ならビルトインFileBoxを使用
|
||
|
||
- 書込: `FileBox.write(data: string)`
|
||
- 変換: String → Bytes（UTF-8）
|
||
- 呼出: method_id=3（write）
|
||
- 戻り: I32 を受け取り、Nyash側は "ok" を返却（将来は書込サイズも返せる拡張余地）
|
||
|
||
- 読取: `FileBox.read([size: integer])`
|
||
- 変換: 省略時デフォルト 1MB（1_048_576）を指定
|
||
- 呼出: method_id=2（read）
|
||
- 戻り: Bytes → String（UTF-8として解釈、失敗時はlossy）
|
||
|
||
- 閉じ: `FileBox.close()`
|
||
- 呼出: method_id=4（close）
|
||
- 戻り: Void → Nyash側は "ok"
|
||
|
||
エラーモデル（戻り値）
|
||
- 0: 成功
|
||
- -1: ShortBuffer（2段階応答。副作用なしで必要サイズを *result_len に返却）
|
||
- -2: InvalidType
|
||
- -3: InvalidMethod
|
||
- -4: InvalidArgs
|
||
- -5: PluginError
|
||
- -8: InvalidHandle
|
||
|
||
例（Nyashコード）
|
||
```
|
||
// プラグイン優先で FileBox を生成
|
||
local f
|
||
f = new FileBox("/tmp/nyash_example.txt")
|
||
f.write("Hello from Nyash via plugin!")
|
||
print("READ=" + f.read())
|
||
f.close()
|
||
```
|
||
|
||
実装メモ（現在の挙動）
|
||
- コンストラクタ: プラグイン有効時は birth→open("rw")。指定モードでの open は将来のAPI拡張候補（例: `FileBox.open(mode)`）。
|
||
- read(size): Nyashからサイズを指定するAPIは次段で追加予定。現状は既定1MBで読み取り。
|
||
- write: 書込サイズはプラグインからI32で返るが、Nyash側APIは簡便化のため "ok" を返却（将来拡張余地）。
|
||
|
||
関連ドキュメント
|
||
- plugin-ABI: docs/説明書/reference/box-design/ffi-abi-specification.md
|
||
- plugin system: docs/説明書/reference/box-design/plugin-system.md
|
||
- plugin-tester: docs/説明書/reference/plugin-tester.md
|
||
|