hakorune/docs/nyash_core_concepts.md

Nyash言語コアコンセプト AI向け速習ガイド

このドキュメントは、AIアシスタントがNyashプログラミング言語を迅速に理解するために、そのコアコンセプトを凝縮して提供します。

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

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

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

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

// 🎉 新しい書き方 - 自動変換で超使いやすい！
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の定義:

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

• コンストラクタ (優先順位: birth > pack > init > Box名形式)

  • birth (推奨・統一): 「Boxに生命を与える」直感的コンストラクタ。Everything is Box哲学を体現する最新の統一構文。

    box Life {
        init { name, energy }  // フィールド宣言
    
        birth(lifeName) {  // ← 「生命を与える」哲学的コンストラクタ
            me.name = lifeName
            me.energy = 100
            print("🌟 " + lifeName + " が誕生しました！")
        }
    }
    local alice = new Life("Alice")  // birthが呼び出される
    

  • init (基本): 従来のユーザー定義Boxのコンストラクタ。フィールド宣言と基本的な初期化。

    box User {
        init { name, email }  // フィールド宣言のみ
        // new時に直接フィールドに値が設定される
    }
    local user = new User("Alice", "alice@example.com")  // initが呼び出される
    

  • pack (ビルトインBox継承専用): ビルトインBox（P2PBox、MathBox等）を継承する際の特別なコンストラクタ。ユーザー定義Boxでは使用禁止。

    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キーワード): あるオブジェクトが、メソッド呼び出しやフィールドアクセスを別のオブジェクトに委譲できます。

  // AdminがUserにデリゲートする
  box Admin from User {
      init { permissions } // Adminの追加フィールド
  }
  

• 明示的なオーバーライド (overrideキーワード): 子Boxが親Boxのメソッドを再実装する場合、必ずoverrideでマークしなければなりません。

  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()を使用します。

  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の再呼び出しを除く）、実行時エラーが発生します。

  box ManagedResource {
      init { handle }
      fini() {
          // ハンドルを解放したり、他のクリーンアップ処理を実行
          me.console.log("リソースをファイナライズしました。")
      }
  }
  

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

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

🌟 using nyashstd - 完全実装済み

基本構文:

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.* - 文字列操作

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

• integer.* - 整数操作

  integer.create(42)        // 整数Box作成
  // 将来: integer.add(), integer.multiply() 等
  

• bool.* - 真偽値操作

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

• array.* - 配列操作

  array.create()            // 空配列Box作成
  // 将来: array.push(), array.length() 等
  

• console.* - コンソール出力

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

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

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

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対応）

• 厳格な変数宣言: すべての変数は使用前に宣言が必要です。

  // 🌟 自動リテラル変換 + 宣言
  local text = "Hello"        // 自動StringBox変換 + ローカル宣言
  local count = 42            // 自動IntegerBox変換 + ローカル宣言
  local flag = true           // 自動BoolBox変換 + ローカル宣言
  
  // Box内フィールドアクセス
  me.field = "value"          // 現在のBoxインスタンスのフィールド
  
  // 静的関数内での所有権移転
  outbox product = new Item() // 所有権が呼び出し元に移転
  

• 統一されたループ: ループ構文は一種類のみです。

  loop(condition) {
      // 条件がtrueの間ループ
  }
  

• プログラムのエントリーポイント: 実行はstatic box Mainのmainメソッドから開始されます。

  using nyashstd  // 標準ライブラリインポート
  
  static box Main {
      init { console }  // フィールド宣言
  
      main() {
          me.console = new ConsoleBox()
  
          // 🌟 現代的Nyash書法
          local message = "Hello Nyash 2025!"  // 自動変換
          console.log(message)                 // 標準ライブラリ使用
      }
  }
  

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

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):

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

• マップ (MapBox):

  local m = new MapBox()
  m.set("name", "Alice")
  m.set("age", 30)
  local name = m.get("name")
  

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

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

• 構文:

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

• finally/throw の補足:

  try {
      if (x < 0) { throw "negative" }
  } catch {
      print("error")
  } finally {
      print("always")
  }
  

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

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

  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() を通じて結果を返します。

使用例:

// 非同期に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）

• 静的エントリーポイント:

  static box Main {
      main() {
          print("Hello Nyash")
      }
  }
  

• 静的boxメソッド呼び出し（Phase 9.75i実装）:

  static box ProxyServer {
      static port = 8080  // 静的フィールド
  
      static main() {
          print("Starting proxy on port " + ProxyServer.port.toString())
      }
  }
  
  // 呼び出し
  ProxyServer.main()  // ✅ 静的メソッド直接呼び出し可能
  

• 静的関数の定義/呼び出し:

  static function Math.min(a, b) {
      if (a < b) { return a } else { return b }
  }
  local m = Math.min(1, 2)
  

• 所有権移転（outbox, static関数内のみ）:

  static function Factory.create() {
      outbox product
      product = new Item()
      return product
  }
  

11. 実行バックエンド選択とハイブリッド戦略 (2025-08-16更新)

Nyashは4つの実行方式をサポート。インタープリターは開発だけでなく本番でも実用的（Pythonのように）：

🌟 インタープリター併用戦略

開発時: インタープリター（即時実行・デバッグ・非同期フル対応）
本番時: インタープリター（多くのユースケースで十分高速）
        OR
        コンパイラ（性能要求時）
配布時: AOT native（最高性能）
Web時:  WASM（ブラウザ対応）

実行方法

# インタープリター実行（開発・本番両対応）
nyash program.nyash

# VM実行（高速実行）
nyash --backend vm program.nyash

# WASM生成（Web配布）
nyash --compile-wasm program.nyash

# ベンチマーク実行（性能比較）
nyash --benchmark --iterations 100

性能比較（実行速度）:

• WASM: 13.5倍高速化
• VM: 20.4倍高速化
• Interpreter: ベースライン（多くの場合十分高速）
• LLVM AOT: 100-1000倍高速化（Phase 10計画中）

インタープリターの価値:

• 即時実行: コンパイル不要で素早い開発サイクル
• 完全な非同期: Rust async/awaitで真の並行処理
• デバッグ容易: 実行時情報の完全把握
• 実用的性能: PythonやRubyが証明する十分な速度

詳細: docs/execution-backends.md

12. クイック実行（ローカル）

• ビルド: cargo build --release -j32
• 実行: ./target/release/nyash program.nyash
• WASM: ./target/release/nyash --compile-wasm program.nyash

---

最終更新: 2025年8月16日 - インタープリター併用戦略統合

• 🌟 インタープリター併用戦略: 開発・本番両対応の実用的実行モデル
• ✅ 静的boxメソッド呼び出し追加: Phase 9.75i実装機能
• ✅ ビルトインBox追加: FloatBox, SocketBox, BufferBox
• ✅ 実行バックエンド説明更新: インタープリターの本番価値明記

前回の革命的改善（Phase 9.75h）:

• 🌟 自動リテラル変換実装: 文字列・数値・真偽値の自動Box変換
• ✅ using nyashstd完全実装: 標準ライブラリアクセス機能完成
• ✅ birth構文追加: 「生命をBoxに与える」統一コンストラクタ

🚀 Nyashの実用的価値

Everything is Box哲学 + 使いやすさ + 実用的性能 の三位一体！

• 開発時: インタープリターで即時実行・完全デバッグ
• 本番時: インタープリター（十分高速）またはコンパイラ（最高性能）
• 将来: LLVM AOTで100-1000倍高速化（Phase 10）