# 機能設計書 4-制御構文

## 概要

本ドキュメントは、Nushellにおける制御フロー構文（if/for/while/loop/match/try）について定義する。これらの構文はプログラムの実行フローを制御し、条件分岐、ループ処理、パターンマッチング、エラーハンドリングを実現する。

### 本機能の処理概要

**業務上の目的・背景**：制御構文はあらゆるプログラミング言語の基盤であり、複雑なロジックの実装を可能にする。Nushellは関数型プログラミングのパラダイムを取り入れつつ、従来のシェルユーザーにも馴染みやすい構文を提供している。

**機能の利用シーン**：
- 条件に基づく処理の分岐（if/else）
- コレクションの繰り返し処理（for）
- 条件付きループ（while）
- 無限ループ（loop + break）
- パターンに基づく分岐（match）
- エラーハンドリング（try/catch/finally）

**主要な処理内容**：
1. `if/else` - 条件式に基づく分岐処理
2. `for` - コレクションまたはレンジのイテレーション
3. `while` - 条件が真の間のループ
4. `loop` - 無限ループ（breakで脱出）
5. `match` - パターンマッチングによる分岐
6. `try/catch/finally` - エラーハンドリング

**関連システム・外部連携**：nu-parser（構文解析）、nu-engine（評価）と連携する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | 制御構文の入力と実行 |

## 機能種別

制御フロー / 条件分岐 / ループ処理

## 入力仕様

### 入力パラメータ

#### if コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cond | MathExpression | Yes | 条件式 | ブール値に評価可能 |
| then_block | Block | Yes | 条件が真の場合に実行するブロック | 有効なブロック |
| else_expression | Keyword(else, Block/Expression) | No | elseブランチ | - |

#### for コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| var_name | VarWithOptType | Yes | ループ変数名 | 有効な識別子 |
| range | Keyword(in, Any) | Yes | イテレート対象 | イテラブル |
| block | Block | Yes | 実行ブロック | 有効なブロック |

#### while コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cond | MathExpression | Yes | 継続条件 | ブール値に評価可能 |
| block | Block | Yes | ループ本体 | 有効なブロック |

#### loop コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| block | Block | Yes | ループ本体 | 有効なブロック |

#### match コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| value | Any | Yes | マッチ対象の値 | - |
| match_block | MatchBlock | Yes | パターンとブランチのブロック | 有効なマッチブロック |

### 入力データソース

- ユーザーからのコマンドライン入力
- スクリプトファイル
- パイプライン入力（matchなど）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PipelineData | PipelineData | ブロック評価結果（if/matchは値を返す） |

### 出力先

- パイプライン後段
- 変数への代入（式として使用時）

## 処理フロー

### 処理シーケンス

```
1. if/else
   └─ 条件式を評価
   └─ 真ならthen_block、偽ならelse_expressionを評価
2. for
   └─ rangeをイテレータに変換
   └─ 各要素でvar_nameにバインドしblockを評価
3. while
   └─ 条件を評価
   └─ 真ならblockを評価し、繰り返す
4. loop
   └─ blockを繰り返し評価
   └─ breakで脱出
5. match
   └─ valueを評価
   └─ 各パターンとマッチを試行
   └─ マッチしたブランチを評価
```

### フローチャート

```mermaid
flowchart TD
    A[制御構文] --> B{種別}
    B -->|if| C[条件評価]
    C --> D{真?}
    D -->|Yes| E[then_block評価]
    D -->|No| F{else あり?}
    F -->|Yes| G[else評価]
    F -->|No| H[Empty返却]
    B -->|for| I[range評価]
    I --> J{要素あり?}
    J -->|Yes| K[変数バインド]
    K --> L[block評価]
    L --> J
    J -->|No| M[終了]
    B -->|while| N[条件評価]
    N --> O{真?}
    O -->|Yes| P[block評価]
    P --> N
    O -->|No| Q[終了]
    B -->|loop| R[block評価]
    R --> S{break?}
    S -->|Yes| T[終了]
    S -->|No| R
    B -->|match| U[value評価]
    U --> V[パターンマッチ]
    V --> W[マッチしたブランチ評価]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | if式 | ifは値を返す式として使用可能 | let x = if ... |
| BR-002 | match式 | matchは値を返す式として使用可能 | let x = match ... |
| BR-003 | breakによる脱出 | loop/for/whileからbreakで脱出可能 | ループ内 |
| BR-004 | continueによるスキップ | loop/for/whileでcontinueで次イテレーション | ループ内 |
| BR-005 | matchガード | パターンに追加条件（if）を指定可能 | match内 |
| BR-006 | matchワイルドカード | _ でデフォルトケースを指定 | match内 |

### 計算ロジック

特になし。

## データベース操作仕様

本機能はデータベース操作を直接行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TypeMismatch | 型エラー | 条件式がブール値でない | 条件式を確認 |
| BreakOutsideOfLoop | 制御エラー | ループ外でbreak使用 | ループ内で使用 |
| ContinueOutsideOfLoop | 制御エラー | ループ外でcontinue使用 | ループ内で使用 |
| NonExhaustiveMatch | パターンエラー | matchが全ケースをカバーしていない | _ を追加 |

### リトライ仕様

リトライは行わない。

## トランザクション仕様

制御構文はトランザクション管理を行わない。

## パフォーマンス要件

- IRコンパイルにより効率的なジャンプ命令に変換
- ループのオーバーヘッドは最小限

## セキュリティ考慮事項

- 無限ループはCtrl+Cで中断可能

## 備考

- 全ての制御構文はパーサーキーワードとして実装
- IRモードではrun関数は呼び出されない（IRコンパイラが直接処理）
- ifとmatchはconst評価（パース時評価）も可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: コマンド定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | if_.rs | `crates/nu-cmd-lang/src/core_commands/if_.rs` | ifコマンドの実装。run_const対応 |
| 1-2 | for_.rs | `crates/nu-cmd-lang/src/core_commands/for_.rs` | forコマンドの実装 |
| 1-3 | while_.rs | `crates/nu-cmd-lang/src/core_commands/while_.rs` | whileコマンドの実装 |
| 1-4 | loop_.rs | `crates/nu-cmd-lang/src/core_commands/loop_.rs` | loopコマンドの実装 |
| 1-5 | match_.rs | `crates/nu-cmd-lang/src/core_commands/match_.rs` | matchコマンドの実装 |

**読解のコツ**: 全コマンドがCommandType::Keywordを返し、run関数はIRモードでは使われない。

#### Step 2: シグネチャを理解する

**主要処理フロー（if_.rs）**:
- **19-40行目**: シグネチャ定義。cond, then_block, else_expression
- **51-53行目**: is_const = true（パース時評価対応）
- **55-94行目**: run_const（パース時の条件評価）

**主要処理フロー（match_.rs）**:
- **16-26行目**: シグネチャ定義。value, match_block（SyntaxShape::MatchBlock）
- **52-98行目**: examples（パターンマッチの各種例）

#### Step 3: パターンマッチを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | parse_patterns.rs | `crates/nu-parser/src/parse_patterns.rs` | パターン構文の解析 |

### プログラム呼び出し階層図

```
制御構文の評価（IRコンパイラ経由）
    │
    ├─ if
    │      ├─ 条件評価
    │      └─ ブランチ選択・評価
    │
    ├─ for
    │      ├─ イテレータ生成
    │      └─ 各要素でブロック評価
    │
    ├─ while
    │      ├─ 条件評価
    │      └─ ブロック評価（繰り返し）
    │
    ├─ loop
    │      └─ ブロック評価（無限繰り返し）
    │
    └─ match
           ├─ 値評価
           ├─ パターンマッチング
           └─ ブランチ評価
```

### データフロー図

```
[入力]                  [処理]                       [出力]

if cond { A } else { B }
    │
    ▼
条件評価 ───▶ true/false
    │
    ▼
ブランチ選択 ───▶ A または B の評価結果

match value { pattern => result }
    │
    ▼
value評価 ───▶ Value
    │
    ▼
パターンマッチ ───▶ マッチしたブランチの評価結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| if_.rs | `crates/nu-cmd-lang/src/core_commands/if_.rs` | ソース | ifコマンド |
| for_.rs | `crates/nu-cmd-lang/src/core_commands/for_.rs` | ソース | forコマンド |
| while_.rs | `crates/nu-cmd-lang/src/core_commands/while_.rs` | ソース | whileコマンド |
| loop_.rs | `crates/nu-cmd-lang/src/core_commands/loop_.rs` | ソース | loopコマンド |
| match_.rs | `crates/nu-cmd-lang/src/core_commands/match_.rs` | ソース | matchコマンド |
| break_.rs | `crates/nu-cmd-lang/src/core_commands/break_.rs` | ソース | breakコマンド |
| continue_.rs | `crates/nu-cmd-lang/src/core_commands/continue_.rs` | ソース | continueコマンド |
| parse_patterns.rs | `crates/nu-parser/src/parse_patterns.rs` | ソース | パターン解析 |
| parse_keywords.rs | `crates/nu-parser/src/parse_keywords.rs` | ソース | キーワード解析 |
