# 機能設計書 44-down-line-or-beginning-search

## 概要

本ドキュメントは、Oh My Zshのdown-line-or-beginning-search機能について、その設計と実装の詳細を記載したものである。この機能は、コマンドライン入力中に下矢印キーを押すと、現在入力中の文字列から始まるコマンド履歴を下方向（新しい方向）に検索する。

### 本機能の処理概要

この機能は、ZSHのZLE（Zsh Line Editor）ウィジェットとして実装され、インクリメンタルな履歴検索を提供する。ユーザーがコマンドの一部を入力した状態で下矢印キーを押すと、その入力内容をプレフィックスとして持つ新しい方向のコマンドを検索し、一致するものを表示する。

**業務上の目的・背景**：up-line-or-beginning-search（機能No.43）で過去の履歴を検索した後、再度新しい方向に戻りたい場合がある。本機能により、同じプレフィックス検索のロジックで新しい方向への検索が可能になり、履歴検索のナビゲーションが完結する。

**機能の利用シーン**：
- up-line-or-beginning-searchで過去方向に検索しすぎた場合の戻り操作
- 特定のプレフィックスを持つ履歴の中で、より新しいコマンドを選択したい場面
- 履歴検索中に前後の候補を行き来したい場面

**主要な処理内容**：
1. 現在のコマンドラインバッファの内容を取得
2. 入力文字列をプレフィックスとして履歴を検索
3. 一致する履歴エントリを表示（下方向に検索）
4. マッチがない場合は何もしない
5. 空入力の場合は通常のdown-line-or-historyと同様に動作

**関連システム・外部連携**：
- ZSHビルトインのZLE（Zsh Line Editor）機能を使用
- コマンド履歴（HISTFILE）を参照

**権限による制御**：特になし。全ユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はZLEウィジェットとして動作し、画面を持たない |

## 機能種別

履歴検索処理 / ZLEウィジェット / インクリメンタル検索

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| BUFFER | ZLE変数 | Yes | 現在のコマンドラインバッファ | なし |
| CURSOR | ZLE変数 | Yes | カーソル位置 | なし |
| HISTNO | ZLE変数 | Yes | 現在の履歴位置 | なし |

### 入力データソース

- ZLEのコマンドラインバッファ
- ZSHのコマンド履歴

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BUFFER | ZLE変数 | 検索でマッチした履歴コマンド |
| CURSOR | ZLE変数 | 更新されたカーソル位置 |
| HISTNO | ZLE変数 | 更新された履歴位置 |

### 出力先

- ZLEコマンドラインバッファ（画面上のコマンドライン）

## 処理フロー

### 処理シーケンス

```
1. キー入力の検出
   └─ 下矢印キーまたは^[[Bの入力を検出

2. 現在のバッファ内容を取得
   └─ $BUFFERから入力中の文字列を取得

3. 履歴検索の実行
   └─ 入力文字列をプレフィックスとして新しい方向に検索

4. 結果の表示
   └─ マッチした場合はバッファを更新して表示

5. カーソル位置の調整
   └─ 行末にカーソルを移動
```

### フローチャート

```mermaid
flowchart TD
    A[下矢印キー押下] --> B{バッファに入力あり?}
    B -->|Yes| C[入力文字列でプレフィックス検索]
    B -->|No| D[通常の履歴ナビゲーション]
    C --> E{マッチあり?}
    E -->|Yes| F[バッファを更新]
    E -->|No| G[何もしない]
    D --> F
    F --> H[カーソル位置調整]
    G --> I[終了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-1 | プレフィックスマッチ | 入力文字列で始まる履歴のみを検索対象とする | バッファに入力がある場合 |
| BR-44-2 | 下方向検索 | 履歴の古い方から新しい方へ検索する | 常時 |
| BR-44-3 | 空入力時動作 | 入力がない場合は通常の履歴ナビゲーション | バッファが空の場合 |
| BR-44-4 | 連続検索 | 繰り返し押下で次のマッチに移動 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベースを使用しない |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | マッチなし | プレフィックスに一致する履歴がない | 無音で処理終了（エラーなし） |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- キー入力に対して即座に応答（遅延なし）
- 履歴サイズに関わらず高速な検索

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

- 履歴に保存されているコマンドのみが検索対象
- hist_ignore_spaceで除外されたコマンドは検索対象外

## 備考

- ZSHビルトインの関数であり、autoloadで遅延読み込みされる
- up-line-or-beginning-search（機能No.43）と対になる機能

---

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

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

### 推奨読解順序

#### Step 1: キーバインド設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | key-bindings.zsh | `lib/key-bindings.zsh` | 47-58行目の下矢印キー設定 |

**主要処理フロー**:
1. **48行目**: `autoload -U down-line-or-beginning-search` - ZSHビルトイン関数の遅延読み込み
2. **49行目**: `zle -N down-line-or-beginning-search` - ZLEウィジェットとして登録
3. **51-53行目**: `bindkey -M emacs/viins/vicmd "^[[B" down-line-or-beginning-search` - ANSIエスケープシーケンスでバインド
4. **54-58行目**: terminfoを使用したバインド（ターミナル互換性のため）

**読解のコツ**:
- `^[[B`はANSIの下矢印キーシーケンス。
- terminfoのkcud1は下矢印キーを表す。
- up-line-or-beginning-searchと同様の設定パターン。

#### Step 2: 関数の動作原理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ZSH内部 | ZSHビルトイン | down-line-or-beginning-searchはZSHビルトインウィジェット |

**読解のコツ**:
- down-line-or-beginning-searchはZSH 4.3.10以降で利用可能なビルトインウィジェット
- 動作は以下の通り：
  1. バッファが空の場合：down-line-or-historyと同じ動作
  2. バッファに入力がある場合：その文字列で始まる履歴を新しい方向に検索

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

```
lib/key-bindings.zsh
    │
    ├─ autoload -U down-line-or-beginning-search
    │      └─ ZSH/share/zsh/functions/Zle/down-line-or-beginning-search
    │
    └─ zle -N down-line-or-beginning-search
           │
           └─ ZLEウィジェット登録
                  │
                  └─ bindkey で下矢印キーにバインド
                         │
                         ├─ "^[[B" (ANSIシーケンス)
                         │
                         └─ ${terminfo[kcud1]} (terminfo)
```

### データフロー図

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

下矢印キー押下              down-line-or-beginning-search  コマンドライン更新
     │                            │                            │
     ▼                            ▼                            ▼
BUFFER（入力文字列）───▶  履歴プレフィックス検索 ───▶  BUFFER（マッチした履歴）
                                  │
                                  ▼
                           HISTNOの更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| key-bindings.zsh | `lib/key-bindings.zsh` | ソース | キーバインド設定とautoload |
| down-line-or-beginning-search | ZSHビルトイン | ZSH関数 | 実際の検索処理を実行 |
