# 画面設計書 10-omz theme set

## 概要

本ドキュメントは、Oh My Zshの`omz theme set`コマンドインターフェースの画面設計書です。指定されたテーマを.zshrcに永続的に設定し、シェルセッションをリロードする機能を定義します。

### 本画面の処理概要

`omz theme set`コマンドは、指定されたテーマを.zshrcファイルのZSH_THEME変数に設定し、自動的にシェルセッションをリロードしてテーマを適用します。次回以降のシェル起動時にも同じテーマが適用されます。

**業務上の目的・背景**：テーマを恒久的に変更する場合、.zshrcファイルを手動で編集する必要がありました。手動編集はミスの原因となり、特に初心者ユーザーにとっては.zshrcの構文を理解することが困難です。本コマンドにより、安全かつ簡単にテーマを永続設定でき、即座に新しいテーマが適用されます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz theme set <theme>` - 指定テーマを.zshrcに設定

**主要な操作・処理内容**：
1. 指定されたテーマの存在を確認（カスタム/ビルトインディレクトリ）
2. AWKスクリプトを使用して.zshrcのZSH_THEME行を更新
3. 元の.zshrcを.zshrc.bckとしてバックアップ
4. 新しい.zshrcの構文チェックを実行
5. 構文エラーがあればロールバック
6. 成功した場合、シェルセッションをリロード

**画面遷移**：
- 遷移元：`omz theme`コマンドから
- 遷移先：処理完了後、`_omz::reload`によりシェルセッションが再起動される

**権限による表示制御**：なし。ただし、.zshrcファイルへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてテーマを永続設定 |
| 14 | omz theme set | 主機能 | .zshrcにテーマを設定し、シェルをリロード |
| 17 | omz reload | 補助機能 | テーマ設定後にzshセッションをリスタート |

## 画面種別

設定変更（テーマ永続設定）

## URL/ルーティング

```
omz theme set <theme>
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| theme | string | はい | 設定するテーマ名 |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| 成功メッセージ | 標準エラー出力（stderr） | テーマ設定完了の通知 |
| エラーメッセージ | 標準エラー出力（stderr） | 処理失敗時のエラー |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| エラー：未発見 | テーマが見つからない場合のエラー | `omz theme set: <name> theme not found` |
| 成功：設定完了 | テーマ設定成功時のメッセージ | `omz theme set: '<name>' theme set correctly.` |
| エラー：設定失敗 | .zshrc更新失敗時のエラー | `omz theme set: error setting theme.` |
| エラー：構文エラー | .zshrcの構文チェック失敗時 | `omz theme set: broken syntax in '~/.zshrc'. Rolling back changes...` |

## イベント仕様

### 1-テーマ永続設定イベント

**トリガー**：`omz theme set <theme>`コマンドの実行

**処理フロー**：
1. 引数の存在を検証
2. テーマファイルの存在を確認（カスタム/ビルトインディレクトリ）
3. AWKスクリプトを生成して.zshrcのZSH_THEME行を更新
4. 元の.zshrcを.zshrc.bckにバックアップ
5. 新しい.zshrcの構文チェック（`zsh -n`）
6. 構文エラーがあれば.zshrc.bckからロールバック
7. 成功メッセージを表示
8. インタラクティブセッションの場合、`_omz::reload`を呼び出し

**データの流れ**：
```
ユーザー入力 → テーマ確認 → AWKスクリプト生成 → .zshrc更新 → 構文チェック → リロード
```

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| テーマ設定 | ~/.zshrc | UPDATE | ZSH_THEME変数を更新 |
| バックアップ作成 | ~/.zshrc.bck | INSERT | 元の.zshrcをバックアップ |

### テーブル別更新項目詳細

#### ~/.zshrc

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | ZSH_THEME="..." | 指定されたテーマ名に更新 | `# set by \`omz\``コメント付き |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz theme set <theme>` | テーマ名が指定されていない場合 |
| エラー | `<theme> theme not found` | テーマファイルが見つからない場合 |
| 成功 | `'<theme>' theme set correctly.` | テーマ設定成功時 |
| エラー | `error setting theme.` | .zshrc更新失敗時 |
| エラー | `broken syntax in '~/.zshrc'. Rolling back changes...` | 構文チェック失敗時 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | 使用方法を表示 | 1 |
| テーマ未発見 | エラーメッセージを表示 | 1 |
| .zshrc更新失敗 | エラーメッセージを表示 | 非0 |
| 構文チェック失敗 | ロールバックしてエラーを表示 | 1 |

## 備考

- AWKスクリプトは`ZSH_THEME=`で始まる行を検出し、新しいテーマ名に置換
- 既存のZSH_THEME行がない場合、.zshrcの先頭にZSH_THEME行を追加
- 設定された行には`# set by \`omz\``コメントが追加される
- バックアップファイル（.zshrc.bck）は上書きされるため、直前のバックアップのみ保持
- 非インタラクティブセッション（スクリプト実行時など）ではリロードは実行されない
- `$ZDOTDIR`環境変数が設定されている場合、そのディレクトリの.zshrcが更新される

---

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

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

### 推奨読解順序

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

テーマ永続設定機能で使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | 行811-824でAWKスクリプトの構造を確認 |

**読解のコツ**: AWKスクリプト内の`set`変数は、ZSH_THEME行が見つかって置換されたかを追跡するフラグです。`!set`は「まだ置換されていない」を意味します。

#### Step 2: エントリーポイントを理解する

テーマ永続設定コマンドのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::theme::set`関数（796-860行目）が処理の本体 |

**主要処理フロー**:
1. **行797-800**: 引数チェック
2. **行802-808**: テーマファイルの存在確認
3. **行810-825**: AWKスクリプトの定義
4. **行827-840**: AWKで.zshrcを更新、ZSH_THEME行がない場合は先頭に追加

#### Step 3: AWKスクリプトのロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行811-817でZSH_THEME行の検出と置換を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行819-823でEND処理を確認 |

**主要処理フロー**:
- **行812**: `!set`かつ`ZSH_THEME=`で始まる行を検出
- **行813**: `set=1`フラグを設定
- **行814**: 行全体を`ZSH_THEME="<theme>" # set by \`omz\``に置換
- **行821-823**: AWK終了時に`set`フラグがなければエラー終了（`exit 1`）
- **行829-837**: AWKがエラー終了した場合（ZSH_THEME行がなかった場合）、先頭にZSH_THEME行を追加

#### Step 4: 構文チェックとリロードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 行848-853で構文チェックとロールバックを確認 |
| 4-2 | cli.zsh | `lib/cli.zsh` | 行858-859でリロード処理を確認 |

**主要処理フロー**:
- **行849**: `zsh -n`で.zshrcの構文チェック
- **行850-852**: エラー時は.zshrc.bckから復元
- **行859**: `[[ ! -o interactive ]]`でインタラクティブセッションを判定し、リロード実行

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

```
omz theme set <theme>
    │
    └─ _omz::theme::set
           │
           ├─ 引数チェック
           │
           ├─ テーマファイル存在確認
           │      ├─ $ZSH_CUSTOM/$1.zsh-theme
           │      ├─ $ZSH_CUSTOM/themes/$1.zsh-theme
           │      └─ $ZSH/themes/$1.zsh-theme
           │
           ├─ [未発見] → エラー終了
           │
           ├─ AWKスクリプト生成
           │      ├─ ZSH_THEME=行の検出
           │      └─ 新しい値に置換
           │
           ├─ .zshrc更新
           │      ├─ awk実行 → .zshrc.new作成
           │      ├─ [ZSH_THEME行なし] → 先頭に追加
           │      ├─ cp -f → .zshrc.bck作成
           │      └─ mv -f → .zshrc置換
           │
           ├─ 構文チェック
           │      └─ zsh -n ~/.zshrc
           │
           ├─ [エラー時] ロールバック
           │      └─ mv -f .zshrc.bck → .zshrc
           │
           └─ [成功時] リロード
                  └─ _omz::reload
```

### データフロー図

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

テーマ名 ───▶ _omz::theme::set
                    │
                    ▼
              テーマ存在確認
                    │
         ┌──────────┴──────────┐
         │                     │
     [発見]                [未発見]
         │                     │
         ▼                     ▼
   AWKスクリプト生成      エラー出力
         │
         ▼
   ~/.zshrc ───▶ awk ───▶ ~/.zshrc.new
         │                     │
         │              [ZSH_THEME行なし]
         │                     │
         │                     ▼
         │              先頭にZSH_THEME追加
         │                     │
         └──────────┬──────────┘
                    │
                    ▼
         ~/.zshrc ───▶ cp ───▶ ~/.zshrc.bck
                    │
                    ▼
         ~/.zshrc.new ───▶ mv ───▶ ~/.zshrc
                    │
                    ▼
                 zsh -n ───▶ 構文チェック
                    │
           ┌────────┴────────┐
           │                 │
       [成功]            [失敗]
           │                 │
           ▼                 ▼
      成功メッセージ    ロールバック
           │                 │
           ▼                 ▼
     _omz::reload      エラーメッセージ
           │
           ▼
       exec zsh
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz theme setコマンドの実装 |
| .zshrc | `~/.zshrc` または `$ZDOTDIR/.zshrc` | 設定 | ZSH_THEME変数の更新対象 |
| .zshrc.bck | `~/.zshrc.bck` または `$ZDOTDIR/.zshrc.bck` | バックアップ | 元の.zshrcのバックアップ |
| *.zsh-theme | `themes/` | テーマ | ビルトインテーマファイル |
| *.zsh-theme | `$ZSH_CUSTOM/` | テーマ | カスタムテーマファイル |
