hakorune/docs/guides/loopform.md

# LoopForm ガイド — ループ正規化（ユーザーマクロ）

目的
- while/for/foreach を Nyash のユーザーマクロで“キャリア（タプル）”に正規化し、MIR/LLVMにとって最適化しやすい形へ落とし込む。

使い方（予定）
- マクロ登録（例）:
```
export NYASH_MACRO_ENABLE=1
export NYASH_MACRO_PATHS=apps/macros/examples/loop_normalize_macro.hako
```
- 自己ホスト前展開（auto）を利用して、parse直後にLoopForm展開を有効化（PyVM環境）。

JSON生成ユーティリティ（JsonBuilder）
- ループ正規化では AST JSON v0 の断片を安全に構成する必要があります。
- 最小ユーティリティとして `apps/lib/json_builder.hako` を提供しています（includeで読み込み、文字列でJSON断片を生成）。
- 例:
```
local JB = include "apps/lib/json_builder.hako"
local v_i   = JB.variable("i")
local v_sum = JB.variable("sum")
local lit_0 = JB.literal_int(0)
local assign = JB.assignment(v_i, JB.binary("+", v_i, JB.literal_int(1)))
```

正規化の考え方
- ループで更新される変数群をタプルに束ね、ヘッダに“1個のφ”を置く。
- break/continue は“次キャリア”または“現キャリア”で遷移し、一貫した合流点を保つ。

キャリア正規化（MVP-2）の具体例
- 前提: break/continue なし、更新変数は最大2個（例: i と sum）。

例1: 基本的な while（i を 0..n-1 で加算）

Nyash（入力・素朴形）
```
local i = 0
local sum = 0
while (i < n) {
  sum = sum + i
  i = i + 1
}
```

正規化の狙い（概念）
- ループ本体の末尾に更新（Assignment）をそろえる（既に末尾ならそのまま）。
- ループヘッダの合流で i と sum を同一グループの PHI でまとめやすくする。

AST JSON v0 のスケッチ（JsonBuilder を用いた生成例）
```
local JB   = include "apps/lib/json_builder.hako"
local v_i  = JB.variable("i")
local v_s  = JB.variable("sum")
local v_n  = JB.variable("n")

// 先頭（ローカル導入）
local i0   = JB.local_decl("i", JB.literal_int(0))
local s0   = JB.local_decl("sum", JB.literal_int(0))

// 条件と本体（更新は末尾に揃える）
local cond = JB.binary("<", v_i, v_n)
local body_nonassign = JB.block([
  JB.assignment(v_s, JB.binary("+", v_s, v_i))
])
local body_updates   = JB.block([
  JB.assignment(v_i, JB.binary("+", v_i, JB.literal_int(1)))
])

// ループノード（MVP: while→Loop; キャリアは概念上）
local loop_node = JB.loop(cond, JB.concat_blocks(body_nonassign, body_updates))

JB.program([ i0, s0, loop_node ])
```

備考
- MVP-2 では“新しいキャリア用ノード”は導入せず、既存の Local/If/Loop/Assignment で表現する。
- 「非代入→代入」の順を崩すと意味が変わる可能性があるため、再配置は安全にできる場合のみ行う（既に末尾に更新がある等）。

例2: 2変数更新の順序混在（安全な並べ替え）
```
while (i < n) {
  print(i)
  sum = sum + i
  i = i + 1
}
```
- 正規化: 非代入（print）→ 代入(sum) → 代入(i) の末尾整列。
- 非代入が末尾に来るケースは再配置しない（意味が変わりうるため、スキップ）。

今後の拡張（MVP-3 概要）
- continue: 「次キャリア」へ（更新後にヘッダへ戻す）。
- break: 「現キャリア」を exit へ（ヘッダ合流と衝突しないよう保持）。
- いずれも 1 段ネストまでの最小対応から開始。

MVP-3（実装済み・最小対応）
- 本体を break/continue でセグメント分割し、各セグメント内のみ安全に「非代入→代入」に整列。
- ガード:
  - 代入先は変数のみ（フィールド等は対象外）
  - 全体の更新変数は最大2種（MVP-2 制約を継承）
  - セグメント内で「代入の後に非代入」があれば整列しない（順序保持）
- スモーク（v2）: `tools/smokes/v2/run.sh --profile quick --filter "loopform|macro"`

for / foreach の糖衣と正規化（概要）
- for: `for(fn(){ init }, cond, fn(){ step }, fn(){ body })` を `init; loop(cond){ body; step }` へ正規化。
  - init/step は `Assignment`/`Local` 単体でも可。
- foreach: `foreach(arr, "x", fn(){ body })` を `__ny_i` で走査する Loop へ正規化し、`x` を `arr.get(__ny_i)` に置換。
- スモーク（v2）: `tools/smokes/v2/run.sh --profile quick --filter "macro|foreach|for"`

対応状況（MVP→順次拡張）
- Week1: while（break/continue無し）
- Week2: break/continue/ネスト最小対応、キャリア自動抽出
- Week3: for/foreach（限定）

制約（MVP）
- try/finally/throwとの相互作用は未対応。例外は後続フェーズで設計を明記。

検証
- macro‑golden（展開後ASTのゴールデン）
- LLVM PHI健全性スモーク（空PHI無し、先頭グループ化）
 - 出力一致スモーク（two‑vars の実行出力が同一であること）

手元での確認
- ゴールデン（キー順無視の比較）
  - `tools/test/golden/macro/loop_simple_user_macro_golden.sh`
  - `tools/test/golden/macro/loop_two_vars_user_macro_golden.sh`
 - 出力一致スモーク（VM, v2）
   - `tools/smokes/v2/run.sh --profile quick --filter "loop_two_vars|macro"`
 - 自己ホスト前展開（PyVM 経由）
  - `NYASH_VM_USE_PY=1 NYASH_USE_NY_COMPILER=1 NYASH_MACRO_ENABLE=1 NYASH_MACRO_PATHS=apps/macros/examples/loop_normalize_macro.hako ./target/release/hakorune --macro-preexpand --backend vm apps/tests/macro/loopform/simple.hako`

Selfhost compiler prepass（恒等→最小正規化）
- Runner が `NYASH_LOOPFORM_NORMALIZE=1` を `--loopform` にマップして子に渡し、`apps/lib/loopform_normalize.hako` の前処理を適用（現状は恒等）。
- 既定OFF。将来、キー順正規化→簡易キャリア整列を段階的に追加する。

実装メモ（内蔵変換ルート / Rust）
- 既定のマクロ実行は internal‑child（Rust内蔵）です。LoopNormalize は以下の保守的なガードで正規化します。
  - トップレベル本体に Break/Continue がないこと
  - 代入対象は最大2変数、かつ単純な変数（フィールド代入などは除外）
  - 代入の後ろに非代入が現れない（安全に末尾整列できる）
- 条件を満たす場合のみ「非代入→代入」の順でボディを再構成します（意味は不変）。

参考
- docs/private/roadmap2/phases/phase-17-loopform-selfhost/