hakorune/docs/nyash_core_concepts.md

# 🚀 Nyash言語 - 一目でわかる速習ガイド

**Nyash**は「Everything is Box」哲学に基づく革新的プログラミング言語です。このドキュメントで、Nyashのコアコンセプトを素早く理解できます。

## 🎯 **5分で動かす！クイックスタート**

```bash
# ビルド & 実行
cargo build --release -j32
./target/release/nyash program.nyash

# プラグイン対応FileBox実行例
./target/release/nyash local_tests/test_plugin_filebox.nyash
```

### 🌟 **実際に動く！Nyashコード例**

```nyash
using nyashstd

static box Main {
    init { console }
    
    main() {
        // 🎉 自動リテラル変換 - 超簡単！
        local name = "Nyash"              // → StringBox
        local year = 2025                 // → IntegerBox
        local pi = 3.14159               // → FloatBox
        
        // 🚀 プラグインシステム
        local f = new FileBox("data.txt") // プラグイン実装
        f.write("Hello from plugin!")
        print("読み取り: " + f.read())
        
        // 📚 標準ライブラリ
        local upper = string.upper(name)
        console.log("🎉 " + upper + " " + year + " Ready!")
    }
}
```

**実行結果:**
```
読み取り: Hello from plugin!
🎉 NYASH 2025 Ready!
```

## 🔌 **BID-FFIプラグインシステム** - Phase 9.75g-0の革命！

Nyashの最新の革命的機能：**プラグインによるBox拡張システム**

### 🎯 **プラグインの威力**

```nyash
// プラグイン設定（nyash.toml）
[plugins]
FileBox = "nyash-filebox-plugin"

// Nyashコード - 透過的にプラグイン使用
local f = new FileBox("important.txt")  // プラグイン実装を自動選択
f.write("機密データ")                    // プラグインのwrite()
local data = f.read()                   // プラグインのread()
```

### ✨ **型情報管理システム**

```toml
# nyash.toml - 型情報で自動変換
[plugins.FileBox.methods]
write = { args = [{ from = "string", to = "bytes" }] }  # 自動変換
read = { args = [] }                                    # 引数なし
```

### 🛡️ **メモリ安全性**

- **HostVtable**: プラグイン↔ホスト間の安全なインターフェース
- **生存期間管理**: birth/finiライフサイクル完全実装
- **valgrind検証済み**: セグフォルト完全解消

### 📋 **プラグイン診断ツール**

```bash
# プラグインの健全性チェック
./tools/plugin-tester/target/release/plugin-tester check plugin.so
./tools/plugin-tester/target/release/plugin-tester io plugin.so
```

**詳細**: [BID-FFI仕様書](説明書/reference/box-design/ffi-abi-specification.md)

## ⚡ **実行バックエンド選択** - 開発から本番まで

Nyashは用途に応じて最適な実行方式を選択可能：

```bash
# 開発・デバッグ（即時実行）
./target/release/nyash program.nyash

# 高速実行（本番用）
./target/release/nyash --backend vm program.nyash

# Web配布用
./target/release/nyash --compile-wasm program.nyash

# 性能比較
./target/release/nyash --benchmark --iterations 100
```

### 🚀 **性能実績**
- **VM**: 20.4倍高速化
- **WASM**: 13.5倍高速化  
- **LLVM AOT**: 100-1000倍高速化（Phase 10計画中）
- **インタープリター**: 開発に最適、本番でも実用的

**詳細**: [実行バックエンド完全ガイド](execution-backends.md)

## 1. 基本哲学: Everything is a Box (すべてはBoxである)

- Nyashの基本原則は「すべてがBoxである」ということです。
- 単純な整数から複雑な構造体まで、すべてのデータ型は「Box」オブジェクトの一種です。これにより、純粋で一貫性のあるオブジェクトベースのシステムが実現されています。

### 🌟 **革命的改善: 自動リテラル変換（Phase 9.75h完了）**

Nyashでは、Everything is Box哲学を維持しながら、使いやすさを大幅に向上させる自動リテラル変換機能を提供します：

```nyash
// 🎉 新しい書き方 - 自動変換で超使いやすい！
local text = "Hello"       // "Hello" → StringBox::new("Hello") に自動変換
local name = "Alice"       // "Alice" → StringBox::new("Alice") に自動変換  
local age = 30             // 30 → IntegerBox::new(30) に自動変換
local active = true        // true → BoolBox::new(true) に自動変換
local pi = 3.14159         // 3.14159 → FloatBox::new(3.14159) に自動変換

// ❌ 古い書き方（まだサポート）
local oldText = new StringBox("Hello")
local oldAge = new IntegerBox(30)

// ✅ Everything is Box哲学 + 書きやすさ革命達成！
```

**重要**: この自動変換はパーサーレベルで行われるため、実行時オーバーヘッドはありません。すべてが内部的にBoxとして処理されます。

## 2. オブジェクトモデルとデリゲーション (Nyash独自の方式)

Nyashは古典的な継承ではなく、デリゲーション（委譲）モデルを使用します。これは非常に重要な違いです。

- **Boxの定義:**
  ```nyash
  box MyBox {
      // フィールドはinitやpackのようなコンストラクタ内で宣言される
      // メソッドはこの場所に定義される
  }
  ```

- **コンストラクタ** (優先順位: birth > pack > init > Box名形式)
  - **`birth` (推奨・統一):** 「Boxに生命を与える」直感的コンストラクタ。Everything is Box哲学を体現する最新の統一構文。
    ```nyash
    box Life {
        init { name, energy }  // フィールド宣言
        
        birth(lifeName) {  // ← 「生命を与える」哲学的コンストラクタ
            me.name = lifeName
            me.energy = 100
            print("🌟 " + lifeName + " が誕生しました！")
        }
    }
    local alice = new Life("Alice")  // birthが呼び出される
    ```
  - **`init` (基本):** 従来のユーザー定義Boxのコンストラクタ。フィールド宣言と基本的な初期化。
    ```nyash
    box User {
        init { name, email }  // フィールド宣言のみ
        // new時に直接フィールドに値が設定される
    }
    local user = new User("Alice", "alice@example.com")  // initが呼び出される
    ```
  - **`pack` (ビルトインBox継承専用):** ビルトインBox（P2PBox、MathBox等）を継承する際の特別なコンストラクタ。ユーザー定義Boxでは使用禁止。
    ```nyash
    box ChatNode from P2PBox {
        init { chatHistory }  // 追加フィールド宣言
        
        pack(nodeId, world) {
            from P2PBox.pack(nodeId, world)  // ビルトインBoxの初期化
            me.chatHistory = new ArrayBox()   // 自分の追加フィールド初期化
        }
    }
    local node = new ChatNode("node1", "tcp")  // packが呼び出される
    ```

- **デリゲーション (`from`キーワード):** あるオブジェクトが、メソッド呼び出しやフィールドアクセスを別のオブジェクトに委譲できます。
  ```nyash
  // AdminがUserにデリゲートする
  box Admin from User {
      init { permissions } // Adminの追加フィールド
  }
  ```

- **明示的なオーバーライド (`override`キーワード):** 子Boxが親Boxのメソッドを再実装する場合、必ず`override`でマークしなければなりません。
  ```nyash
  box AdminUser from User {
      init { permissions }  // 追加フィールド
      
      birth(name, email, permissions) {  // birth構文使用
          from User.birth(name, email)     // 親のbirthを呼び出し
          me.permissions = permissions     // 追加フィールド初期化
          print("🎉 管理者 " + name + " が誕生しました")
      }
      
      override greet() {
          from User.greet()                // 親の処理を実行
          print("(Administrator)")         // 追加の処理
      }
  }
  ```

- **デリゲートされたメソッドの呼び出し (`from`キーワード):** オーバーライドしたメソッド内から親の実装を呼び出すには、`from Parent.method()`を使用します。
  ```nyash
  box ScientificCalc from MathBox {
      init { history }
      
      pack() {
          from MathBox.pack()              // ビルトインBoxの初期化
          me.history = new ArrayBox()      // 自分の追加フィールド
      }
      
      override sin(x) {
          local result = from MathBox.sin(x)  // 親のメソッド呼び出し
          me.history.push("sin(" + x + ") = " + result)
          return result
      }
  }
  ```

- **ファイナライズ (`fini`キーワード):**
  - `fini()`は「論理的な解放フック」として機能する特別なメソッドです。
  - インスタンスに対して呼び出されると、そのインスタンスがもはや使用されるべきではないことを示します。
  - クリーンアップ処理を実行し、所有するすべてのフィールドに対して再帰的に`fini()`を呼び出します。
  - ファイナライズされたオブジェクトを使用しようとすると（`fini`の再呼び出しを除く）、実行時エラーが発生します。
  ```nyash
  box ManagedResource {
      init { handle }
      fini() {
          // ハンドルを解放したり、他のクリーンアップ処理を実行
          me.console.log("リソースをファイナライズしました。")
      }
  }
  ```

## 3. 標準ライブラリアクセス (using & namespace) 🎉 **Phase 9.75e完了**

Nyashは組み込み標準ライブラリ`nyashstd`と、using文による名前空間インポートをサポートします。

### **🌟 using nyashstd - 完全実装済み**

**基本構文:**
```nyash
using nyashstd

// ✅ 実際に動作確認済みの標準ライブラリ機能
local result = string.create("Hello World")  // → "Hello World"
local upper = string.upper(result)           // → "HELLO WORLD"  
local number = integer.create(42)            // → 42
local flag = bool.create(true)               // → true
local arr = array.create()                   // → []
console.log("✅ using nyashstd test completed!")  // ✅ 出力成功
```

### **🎯 実装済み名前空間モジュール:**

- **string.*** - 文字列操作
  ```nyash
  string.create("text")     // 文字列Box作成
  string.upper("hello")     // "HELLO" - 大文字変換
  string.lower("WORLD")     // "world" - 小文字変換
  ```

- **integer.*** - 整数操作
  ```nyash
  integer.create(42)        // 整数Box作成
  // 将来: integer.add(), integer.multiply() 等
  ```

- **bool.*** - 真偽値操作
  ```nyash
  bool.create(true)         // 真偽値Box作成
  // 将来: bool.and(), bool.or(), bool.not() 等
  ```

- **array.*** - 配列操作
  ```nyash
  array.create()            // 空配列Box作成
  // 将来: array.push(), array.length() 等
  ```

- **console.*** - コンソール出力
  ```nyash
  console.log("message")    // コンソール出力
  // 将来: console.error(), console.debug() 等
  ```

### **⚡ 自動リテラル変換との連携**

using nyashstdと自動リテラル変換を組み合わせると、極めてシンプルなコードが書けます：

```nyash
using nyashstd

// 🌟 革命的シンプルさ！
local name = "Nyash"              // 自動StringBox変換
local year = 2025                 // 自動IntegerBox変換
local upper = string.upper(name)  // nyashstd + 自動変換連携
console.log("🚀 " + upper + " " + year.toString() + " Ready!")
// 出力: "🚀 NYASH 2025 Ready!" ✅
```

### **📋 名前空間の特徴:**
- **✅ Phase 9.75e完了**: `nyashstd`完全実装・動作確認済み
- **IDE補完対応**: `string.`で標準機能の補完が可能（将来）
- **明示的インポート**: プレリュード（自動インポート）よりIDE補完に適した設計
- **拡張可能**: 将来的にユーザー定義名前空間もサポート予定

## 4. 構文クイックリファレンス

### **🎯 現代的Nyash構文（Phase 9.75h対応）**

- **厳格な変数宣言:** すべての変数は使用前に宣言が必要です。
  ```nyash
  // 🌟 自動リテラル変換 + 宣言
  local text = "Hello"        // 自動StringBox変換 + ローカル宣言
  local count = 42            // 自動IntegerBox変換 + ローカル宣言
  local flag = true           // 自動BoolBox変換 + ローカル宣言
  
  // Box内フィールドアクセス
  me.field = "value"          // 現在のBoxインスタンスのフィールド
  
  // 静的関数内での所有権移転
  outbox product = new Item() // 所有権が呼び出し元に移転
  ```

- **統一されたループ:** ループ構文は一種類のみです。
  ```nyash
  loop(condition) {
      // 条件がtrueの間ループ
  }
  ```

- **プログラムのエントリーポイント:** 実行は`static box Main`の`main`メソッドから開始されます。
  ```nyash
  using nyashstd  // 標準ライブラリインポート
  
  static box Main {
      init { console }  // フィールド宣言
      
      main() {
          me.console = new ConsoleBox()
          
          // 🌟 現代的Nyash書法
          local message = "Hello Nyash 2025!"  // 自動変換
          console.log(message)                 // 標準ライブラリ使用
      }
  }
  ```

### **🎉 実用的なコード例（最新機能活用）**

```nyash
using nyashstd

static box Main {
    init { console }
    
    main() {
        me.console = new ConsoleBox()
        
        // 🌟 すべて自動変換 + 標準ライブラリ
        local name = "Nyash"               // 自動StringBox
        local version = 2025               // 自動IntegerBox  
        local isStable = true              // 自動BoolBox
        local pi = 3.14159                 // 自動FloatBox
        
        // string標準ライブラリ活用
        local upper = string.upper(name)
        
        // コンソール出力
        console.log("🚀 " + upper + " " + version.toString() + " Ready!")
        console.log("円周率: " + pi.toString())
        console.log("安定版: " + isStable.toString())
    }
}
```

## 4. 演算子

- **論理演算子:** `and`, `or`, `not`
- **算術演算子:** `+`, `-`, `*`, `/` (ゼロ除算をハンドルします)
- **比較演算子:** `==`, `!=`, `<`, `>`, `<=`, `>=`

## 5. 主要なビルトインBox（実装済み）

- **基本型**
  - **`StringBox`**: 文字列操作
  - **`IntegerBox`**: 整数値
  - **`FloatBox`**: 浮動小数点数（Phase 9.75h追加）
  - **`BoolBox`**: 真偽値
  - **`NullBox`**: null値

- **計算・データ処理系**
  - **`MathBox`**: 数学関数（sin, cos, sqrt等）
  - **`RandomBox`**: 乱数生成
  - **`TimeBox`**: 時間・日付操作
  - **`ArrayBox`**: 配列操作
  - **`MapBox`**: 連想配列（辞書）操作

- **I/O・デバッグ系**
  - **`ConsoleBox`**: 基本的なI/O (例: `log()`)
  - **`DebugBox`**: イントロスペクション/デバッグ (例: `memoryReport()`)
  - **`SoundBox`**: 音声出力

- **GUI・Web系（環境依存）**
  - **`EguiBox`**: GUI（メインスレッド制約など）
  - **`WebDisplayBox`**: Web表示
  - **`WebConsoleBox`**: Webコンソール
  - **`WebCanvasBox`**: Web Canvas操作

- **通信・ネットワーク系**
  - **`P2PBox`**: P2P通信
  - **`SimpleIntentBox`**: 簡単なインテント通信
  - **`SocketBox`**: TCP/IPソケット通信（Phase 9.75i追加）
  - **`BufferBox`**: バイナリバッファ操作（Phase 9.75i追加）

**注意**: using nyashstdで標準ライブラリ経由でのアクセスも可能です。

## 6. データ構造 (Data Structures)

現行バージョンでは配列/マップのリテラル構文（`[]`, `{}`）は未実装です（将来計画）。
利用時はビルトインBoxを用います。

- **配列 (ArrayBox):**
  ```nyash
  local a = new ArrayBox()
  a.push(1)
  a.push(2)
  a.push(3)
  // 取得
  local first = a.get(0)
  // サイズ（実装に依存）
  // 例: a.length() または length はAPIに従って利用
  ```

- **マップ (MapBox):**
  ```nyash
  local m = new MapBox()
  m.set("name", "Alice")
  m.set("age", 30)
  local name = m.get("name")
  ```

## 7. エラーハンドリング (Error Handling)

実行時エラーによってプログラムがクラッシュするのを防ぐために、`try...catch`ブロックを使用します。

- **構文:**
  ```nyash
  try {
      // エラーが発生する可能性のあるコード
      local result = 10 / 0
  } catch {
      // エラーが発生した場合に実行されるコード
      print("エラーが発生しましたが、プログラムは続行します。")
  }
  ```

- **finally/throw の補足:**
  ```nyash
  try {
      if (x < 0) { throw "negative" }
  } catch {
      print("error")
  } finally {
      print("always")
  }
  ```

## 8. メモリ管理と弱参照 (Memory Management & Weak References)

- **`weak` キーワード:** `init`ブロック内でフィールドを`weak`として宣言することで、弱参照を作成します。これは主に循環参照を防ぐために使用されます。
  - 弱参照はオブジェクトの所有権を持ちません。
  - 参照先のオブジェクトが解放されると、弱参照フィールドは自動的に`null`になります。
  ```nyash
  box Node {
      init { id, weak next } // 'next'は弱参照
  }

  local node1 = new Node("A", null)
  local node2 = new Node("B", node1) // node2はnode1への弱参照を持つ
  node1.next = node2 // node1はnode2への強参照を持つ
  // この場合、node1とnode2が互いを所有しないため、安全に解放される
  ```

不変条件（重要）
- weak フィールドに対して `fini()` を直接呼ぶことはできません（エラーになります）。
- インスタンスで `fini()` 呼び出し後は、そのオブジェクトの使用はすべて禁止です（アクセス時にエラー）。
- `fini()` のカスケードは init 宣言順の「逆順」で実行され、weak フィールドはスキップされます。

## 9. 非同期処理 (Asynchronous Processing)

- **`nowait` 文:** 式を別スレッドで非同期実行し、その結果を表す `FutureBox` を変数に格納します。
  - 構文: `nowait future = expression`
  - 挙動: 内部でスレッドを生成し、完了時に `future.set_result(...)` が呼ばれます。

- **`await` 式:** `FutureBox` の完了を待機し、結果を取り出します。
  - 構文: `result = await future`
  - 実装: `FutureBox.wait_and_get()` を通じて結果を返します。

使用例:
```nyash
// 非同期に3つの処理を開始
nowait f1 = heavyComputation(5000)
nowait f2 = heavyComputation(3000)
nowait f3 = heavyComputation(4000)

// 結果を待機
r1 = await f1
r2 = await f2
r3 = await f3
```

備考（現実装の特性）
- 実装はスレッドベースの簡易非同期（イベントループ無し）。
- FutureBox は簡易 busy-wait を用います（将来 condvar 等で改善予定）。
- 例外は `ErrorBox` として `FutureBox` に格納されます（`await` 側で結果を取り出す設計）。

## 10. 静的Box/関数と所有権移転（outbox）

- **静的エントリーポイント:**
  ```nyash
  static box Main {
      main() {
          print("Hello Nyash")
      }
  }
  ```

- **静的boxメソッド呼び出し（Phase 9.75i実装）:**
  ```nyash
  static box ProxyServer {
      static port = 8080  // 静的フィールド
      
      static main() {
          print("Starting proxy on port " + ProxyServer.port.toString())
      }
  }
  
  // 呼び出し
  ProxyServer.main()  // ✅ 静的メソッド直接呼び出し可能
  ```

- **静的関数の定義/呼び出し:**
  ```nyash
  static function Math.min(a, b) {
      if (a < b) { return a } else { return b }
  }
  local m = Math.min(1, 2)
  ```

- **所有権移転（outbox, static関数内のみ）:**
  ```nyash
  static function Factory.create() {
      outbox product
      product = new Item()
      return product
  }
  ```

## 11. クイック実行コマンド

```bash
# ビルド & 基本実行
cargo build --release -j32
./target/release/nyash program.nyash

# プラグイン診断
./tools/plugin-tester/target/release/plugin-tester check plugin.so

# 性能比較
./target/release/nyash --benchmark --iterations 100
```

---

**最終更新: 2025年8月19日** - **🚀 Phase 9.75g-0 BID-FFI完全実装！**

### 🎉 **最新の革命的成果**
- 🔌 **BID-FFIプラグインシステム**: プラグインによるBox拡張完全実装
- ✨ **型情報管理システム**: nyash.tomlベースの自動型変換
- 🛡️ **メモリ安全性確保**: HostVtable生存期間問題解決、valgrind検証済み
- 🧪 **plugin-tester**: 汎用プラグイン診断ツール完成

### 🌟 **過去の革命的改善**
- **Phase 9.75h**: 自動リテラル変換、using nyashstd、birth構文
- **Phase 9.75i**: 静的boxメソッド、SocketBox、BufferBox
- **Phase 9.75j**: 警告削減（106個→0個）

### 🚀 **Nyashの実用的価値**
**Everything is Box哲学 + プラグイン拡張 + 実用的性能** の革新的言語！

- **🔌 拡張性**: プラグインで無限にBox機能拡張
- **🛡️ 安全性**: メモリ安全性とvalgrind検証済み
- **⚡ 性能**: VM 20倍、WASM 13倍、将来AOT 1000倍高速化
- **📚 使いやすさ**: 自動変換、標準ライブラリ、直感的構文

**詳しいdocs**: [完全リファレンス](説明書/reference/) | [開発ガイド](../CLAUDE.md) | [Phase計画](予定/native-plan/copilot_issues.txt)