# 機能設計書 4-カスタム設定読み込み

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）のカスタム設定読み込み機能に関する機能設計書である。ZSH_CUSTOM/*.zshからすべてのカスタム設定ファイルを読み込む処理について記述する。

### 本機能の処理概要

本機能は、OMZ初期化時にユーザーが定義したカスタム設定ファイルを読み込み、個人の環境設定やカスタマイズを適用する。

**業務上の目的・背景**：OMZの標準機能を変更せずに、ユーザー固有の設定やカスタマイズを追加する仕組みが必要である。カスタム設定ディレクトリを分離することで、OMZのアップデート時に設定が上書きされることを防ぎ、バージョン管理も容易になる。

**機能の利用シーン**：シェル起動時に自動実行される。ユーザーは$ZSH_CUSTOM/ディレクトリに.zsh拡張子のファイルを配置することで、独自の設定を追加できる。例えば、独自のエイリアス定義、環境変数設定、関数定義などを記述する。

**主要な処理内容**：
1. $ZSH_CUSTOMディレクトリの確認
2. *.zshファイルのグロブパターンマッチング
3. 各カスタム設定ファイルのsource

**関連システム・外部連携**：特になし（カスタム設定ファイル内で外部システムと連携する可能性あり）

**権限による制御**：特になし。カスタム設定ファイルへの読み取り権限が必要。

## 関連画面

本機能は画面を持たないバックエンド処理であり、直接関連する画面はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | シェル起動時に自動実行 |

## 機能種別

初期化処理 / 設定読み込み

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ZSH_CUSTOM | 環境変数(文字列) | No | カスタム設定ディレクトリ | 未定義時は$ZSH/custom |

### 入力データソース

- $ZSH_CUSTOM/以下の.zshファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 関数群 | 関数 | カスタム設定ファイルで定義された関数 |
| エイリアス群 | エイリアス | カスタム設定ファイルで定義されたエイリアス |
| 変数群 | 変数 | カスタム設定ファイルで定義された変数 |

### 出力先

- シェル環境（関数、エイリアス、変数等）

## 処理フロー

### 処理シーケンス

```
1. カスタム設定ファイルの検索
   └─ $ZSH_CUSTOM/*.zshのグロブパターンでファイル一覧取得
   └─ (N)修飾子によりマッチしない場合は空配列

2. カスタム設定ファイルの読み込み
   └─ 各ファイルを順次source
   └─ サブディレクトリは対象外

3. 変数クリーンアップ
   └─ config_file変数をunset
```

### フローチャート

```mermaid
flowchart TD
    A[初期化開始] --> B{ZSH_CUSTOM/*.zshファイル存在?}
    B -->|Yes| C[ファイルループ開始]
    B -->|No| D[処理スキップ]
    C --> E[config_fileにファイルパス代入]
    E --> F[source config_file]
    F --> G{次のファイルあり?}
    G -->|Yes| E
    G -->|No| H[config_file変数unset]
    D --> I[完了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ファイル拡張子制限 | .zsh拡張子のファイルのみ読み込む | 常時 |
| BR-02 | 直下ディレクトリのみ | サブディレクトリ内のファイルは読み込まない | 常時 |
| BR-03 | プラグイン・テーマ後に実行 | カスタム設定はプラグインとテーマの後に読み込まれる | 常時 |
| BR-04 | 存在しない場合はスキップ | $ZSH_CUSTOM/*.zshにマッチするファイルがない場合は何もしない | 常時 |
| BR-05 | ファイル名順で読み込み | グロブパターンのデフォルト順序（アルファベット順）で読み込む | 常時 |

### 計算ロジック

**グロブパターンマッチング**:
```zsh
for config_file ("$ZSH_CUSTOM"/*.zsh(N)); do
  source "$config_file"
done
```

- `(N)`: nullglob修飾子。マッチするファイルがない場合、エラーを発生させずに空の結果を返す

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | カスタム設定ファイルに構文エラーがある場合 | ZSHがエラーメッセージを出力 |

### リトライ仕様

リトライは行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- カスタム設定ファイルの読み込みはシェル起動時間に影響するため、必要最小限のファイル数にすることを推奨
- 各ファイル内での処理は効率的に記述することを推奨

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

- カスタム設定ファイルは任意のZSHコードを実行するため、信頼できる内容のみを配置すること
- ZSH_CUSTOMディレクトリのパーミッションを適切に設定し、他者が書き込みできないようにすること
- 第三者から取得したカスタム設定ファイルは内容を確認してから使用すること

## 備考

- カスタム設定は.zshrc編集の代替として推奨される
- example.zshファイルがテンプレートとして提供されている場合がある
- `*.zsh`以外の拡張子（`.sh`等）のファイルは読み込まれないため注意

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

カスタム設定システムで扱う変数とファイル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | ZSH_CUSTOM変数の定義と用途 |

**読解のコツ**:
- ZSH_CUSTOMはデフォルトで$ZSH/custom
- プラグイン、テーマ、直下の.zshファイルを配置可能

#### Step 2: ZSH_CUSTOM初期化を理解する

ZSH_CUSTOM変数の初期化を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 53-55行目のZSH_CUSTOM初期化 |

**主要処理フロー**:
- **55行目**: `[[ -n "$ZSH_CUSTOM" ]] || ZSH_CUSTOM="$ZSH/custom"` - 未定義時のデフォルト設定

#### Step 3: カスタム設定読み込みを理解する

カスタム設定ファイルの読み込み処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 208-212行目のカスタム設定読み込み |

**主要処理フロー**:
- **209行目**: `for config_file ("$ZSH_CUSTOM"/*.zsh(N)); do` - グロブパターンでファイル検索
  - `(N)`: nullglob修飾子（マッチなしでもエラーにならない）
- **210行目**: `source "$config_file"` - ファイル読み込み
- **212行目**: `unset config_file` - 変数クリーンアップ

#### Step 4: 読み込み順序を理解する

カスタム設定がいつ読み込まれるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 195-231行目の全体の流れ |

**読み込み順序**:
1. **197-200行目**: ライブラリ読み込み（lib/*.zsh）
2. **203-206行目**: プラグイン読み込み（plugins配列）
3. **209-212行目**: カスタム設定読み込み（$ZSH_CUSTOM/*.zsh）
4. **221-231行目**: テーマ読み込み（ZSH_THEME）

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

```
oh-my-zsh.sh (初期化時)
    │
    ├─ lib/*.zsh読み込み
    │
    ├─ plugins読み込み
    │
    ├─ カスタム設定読み込み ←【本機能】
    │      │
    │      └─ for config_file ("$ZSH_CUSTOM"/*.zsh(N))
    │             └─ source "$config_file"
    │
    └─ テーマ読み込み
```

### データフロー図

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

$ZSH_CUSTOM/*.zsh     ───▶ oh-my-zsh.sh
                              │
                              ├─▶ グロブパターン展開 ──────▶ ファイルリスト
                              │
                              └─▶ source ループ ──────────▶ 関数・エイリアス・
                                                            変数定義
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | カスタム設定読み込みのエントリーポイント |
| *.zsh | `$ZSH_CUSTOM/*.zsh` | 設定 | ユーザーカスタム設定ファイル |
| example.zsh | `$ZSH_CUSTOM/example.zsh` | 設定（例） | カスタム設定のテンプレート例 |
