# 機能設計書 55-default

## 概要

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

### 本機能の処理概要

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

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

**機能の利用シーン**：
- プラグインの初期化時に設定変数にデフォルト値を設定する場合
- ユーザーが設定していない場合のみデフォルト動作を適用したい場合
- 設定ファイルの読み込み前にデフォルト値を準備する場合

**主要な処理内容**：
1. zshの$parameters配列で変数の存在をチェック
2. 変数が存在する場合は何もせず戻り値0を返す
3. 変数が存在しない場合はtypeset -gでグローバル変数として設定し戻り値3を返す

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

- グローバル変数（$1で指定された名前）
- 戻り値

## 処理フロー

### 処理シーケンス

```
1. 変数存在チェック
   └─ (( $+parameters[$1] )) で変数の存在を確認
2. 条件分岐
   ├─ 存在する場合: return 0
   └─ 存在しない場合: typeset -g で変数を設定し return 3
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-1 | 存在チェック | $+parameters構文で変数の存在を確認する | 常時 |
| BR-55-2 | 上書き禁止 | 既存の変数値は上書きしない | 変数が既に存在する場合 |
| BR-55-3 | グローバル設定 | typeset -gでグローバル変数として設定する | 変数が存在しない場合 |
| BR-55-4 | 戻り値規約 | 既存時は0、新規設定時は3を返す | 常時 |

### 計算ロジック

変数存在チェックとデフォルト値設定：
```zsh
(( $+parameters[$1] )) && return 0
typeset -g "$1"="$2"   && return 3
```
- `$+parameters[$1]`：$parameters配列にキー$1が存在する場合1、そうでない場合0
- `(( ... ))`：算術式として評価、0の場合false、非0の場合true
- `typeset -g`：グローバルスコープで変数を定義

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

連想配列への直接アクセスのため、非常に高速（O(1)）。

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

- 動的な変数名を使用するため、信頼できない入力に対しては注意が必要
- typeset -gはグローバル変数を設定するため、意図しない変数の変更に注意

## 備考

- env_default関数との違いは、この関数は通常の変数を対象とし、env_defaultは環境変数（export）を対象とする点
- 戻り値3は慣例的な値であり、成功を示す0や一般的なエラーを示す1とは区別される

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: zshの`$+parameter`構文（パラメータが設定されていれば1、そうでなければ0を返す）と、`typeset -g`（グローバル変数の設定）を理解することがポイント。

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

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

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

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

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

**env_defaultとの比較**:
- default: 通常の変数（typeset -g）
- env_default: 環境変数（export）

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

```
default()
    │
    ├─ $+parameters[$1] (zsh内部配列アクセス)
    │       │
    │       └─ [存在チェック]
    │
    └─ typeset -g "$1"="$2" [変数未定義時]
```

### データフロー図

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

変数名 $1 ─────────▶ $+parameters[$1]
デフォルト値 $2           │
                         ├─ [存在する] ──────▶ 戻り値 0
                         │
                         └─ [存在しない]
                                │
                                ▼
                         typeset -g $1=$2
                                │
                                ▼
                         グローバル変数 ────▶ 戻り値 3
```

### 関連ファイル一覧

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