hakorune/docs/development/roadmap/phases/phase-12/export-import-spec.md

Nyash Export/Import構文仕様 v1.0

🎯 概要

Nyashのコード共有エコシステムを実現するためのexport/import構文仕様。「Everything is Box」哲学に基づき、Boxを中心とした明快な構文を提供する。

📝 基本構文

Export構文

# 単一Boxのエクスポート
export box MathUtils {
    init { precision }
    
    factorial(n) {
        if n <= 1 { return 1 }
        return n * me.factorial(n - 1)
    }
    
    fibonacci(n) {
        if n <= 1 { return n }
        return me.fibonacci(n - 1) + me.fibonacci(n - 2)
    }
}

# Static Boxのエクスポート
export static box Constants {
    init { }
    
    PI = 3.14159265359
    E = 2.71828182846
    GOLDEN_RATIO = 1.61803398875
}

# 複数Boxの名前付きエクスポート
export {
    MathUtils,
    Constants,
    StringHelpers as StrUtils  # エイリアス付き
}

# デフォルトエクスポート
export default box Calculator {
    init { display }
    // ...
}

Import構文

# 名前付きインポート
import { MathUtils } from "math_utils.ny"
import { MathUtils, Constants } from "math_lib.ny"

# エイリアス付きインポート
import { MathUtils as Math } from "math_utils.ny"

# デフォルトインポート
import Calculator from "calculator.ny"

# 全体インポート（名前空間）
import * as MathLib from "math_lib.ny"

# 複合インポート
import Calculator, { MathUtils, Constants } from "advanced_calc.ny"

🔧 モジュール解決

ファイルパス解決

# 相対パス
import { Utils } from "./utils.ny"
import { Common } from "../common/helpers.ny"

# パッケージ名（nyash_modules/から）
import { Logger } from "awesome-logger"

# 絶対パス（非推奨、移植性のため）
import { Config } from "/home/user/project/config.ny"

解決順序

1. 相対パス（./または../で始まる）
2. nyash_modules/ディレクトリ
3. グローバルパッケージディレクトリ（設定可能）
4. 絶対パス

📦 パッケージ構造

基本的なパッケージ構成

my-math-package/
├── nyash.toml          # パッケージメタデータ
├── src/
│   ├── index.ny        # メインエントリーポイント
│   ├── utils.ny
│   └── advanced.ny
├── tests/
│   └── test_math.ny
└── README.md

nyash.toml

[package]
name = "awesome-math"
version = "1.0.0"
description = "素晴らしい数学ユーティリティ"
author = "Nyash Developer"
license = "MIT"

[dependencies]
# 他のNyashパッケージへの依存
basic-utils = "^2.0.0"

[export]
# パッケージのメインエクスポート
main = "src/index.ny"

index.ny（エントリーポイント）

# 内部モジュールをインポート
import { InternalUtils } from "./utils.ny"
import { AdvancedMath } from "./advanced.ny"

# 外部にエクスポート
export {
    InternalUtils as Utils,
    AdvancedMath
}

# デフォルトエクスポート
export default box MathPackage {
    init {
        me.utils = new Utils()
        me.advanced = new AdvancedMath()
    }
}

🚀 高度な機能

条件付きエクスポート

# プラットフォーム別エクスポート
if PLATFORM == "web" {
    export { WebLogger as Logger } from "./web_logger.ny"
} else {
    export { ConsoleLogger as Logger } from "./console_logger.ny"
}

再エクスポート

# 他のモジュールから再エクスポート
export { MathUtils } from "./math_utils.ny"
export * from "./string_helpers.ny"

動的インポート（将来拡張）

# 実行時に動的にインポート
local dynamicModule = await import("./heavy_module.ny")
local HeavyBox = dynamicModule.HeavyBox

🔒 スコープとアクセス制御

プライベートメンバー

export box SecureBox {
    init { 
        _privateData  # アンダースコアプレフィックスは慣習的にプライベート
        publicData
    }
    
    # プライベートメソッド（エクスポートされない）
    _internalProcess() {
        // 内部処理
    }
    
    # パブリックメソッド
    process() {
        return me._internalProcess()
    }
}

🎯 実装優先順位

Phase 1: 基本機能（必須）

• export box構文
• import { Box } from "file"構文
• 相対パス解決
• 基本的な循環参照チェック

Phase 2: 拡張機能（推奨）

• export default
• import * as namespace
• エイリアス（as）
• nyash_modules/ディレクトリサポート

Phase 3: 高度な機能（オプション）

• 条件付きエクスポート
• 再エクスポート
• 動的インポート
• パッケージマネージャー統合

⚠️ 制約事項

1. 循環参照の禁止

   # ❌ エラー: 循環参照
   # a.ny: import { B } from "./b.ny"
   # b.ny: import { A } from "./a.ny"
   

2. トップレベルでのみ許可

   # ✅ OK
   import { Utils } from "./utils.ny"
   
   # ❌ エラー: 関数内でのインポート
   box MyBox {
       method() {
           import { Helper } from "./helper.ny"  # エラー！
       }
   }
   

3. export前の参照禁止

   # ❌ エラー: 定義前のエクスポート
   export { UndefinedBox }  # エラー！
   
   box UndefinedBox { }
   

🔄 他言語との比較

機能	Nyash	JavaScript	Python	Rust
名前付きexport	✅	✅	✅	✅
デフォルトexport	✅	✅	❌	❌
名前空間import	✅	✅	✅	✅
動的import	🔄	✅	✅	❌
再export	✅	✅	✅	✅

📚 使用例

数学ライブラリ

# math_lib.ny
export box Vector2D {
    init { x, y }
    
    add(other) {
        return new Vector2D(me.x + other.x, me.y + other.y)
    }
    
    magnitude() {
        return Math.sqrt(me.x * me.x + me.y * me.y)
    }
}

export static box MathConstants {
    init { }
    TAU = 6.28318530718
}

使用側

# game.ny
import { Vector2D, MathConstants } from "./math_lib.ny"

box Player {
    init { 
        me.position = new Vector2D(0, 0)
        me.velocity = new Vector2D(1, 1)
    }
    
    update() {
        me.position = me.position.add(me.velocity)
        local angle = MathConstants.TAU / 4  # 90度
    }
}

---

Everything is Box - そしてBoxは共有される