# 機能設計書 40-omz_history

## 概要

本ドキュメントは、Oh My Zshの`omz_history`関数の機能設計について記載する。この関数は、標準の`history`コマンドのラッパーとして機能し、履歴削除の確認機能やタイムスタンプ表示オプションを提供する。

### 本機能の処理概要

**業務上の目的・背景**：コマンド履歴の管理は開発者の生産性に直接影響する。過去に実行したコマンドを検索・再利用できることで、作業効率が向上する。また、誤って履歴を削除することを防ぐための確認機能や、タイムスタンプによる履歴の時系列管理も重要である。

**機能の利用シーン**：ユーザーが`history`コマンドを実行した際に、この関数がエイリアス経由で呼び出される。履歴の表示、削除、タイムスタンプ付き表示などの操作で使用される。

**主要な処理内容**：
1. コマンドライン引数のパース（-c、-l、-f、-E、-i、-t）
2. -cオプションの場合、履歴削除の確認プロンプトを表示
3. 確認後、HISTFILEを空にしてfcをリセット
4. 引数なしの場合、履歴全体を表示
5. 引数ありの場合、fcコマンドに引数を渡して実行

**関連システム・外部連携**：ZSHの組み込みコマンド`fc`および`$HISTFILE`変数と連携する。

**権限による制御**：特になし。ただし、HISTFILEへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ターミナル | 結果表示画面 | historyコマンドの実行結果を表示 |

## 機能種別

ユーティリティ・履歴管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| -c | flag | No | 履歴を削除（確認プロンプト付き） | - |
| -l | flag | No | 履歴をリスト表示（デフォルト動作） | - |
| -f | flag | No | タイムスタンプをmm/dd/yyyy形式で表示 | - |
| -E | flag | No | タイムスタンプをdd.mm.yyyy形式で表示 | - |
| -i | flag | No | タイムスタンプをyyyy-mm-dd形式で表示 | - |
| -t format | string | No | カスタムタイムスタンプ形式 | - |
| その他の引数 | string | No | 履歴範囲の指定（fcに渡される） | - |

### 入力データソース

- **環境変数**: HIST_STAMPS - デフォルトのタイムスタンプ形式
- **ファイル**: $HISTFILE - 履歴ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 履歴リスト | text | コマンド履歴（オプションに応じてタイムスタンプ付き） |
| 確認プロンプト | text | 履歴削除時の確認メッセージ |
| 削除完了メッセージ | text | 「History file deleted.」 |

### 出力先

- 標準出力（履歴リスト）
- 標準エラー出力（確認プロンプト、削除完了メッセージ）

## 処理フロー

### 処理シーケンス

```
1. 引数パース（zparseopts）
   └─ -c、-l、-f、-E、-i、-tオプションを抽出
2. -cオプションの処理
   2.1 確認プロンプト表示
   2.2 ユーザー入力待ち
   2.3 y/Yの場合のみ履歴削除
       └─ HISTFILEを空にする
       └─ fc -pでリセット
   2.4 削除完了メッセージ表示
3. 引数なしの場合
   └─ fc -l 1 で全履歴表示
4. 引数ありの場合
   └─ fc -l "$@" で指定範囲を表示
```

### フローチャート

```mermaid
flowchart TD
    A[history呼び出し] --> B[引数パース]
    B --> C{-cオプション?}
    C -->|Yes| D[確認プロンプト表示]
    D --> E{y/Y入力?}
    E -->|Yes| F[HISTFILE削除]
    F --> G[fc -pでリセット]
    G --> H[削除完了メッセージ]
    E -->|No| I[終了]
    H --> I
    C -->|No| J{引数なし?}
    J -->|Yes| K[fc -l 1で全履歴表示]
    J -->|No| L[fc -l "$@"で範囲表示]
    K --> I
    L --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-40-1 | 削除確認 | 履歴削除前に確認プロンプトを表示する | -cオプション指定時 |
| BR-40-2 | タイムスタンプエイリアス | HIST_STAMPSに応じて適切なオプションをデフォルトで使用 | historyエイリアス設定時 |
| BR-40-3 | 全履歴表示 | 引数なしの場合は履歴番号1から全て表示 | 引数なし時 |
| BR-40-4 | 不可逆操作警告 | 削除が不可逆であることをユーザーに警告 | -cオプション指定時 |

### 計算ロジック

HIST_STAMPSによるエイリアス設定:
```zsh
case ${HIST_STAMPS-} in
  "mm/dd/yyyy") alias history='omz_history -f' ;;
  "dd.mm.yyyy") alias history='omz_history -E' ;;
  "yyyy-mm-dd") alias history='omz_history -i' ;;
  "") alias history='omz_history' ;;
  *) alias history="omz_history -t '$HIST_STAMPS'" ;;
esac
```

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

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

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴削除 | $HISTFILE | 上書き（空） | -cオプションで履歴ファイルを空にする |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ユーザーキャンセル | 削除確認でn/Nを入力 | 何もせず終了 |

### リトライ仕様

リトライは実装されていない

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

該当なし

## パフォーマンス要件

- 大量の履歴がある場合でも、fcコマンドの性能に依存
- 通常は即座に結果を表示

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

- 履歴削除は確認プロンプト付きで誤操作を防止
- 履歴にはパスワードなどの機密情報が含まれる可能性があるため、適切な管理が必要

## 備考

- lib/history.zshには履歴設定（HISTSIZE、SAVEHIST、オプション）も含まれる
- share_historyオプションにより、複数のシェル間で履歴を共有

---

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

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

### 推奨読解順序

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

履歴システムで使用される環境変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | history.zsh | `lib/history.zsh` | 履歴関連の環境変数を確認 |

**読解のコツ**:
- `$HISTFILE`: 履歴ファイルのパス
- `$HISTSIZE`: メモリ内の履歴サイズ
- `$SAVEHIST`: ファイルに保存する履歴サイズ
- `HIST_STAMPS`: タイムスタンプ形式

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | history.zsh | `lib/history.zsh` | `omz_history`関数の定義（2-26行目） |

**主要処理フロー**:
1. **1行目**: コメント「## History wrapper」
2. **2行目**: 関数定義開始
3. **4行目**: ローカル変数宣言
4. **5行目**: `zparseopts -E -D c=clear l=list f=stamp E=stamp i=stamp t:=stamp` - 引数パース
5. **7-18行目**: -cオプションの処理（確認プロンプト、削除）
6. **19-21行目**: 引数なしの場合の処理
7. **22-25行目**: 引数ありの場合の処理

#### Step 3: エイリアス設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | history.zsh | `lib/history.zsh` | エイリアス設定（29-35行目） |

**主要処理フロー**:
- **29行目**: `case ${HIST_STAMPS-} in` - HIST_STAMPSによる分岐開始
- **30行目**: mm/dd/yyyy -> -fオプション
- **31行目**: dd.mm.yyyy -> -Eオプション
- **32行目**: yyyy-mm-dd -> -iオプション
- **33行目**: 空 -> オプションなし
- **34行目**: カスタム -> -tオプション

#### Step 4: 履歴設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | history.zsh | `lib/history.zsh` | 履歴設定（38-48行目） |

**主要処理フロー**:
- **38行目**: HISTFILEのデフォルト設定
- **39行目**: HISTSIZEの最小値設定
- **40行目**: SAVEHISTの最小値設定
- **43-48行目**: 各種履歴オプション設定

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

```
history (エイリアス)
    │
    └─ omz_history [オプション] [引数]
           │
           ├─ zparseopts (引数パース)
           │
           ├─ -cオプション時:
           │      ├─ print -nu2 (確認プロンプト)
           │      ├─ builtin read -E (入力待ち)
           │      ├─ print -nu2 >| "$HISTFILE" (ファイル削除)
           │      ├─ fc -p "$HISTFILE" (リセット)
           │      └─ print -u2 (完了メッセージ)
           │
           └─ 通常時:
                  └─ builtin fc "${stamp[@]}" -l [1|"$@"]
```

### データフロー図

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

historyコマンド ──▶ omz_history
      │                  │
      ▼                  ▼
オプション解析 ──▶ zparseopts
      │                  │
      ├─ -c ────────────▶ 確認プロンプト ──▶ HISTFILE削除
      │                                         │
      │                                         ▼
      │                                    fc -p (リセット)
      │
      └─ その他 ───────▶ builtin fc -l ──────▶ 履歴リスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| history.zsh | `lib/history.zsh` | ソース | omz_history関数と履歴設定の定義元 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/history.zshを読み込むメインスクリプト |
| .zsh_history | `$HOME/.zsh_history` | データ | デフォルトの履歴ファイル |
