# 機能設計書 10-エラー処理

## 概要

本ドキュメントは、Nushellにおけるエラー処理機能について定義する。try-catch構文によるエラーハンドリングと、error makeコマンドによるカスタムエラー生成を提供する。

### 本機能の処理概要

**業務上の目的・背景**：スクリプト実行中にエラーが発生した場合、適切にハンドリングして処理を継続したり、ユーザーにわかりやすいエラーメッセージを提示したりする必要がある。Nushellのエラー処理機能は、構造化されたエラー情報と柔軟なハンドリング機構を提供する。

**機能の利用シーン**：
- 外部コマンド実行時のエラーハンドリング
- ファイル操作失敗時のリカバリ
- バリデーションエラーの生成
- エラーのチェーン（連鎖）による詳細なエラー情報提供

**主要な処理内容**：
1. `try { ... }` - エラーをキャッチせずに無視
2. `try { ... } catch { ... }` - エラーをキャッチして処理
3. `try { ... } catch { |err| ... }` - エラー情報を受け取って処理
4. `try { ... } finally { ... }` - エラー有無に関わらず実行
5. `error make` - カスタムエラーの生成
6. エラーのチェーン（inner errors）

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | エラー処理の実行 |

## 機能種別

エラーハンドリング / 例外処理

## 入力仕様

### 入力パラメータ

#### try コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| try_block | Block | Yes | 実行するブロック | 有効なブロック |
| catch | Keyword(catch, Closure) | No | エラー時のクロージャ | - |
| finally | Keyword(finally, Closure) | No | 常に実行するクロージャ | - |

#### error make コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| error_struct | Record/String | No | エラー構造体または文字列 | - |
| --unspanned | Switch | No | ラベルを削除 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PipelineData | PipelineData | tryブロックまたはcatchブロックの結果 |
| ShellError | Error | error makeが生成するエラー |

### 出力先

- パイプライン後段
- エラー表示

## 処理フロー

### 処理シーケンス

```
1. try
   └─ try_blockを評価
   └─ エラー発生時: catchブロックを評価
   └─ finally指定時: finallyブロックを評価
2. error make
   └─ error_structを解析
   └─ LabeledErrorを構築
   └─ ShellErrorを返却
```

### フローチャート

```mermaid
flowchart TD
    A[try] --> B[try_block評価]
    B --> C{エラー発生?}
    C -->|No| D{finally?}
    C -->|Yes| E{catch?}
    E -->|Yes| F[catchブロック評価]
    E -->|No| G[エラー無視]
    F --> D
    G --> D
    D -->|Yes| H[finallyブロック評価]
    D -->|No| I[結果返却]
    H --> I
    J[error make] --> K{入力種別}
    K -->|Record| L[ErrorInfo解析]
    K -->|String| M[msg設定]
    L --> N[LabeledError構築]
    M --> N
    N --> O[ShellError返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | catchパラメータ | `catch { \|err\| ... }` でエラー情報を受け取る | catch指定時 |
| BR-002 | finally実行 | finallyはエラー有無に関わらず実行 | finally指定時 |
| BR-003 | エラーチェーン | innerでエラーをチェーン可能 | error make |
| BR-004 | ラベル位置 | labelsでソース位置を指定可能 | error make |
| BR-005 | 外部ソース | srcで外部ファイルのエラー位置を指定 | error make |

### 計算ロジック

特になし。

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

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

## エラー処理

### error_struct構造

```
{
  msg: string,         # 必須: エラーメッセージ
  code: string,        # オプション: エラーコード
  labels: table,       # オプション: ラベル情報
  help: string,        # オプション: ヘルプメッセージ
  url: string,         # オプション: 参照URL
  inner: table,        # オプション: チェーンエラー
  src: record          # オプション: 外部ソース情報
}
```

### リトライ仕様

リトライは行わない。try-catchでユーザーが実装可能。

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

エラー処理はトランザクション管理を行わない。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- tryはパーサーキーワードとして実装
- IRモードではtryのrunは呼び出されない
- error makeは通常のコマンドとして実装

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | try_.rs | `crates/nu-cmd-lang/src/core_commands/try_.rs` | tryコマンドの実装 |
| 1-2 | error_make.rs | `crates/nu-cmd-lang/src/core_commands/error_make.rs` | error makeコマンドの実装 |

**主要処理フロー（try_.rs）**:
- **16-61行目**: シグネチャ定義。try_block, catch, finally
- **72-85行目**: run関数（IRモードでは呼び出されない）
- **87-110行目**: examples

**主要処理フロー（error_make.rs）**:
- **12-22行目**: シグネチャ定義。error_struct, --unspanned
- **24-65行目**: extra_description（error_struct構造の説明）
- **120-161行目**: run関数（エラー構築ロジック）
- **163-192行目**: ErrorInfo構造体

#### Step 2: エラー構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | errors/ | `crates/nu-protocol/src/errors/` | ShellError, ParseError 等 |

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

```
try { ... } catch { |err| ... }
    │
    ├─ IRモード
    │      └─ IRコンパイラが特別処理
    │             ├─ try_block評価
    │             ├─ エラー時: catch評価
    │             └─ finally評価
    │
    └─ 非IRモード
           └─ Try.run（unreachable）

error make { msg: "..." }
    │
    └─ ErrorMake.run
           ├─ error_struct解析
           ├─ ErrorInfo構築
           ├─ パイプライン入力のinner追加
           └─ ShellError返却
```

### データフロー図

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

try { cmd }
    │
    ▼
try_block評価 ───▶ エラー発生? ───▶ catch評価
                       │                │
                       ▼                ▼
                  finally評価 ◀────────┘
                       │
                       ▼
                  結果/エラー

error make {msg: "x"}
    │
    ▼
ErrorInfo解析 ───▶ LabeledError構築 ───▶ ShellError
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| try_.rs | `crates/nu-cmd-lang/src/core_commands/try_.rs` | ソース | tryコマンド |
| error_make.rs | `crates/nu-cmd-lang/src/core_commands/error_make.rs` | ソース | error makeコマンド |
| error.rs | `crates/nu-cmd-lang/src/core_commands/error.rs` | ソース | errorコマンド（ヘルプ） |
| errors/ | `crates/nu-protocol/src/errors/` | ソース | エラー型定義 |
| shell_error.rs | `crates/nu-protocol/src/errors/shell_error.rs` | ソース | ShellError |
| parse_error.rs | `crates/nu-protocol/src/errors/parse_error.rs` | ソース | ParseError |
