hakorune/docs/guides/macro-box.md

MacroBox — User Extensible Macro Units

Status: Stable for user macros via Nyash runner route（self‑hosting優先）。

Goals

• Allow users to implement procedural macro-like expansions in pure Nyash (future) and Rust (prototype) with a clean, deterministic interface.
• Preserve “Box independence” (loose coupling). Operate on public interfaces; avoid relying on private internals.

Enabling

• Macro engine is ON by default. Disable with NYASH_MACRO_DISABLE=1.
• Register user macro files via NYASH_MACRO_PATHS=path1,path2.
• Runner route（Nyashでの実行）が既定。内部子ルートは非推奨（NYASH_MACRO_BOX_CHILD_RUNNER=0 でのみ強制）。

API（Nyash, 推奨）

• Box: static box MacroBoxSpec { static function expand(json[, ctx]) -> json }
• Contract: AST JSON v0（docs/reference/ir/ast-json-v0.md）。ctxはJSON文字列（MVP: {caps:{io,net,env}}）。
• 実行: エンジンは登録されたファイルをNyashランナールートで呼び出し、展開JSONを受け取る。

API（Rust, 内部/開発者向け）

• Trait: MacroBox { name() -> &'static str; expand(&ASTNode) -> ASTNode }
• 用途: 最小のビルトイン（例: derive）やプロトタイピング。一般ユーザーはNyash版を使う。

Constraints (philosophy)

• Deterministic; side-effect free by default（io/net/envはcapabilitiesで明示）
• Respect “Box independence”: 公開インターフェースを基本に、疎結合を維持

Built-in example

• UppercasePrintMacro（開発者向けの内蔵例）。通常はNyashで実装されたユーザーマクロを使用。

Future plan

• nyash.toml による登録/パッケージ管理
• Attribute-style macros（@derive/@lint）の整理