# 機能設計書 71-d関数

## 概要

本ドキュメントは、Oh My Zshのディレクトリ管理ライブラリ（lib/directories.zsh）で提供される`d`関数の機能設計について記述する。

### 本機能の処理概要

`d`関数は、Zshのディレクトリスタック（pushd/popdで管理されるディレクトリ履歴）を簡単に表示・操作するためのユーティリティ関数である。引数なしで実行すると上位10件のディレクトリスタックを番号付きで表示し、引数を指定するとzsh組み込みの`dirs`コマンドに引数を渡して実行する。

**業務上の目的・背景**：ディレクトリ間を頻繁に移動する作業において、移動履歴を確認したり、以前訪れたディレクトリに素早く戻る必要がある。標準の`dirs`コマンドは出力が見づらいため、番号付きの見やすい形式で表示する機能が必要とされる。

**機能の利用シーン**：
- 複数のプロジェクトディレクトリ間を移動しながら作業している場合
- 深いディレクトリ階層を移動した後、以前のディレクトリに戻りたい場合
- `cd -1`、`cd -2`などのエイリアスと組み合わせて、スタック内のディレクトリを確認する場合

**主要な処理内容**：
1. 引数の有無をチェック（-n $1）
2. 引数がある場合は`dirs`コマンドにそのまま引数を渡して実行
3. 引数がない場合は`dirs -v`（番号付き表示）を実行し、`head -n 10`で上位10件に制限
4. compdefで`_dirs`補完関数を`d`コマンドに関連付け

**関連システム・外部連携**：本機能はZshの組み込み`dirs`コマンドおよび`auto_pushd`オプションと連携して動作する。`auto_pushd`が有効な場合、`cd`コマンドでディレクトリ変更するたびにスタックにプッシュされる。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | ターミナル | 主画面 | ディレクトリスタックの表示 |

## 機能種別

参照処理（ディレクトリスタックの表示）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $@ | string | No | dirsコマンドに渡すオプション・引数 | dirsコマンドの仕様に準拠 |

### 入力データソース

- Zshディレクトリスタック（$dirstack配列、内部的にはPWD履歴）
- コマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ディレクトリ一覧 | string | 番号付きディレクトリパス一覧（最大10件） |

### 出力先

- 標準出力（ターミナル）

## 処理フロー

### 処理シーケンス

```
1. 引数の有無を確認
   └─ [[ -n $1 ]] で第1引数が空でないかチェック
2. 引数がある場合
   └─ dirs "$@" を実行（引数をそのまま渡す）
3. 引数がない場合
   └─ dirs -v | head -n 10 を実行（番号付き表示、上位10件）
```

### フローチャート

```mermaid
flowchart TD
    A[d関数呼び出し] --> B{引数あり?}
    B -->|Yes| C["dirs $@ を実行"]
    B -->|No| D["dirs -v | head -n 10 を実行"]
    C --> E[結果を標準出力]
    D --> E
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-01 | デフォルト表示件数 | 引数なしの場合は上位10件を表示 | 引数が指定されていない場合 |
| BR-71-02 | 番号付き表示 | -vオプションにより番号付きで表示 | 引数が指定されていない場合 |
| BR-71-03 | 引数透過 | 引数がある場合はdirsコマンドにそのまま渡す | 引数が指定されている場合 |

### 計算ロジック

特になし（表示のみ）

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | dirsエラー | 無効なオプションを指定した場合 | dirsコマンドのエラーメッセージが表示される |

### リトライ仕様

リトライは不要（即時完了する処理）

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

トランザクション管理なし

## パフォーマンス要件

即時完了（ミリ秒単位）

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

- 表示されるディレクトリパスにはユーザーのホームディレクトリなどの情報が含まれる可能性がある
- 特にセキュリティ上の脆弱性はない

## 備考

- `d`関数は`lib/directories.zsh`で定義されるディレクトリエイリアス群（`cd -1`〜`cd -9`、`...`、`....`など）と組み合わせて使用されることを想定している
- `compdef _dirs d`により、`d`コマンドでも`dirs`コマンドと同じ補完機能が利用可能

---

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

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

### 推奨読解順序

#### Step 1: ディレクトリスタック設定を理解する

まず、ディレクトリスタックの動作を制御するオプション設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | directories.zsh | `lib/directories.zsh` | setoptでのディレクトリスタック設定（1-5行目） |

**読解のコツ**: Zshの`setopt`コマンドでシェルオプションを有効化している。`auto_pushd`によりcdコマンドが自動的にディレクトリをスタックにプッシュするようになる。

**主要処理フロー**:
1. **2行目**: `setopt auto_cd` - ディレクトリ名だけでcdを実行可能にする
2. **3行目**: `setopt auto_pushd` - cdコマンドで自動的にディレクトリスタックにプッシュ
3. **4行目**: `setopt pushd_ignore_dups` - 重複するディレクトリをスタックに追加しない
4. **5行目**: `setopt pushdminus` - `cd -N`の挙動を反転（直感的な番号指定）

#### Step 2: d関数の実装を理解する

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

**主要処理フロー**:
- **27行目**: `function d ()` - d関数の定義開始
- **28行目**: `if [[ -n $1 ]]; then` - 第1引数が空でないかチェック
- **29行目**: `dirs "$@"` - 引数がある場合、dirsコマンドに引数を渡す
- **31行目**: `dirs -v | head -n 10` - 引数がない場合、番号付き表示で上位10件
- **34行目**: `compdef _dirs d` - 補完関数の関連付け

#### Step 3: 関連エイリアスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | directories.zsh | `lib/directories.zsh` | ディレクトリ移動エイリアス（13-25行目） |

**主要処理フロー**:
- **13行目**: `alias -- -='cd -'` - 直前のディレクトリに戻る
- **14-22行目**: `alias 1='cd -1'`〜`alias 9='cd -9'` - スタック内のN番目のディレクトリに移動

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

```
d関数 (lib/directories.zsh:27-33)
    │
    ├─ [引数あり] dirs $@ (zsh builtin)
    │
    └─ [引数なし] dirs -v (zsh builtin)
           └─ head -n 10 (外部コマンド)
```

### データフロー図

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

コマンドライン引数 ───▶ d関数
                         │
                         ├─[引数あり]──▶ dirs $@ ───▶ 標準出力
                         │
                         └─[引数なし]──▶ dirs -v ───▶ head -n 10 ───▶ 標準出力
                                            │
Zshディレクトリスタック ────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| directories.zsh | `lib/directories.zsh` | ソース | d関数およびディレクトリ関連エイリアス・オプションの定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/directories.zshを読み込むメインスクリプト |
