# 機能設計書 53-alias_value

## 概要

本ドキュメントは、Oh My Zshの`alias_value`関数の機能設計を記載する。この関数は、指定されたエイリアスの値を取得するユーティリティ関数である。

### 本機能の処理概要

`alias_value`関数は、zshのエイリアス配列からエイリアス名に対応する値を取得し、標準出力に出力する。エイリアスが存在しない場合は何も出力せず、戻り値で存在の有無を示す。

**業務上の目的・背景**：シェルスクリプトやプラグイン開発において、既存のエイリアスの値を動的に取得する必要がある場合がある。例えば、エイリアスの存在チェックや、エイリアスの値を利用した処理の分岐などに活用される。この関数は、zshの内部配列に直接アクセスする方法をカプセル化し、使いやすいインターフェースを提供する。

**機能の利用シーン**：
- プラグインやスクリプトでエイリアスの値を動的に取得する場合
- エイリアスの存在確認を行う場合
- エイリアスの値に基づいて処理を分岐する場合
- デバッグやトラブルシューティングでエイリアスの定義を確認する場合

**主要な処理内容**：
1. zshの$aliases連想配列に指定されたキーが存在するかチェック
2. 存在する場合、その値を標準出力に出力
3. 戻り値でエイリアスの存在を示す（0: 存在、1: 不存在）

**関連システム・外部連携**：zshの内部$aliases連想配列に依存。

**権限による制御**：特にロールによる制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 内部ユーティリティ関数のため関連画面なし |

## 機能種別

データ取得 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $1 (alias) | string | Yes | 値を取得したいエイリアス名 | なし |

### 入力データソース

コマンドライン引数として直接入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | string | エイリアスの値（存在する場合） |
| 戻り値 | integer | 0: エイリアスが存在、1: エイリアスが存在しない |

### 出力先

- 標準出力（エイリアスの値）
- 戻り値（存在の有無）

## 処理フロー

### 処理シーケンス

```
1. エイリアス存在チェック
   └─ (( $+aliases[$1] )) でエイリアスの存在を確認
2. 値の出力（存在する場合）
   └─ echo $aliases[$1] で値を出力
3. 戻り値の設定
   └─ 存在する場合: 0、存在しない場合: 1
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{エイリアスが存在?}
    B -->|Yes| C[エイリアスの値を出力]
    C --> D[戻り値 0 を返す]
    B -->|No| E[何も出力しない]
    E --> F[戻り値 1 を返す]
    D --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-1 | 存在チェック | $+aliases構文でエイリアスの存在を確認する | 常時 |
| BR-53-2 | 出力条件 | エイリアスが存在する場合のみ値を出力する | 常時 |
| BR-53-3 | 戻り値規約 | 存在時は0、不存在時は1を返す | 常時 |

### 計算ロジック

エイリアス存在チェックと値取得：
```zsh
(( $+aliases[$1] )) && echo $aliases[$1]
```
- `$+aliases[$1]`：$aliases配列にキー$1が存在する場合1、そうでない場合0
- `(( ... ))`：算術式として評価、0の場合false、非0の場合true
- `&&`：前の条件がtrueの場合のみ後続を実行

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | エイリアス不存在 | 指定されたエイリアスが定義されていない | 戻り値1が返される、呼び出し側で対応 |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

連想配列への直接アクセスのため、非常に高速（O(1)）。

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

特になし。エイリアスはユーザーのシェル環境内で定義されたものであり、セキュリティリスクは低い。

## 備考

- try_alias_value関数から呼び出されることがある
- zsh固有の$aliases連想配列を使用しているため、bash等の他のシェルでは動作しない

---

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

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

### 推奨読解順序

#### Step 1: 関数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | functions.zsh | `lib/functions.zsh` | alias_value関数の定義（101-103行目） |

**読解のコツ**: zshの`$+parameter`構文（パラメータが設定されていれば1、そうでなければ0を返す）と、`$aliases`連想配列を理解することがポイント。

#### Step 2: 関連コメントを読む

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | functions.zsh | `lib/functions.zsh` | 関数上部のコメント（90-100行目） |

**ドキュメントコメントの内容**:
- **Arguments**：引数の説明（1. alias - 値を取得するエイリアス名）
- **STDOUT**：標準出力の説明（エイリアスの値）
- **Return value**：戻り値の説明（0: 存在、1: 不存在）

#### Step 3: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | functions.zsh | `lib/functions.zsh` | try_alias_value関数（116-118行目） |

**主要処理フロー**:
- **117行目**: `alias_value "$1" || echo "$1"` - alias_valueの戻り値に基づく分岐

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

```
try_alias_value()
    │
    └─ alias_value()
           │
           └─ $aliases[$1] (zsh内部配列アクセス)
```

### データフロー図

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

エイリアス名 ─────▶ $+aliases[$1] ─────▶ 存在チェック結果
                       │
                       ▼
               [存在する場合]
                       │
                       ▼
              $aliases[$1] ─────────▶ 標準出力（エイリアス値）
                       │
                       ▼
                  戻り値 0/1 ─────────▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| functions.zsh | `lib/functions.zsh` | ソース | alias_value関数およびtry_alias_value関数の定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/functions.zshを読み込むエントリポイント |
