# 機能設計書 56-env_default

## 概要

本ドキュメントは、Oh My Zshの`env_default`関数の機能設計を記載する。この関数は、環境変数が未定義の場合にデフォルト値を設定するユーティリティ関数である。

### 本機能の処理概要

`env_default`関数は、指定された環境変数がまだ定義されていない場合に限り、デフォルト値を設定してexportする。環境変数が既にexportされている場合は何もしない。これにより、環境変数の初期化処理を安全かつ簡潔に記述できる。

**業務上の目的・背景**：シェルスクリプトやプラグインの初期化処理において、ユーザーが設定していない環境変数にデフォルト値を割り当てる必要がある。この関数は、既存の設定を上書きせずにデフォルト値を安全に設定する方法を提供し、ユーザーのカスタマイズを尊重しながら合理的なデフォルト動作を実現する。環境変数は子プロセスに継承されるため、サブシェルや外部コマンドにも設定が引き継がれる。

**機能の利用シーン**：
- プラグインの初期化時に環境変数にデフォルト値を設定する場合
- 外部ツールやコマンドに渡す環境変数を初期化する場合
- ユーザーが設定していない場合のみデフォルト動作を適用したい場合

**主要な処理内容**：
1. zshの$parameters配列で環境変数（export属性を持つ変数）の存在をチェック
2. 環境変数が存在する場合は何もせず戻り値0を返す
3. 環境変数が存在しない場合はexportで設定し戻り値3を返す

**関連システム・外部連携**：zshの内部$parameters配列に依存。

**権限による制御**：特にロールによる制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 内部ユーティリティ関数のため関連画面なし |

## 機能種別

環境変数設定 / 初期化処理 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $1 (name) | string | Yes | 設定する環境変数名 | 有効なzsh変数名 |
| $2 (val) | string | Yes | デフォルト値 | なし |

### 入力データソース

コマンドライン引数として直接入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | なし | 出力なし |
| 戻り値 | integer | 0: 環境変数が既に存在していた、3: 環境変数を新規設定した |

### 出力先

- 環境変数（$1で指定された名前）
- 戻り値

## 処理フロー

### 処理シーケンス

```
1. 環境変数存在チェック
   └─ ${parameters[$1]} が *-export* を含むかチェック
2. 条件分岐
   ├─ 存在する場合: return 0
   └─ 存在しない場合: export で環境変数を設定し return 3
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{環境変数が存在?}
    B -->|Yes| C[何もしない]
    C --> D[戻り値 0 を返す]
    B -->|No| E[export で環境変数を設定]
    E --> F[戻り値 3 を返す]
    D --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-1 | export属性チェック | ${parameters[$1]}に-export-が含まれるかで環境変数の存在を判定 | 常時 |
| BR-56-2 | 上書き禁止 | 既存の環境変数値は上書きしない | 環境変数が既に存在する場合 |
| BR-56-3 | export設定 | export "$1=$2"で環境変数として設定する | 環境変数が存在しない場合 |
| BR-56-4 | 戻り値規約 | 既存時は0、新規設定時は3を返す | 常時 |

### 計算ロジック

環境変数存在チェックとデフォルト値設定：
```zsh
[[ ${parameters[$1]} = *-export* ]] && return 0
export "$1=$2" && return 3
```
- `${parameters[$1]}`：変数$1の属性を取得
- `*-export*`：export属性を持つかどうかをパターンマッチ
- `export "$1=$2"`：環境変数として設定（子プロセスに継承される）

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

### 操作別データベース影響一覧

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | なし | 通常のエラーケースは存在しない | - |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

連想配列への直接アクセスとパターンマッチのため、非常に高速。

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

- 動的な変数名を使用するため、信頼できない入力に対しては注意が必要
- 環境変数は子プロセスに継承されるため、機密情報の設定には注意が必要

## 備考

- default関数との違いは、この関数は環境変数（export属性を持つ変数）を対象とする点
- 戻り値3は慣例的な値であり、成功を示す0や一般的なエラーを示す1とは区別される
- 環境変数は子プロセスに継承されるが、通常の変数は継承されない

---

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

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

### 推奨読解順序

#### Step 1: 関数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | functions.zsh | `lib/functions.zsh` | env_default関数の定義（143-146行目） |

**読解のコツ**: zshの`${parameters[$1]}`構文（変数の属性情報を取得）と、`-export-`パターン（export属性の判定）を理解することがポイント。

#### Step 2: 関連コメントを読む

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | functions.zsh | `lib/functions.zsh` | 関数上部のコメント（134-142行目） |

**ドキュメントコメントの内容**:
- **Arguments**：引数の説明（1. name - 環境変数名、2. val - デフォルト値）
- **Return value**：戻り値の説明（0: 存在、3: 設定した）

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | functions.zsh | `lib/functions.zsh` | default関数（129-132行目） |

**defaultとの比較**:
- default: 通常の変数（typeset -g、$+parameters）
- env_default: 環境変数（export、parameters属性チェック）

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

```
env_default()
    │
    ├─ ${parameters[$1]} (zsh内部配列アクセス)
    │       │
    │       └─ [export属性チェック]
    │
    └─ export "$1=$2" [環境変数未定義時]
```

### データフロー図

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

変数名 $1 ─────────▶ ${parameters[$1]}
デフォルト値 $2           │
                         ├─ [*-export*一致] ──▶ 戻り値 0
                         │
                         └─ [不一致]
                                │
                                ▼
                         export $1=$2
                                │
                                ▼
                         環境変数 ──────────▶ 戻り値 3
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| functions.zsh | `lib/functions.zsh` | ソース | env_default関数およびdefault関数の定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/functions.zshを読み込むエントリポイント |
