hakorune/docs/reference/plugin-system/filebox-bid-mapping.md

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