# 機能設計書 59-clipcopy

## 概要

本ドキュメントは、Oh My Zshの`clipcopy`関数の機能設計を記載する。この関数は、クロスプラットフォーム対応でデータをシステムクリップボードにコピーするユーティリティ関数である。

### 本機能の処理概要

`clipcopy`関数は、標準入力またはファイルからデータを読み取り、実行環境に応じた適切なクリップボードコマンドを使用してシステムクリップボードにコピーする。macOS、Linux（X11/Wayland）、Windows（Cygwin/WSL/MSYS）、SSH経由など、様々な環境に対応している。

**業務上の目的・背景**：開発作業において、コマンドの出力結果やファイルの内容をクリップボードにコピーしたい場面は頻繁にある。各プラットフォームではクリップボードへのアクセス方法が異なるため、統一的なインターフェースを提供することで、環境を意識せずにクリップボード操作を行えるようにする。これにより、シェルスクリプトの可搬性も向上する。

**機能の利用シーン**：
- コマンドの出力結果をクリップボードにコピーしてドキュメントに貼り付ける場合
- ファイルの内容をクリップボードにコピーする場合
- パイプラインの最後でデータをクリップボードに送る場合
- SSH接続先のサーバーからローカルのクリップボードにデータを送る場合

**主要な処理内容**：
1. detect-clipboard関数でプラットフォームを検出
2. 検出されたプラットフォームに応じてclipcopy関数を再定義
3. 標準入力またはファイルからデータを読み取り
4. プラットフォーム固有のコマンドでクリップボードにコピー

**関連システム・外部連携**：
- macOS: pbcopy
- Linux X11: xsel, xclip
- Linux Wayland: wl-copy
- Windows: clip.exe, /dev/clipboard
- SSH: lemonade, doitclient
- tmux: tmux load-buffer

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

## 関連画面

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

## 機能種別

クリップボード操作 / プラットフォーム抽象化 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $1 (file) | string | No | コピーするファイルのパス。省略時は標準入力を使用 | なし |

### 入力データソース

- コマンドライン引数（ファイルパス）
- 標準入力（パイプライン使用時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | なし | 出力なし |
| クリップボード | バイナリ/テキスト | コピーされたデータ |
| 戻り値 | integer | 0: 成功、1: エラー（プラットフォーム非対応等） |

### 出力先

- システムクリップボード
- 標準エラー出力（エラーメッセージ）

## 処理フロー

### 処理シーケンス

```
1. 初回呼び出し時の処理
   └─ clipcopy/clippaste関数を未定義化
   └─ detect-clipboard関数を呼び出し
2. プラットフォーム検出（detect-clipboard）
   └─ 環境変数とコマンド存在チェックで判定
3. 関数再定義
   └─ 検出されたプラットフォームに応じたclipcopy関数を定義
4. データコピー
   └─ 引数またはstdinからデータを取得
   └─ プラットフォーム固有のコマンドでクリップボードにコピー
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{初回呼び出し?}
    B -->|Yes| C[clipcopy/clippaste を未定義化]
    C --> D[detect-clipboard 呼び出し]
    B -->|No| E[clipcopy 実行]
    D --> F{プラットフォーム検出}
    F -->|macOS| G[pbcopy使用]
    F -->|Linux X11| H[xsel/xclip使用]
    F -->|Linux Wayland| I[wl-copy使用]
    F -->|Windows| J[clip.exe/dev/clipboard使用]
    F -->|SSH| K[lemonade/doitclient使用]
    F -->|tmux| L[tmux load-buffer使用]
    F -->|不明| M[リトライ or エラー]
    G --> N[clipcopy再定義]
    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    N --> E
    E --> O{引数あり?}
    O -->|Yes| P[ファイルを読み込み]
    O -->|No| Q[stdinを読み込み]
    P --> R[クリップボードにコピー]
    Q --> R
    R --> S[終了]
    M --> T[エラー出力]
    T --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-1 | 遅延初期化 | 初回呼び出し時にプラットフォーム検出を行う | 初回呼び出し時 |
| BR-59-2 | プラットフォーム優先順位 | macOS > Cygwin/MSYS > WSL > Wayland > X11の順で検出 | 常時 |
| BR-59-3 | stdin/ファイル自動判定 | 引数がある場合はファイル、ない場合はstdinを使用 | 常時 |
| BR-59-4 | リトライ機能 | 検出失敗時、次回呼び出しで再検出を試みる | 初回検出失敗時 |

### 計算ロジック

プラットフォーム検出の優先順位：
```zsh
# 検出順序（detect-clipboard関数内）
1. macOS (darwin) + pbcopy/pbpaste
2. Cygwin/MSYS (/dev/clipboard)
3. WSL (clip.exe + powershell.exe)
4. Wayland (WAYLAND_DISPLAY + wl-copy/wl-paste)
5. X11 xsel (DISPLAY + xsel)
6. X11 xclip (DISPLAY + xclip)
7. SSH lemonade (lemonade)
8. SSH doitclient (doitclient)
9. win32yank (win32yank)
10. Termux (termux-clipboard-set)
11. tmux (TMUX + tmux)
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | プラットフォーム非対応 | クリップボードコマンドが見つからない | xclip/xselのインストール、または環境変数の設定 |
| - | ファイル読み込みエラー | 指定されたファイルが存在しない | ファイルパスを確認 |

### リトライ仕様

初回検出失敗時、次回呼び出しで再度detect-clipboardを実行する。

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

該当なし。

## パフォーマンス要件

データサイズに比例した線形時間。大量のデータのコピーはクリップボードの制限に依存する。

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

- クリップボードの内容は他のアプリケーションからアクセス可能
- 機密情報（パスワード等）をクリップボードにコピーする場合は注意が必要
- SSH経由のクリップボード操作（lemonade/doitclient）はネットワーク経由でデータが送信される

## 備考

- clippaste関数とペアで使用される
- detect-clipboard関数で実際の関数実装が動的に定義される
- Wayland環境ではwl-copyがバックグラウンドで実行される（&|）

---

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

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

### 推奨読解順序

#### Step 1: ファイル全体の構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | clipboard.zsh | `lib/clipboard.zsh` | ファイル全体の構成（1-108行目） |

**読解のコツ**: このファイルは以下の構造になっている：
1. コメント/ドキュメント（1-50行目）
2. detect-clipboard関数（51-101行目）
3. 初期化用のスタブ関数（103-107行目）

#### Step 2: 使用方法のドキュメントを読む

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

**ドキュメントコメントの内容**:
- clipcopyの使用方法（stdin、ファイル指定）
- clipppasteの使用方法（stdout、パイプ、リダイレクト）
- サポートされているプラットフォーム

#### Step 3: プラットフォーム検出ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | clipboard.zsh | `lib/clipboard.zsh` | detect-clipboard関数（51-101行目） |

**主要処理フロー**:
- **54-56行目**: macOS（darwin）の検出とpbcopy/pbpaste使用
- **57-59行目**: Cygwin/MSYSの検出と/dev/clipboard使用
- **60-62行目**: WSL（clip.exe）の検出
- **63-65行目**: Wayland（wl-copy）の検出
- **66-68行目**: X11 xselの検出
- **69-71行目**: X11 xclipの検出
- **72-74行目**: SSH lemonadeの検出
- **75-77行目**: SSH doitclientの検出
- **78-80行目**: win32yankの検出
- **81-83行目**: Termuxの検出
- **84-86行目**: tmuxの検出
- **87-99行目**: 検出失敗時のリトライ処理

#### Step 4: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | clipboard.zsh | `lib/clipboard.zsh` | スタブ関数（103-107行目） |

**主要処理フロー**:
- **103行目**: `function clipcopy clippaste {` - 両関数を同時定義
- **104行目**: `unfunction clipcopy clippaste` - 自身を未定義化
- **105行目**: `detect-clipboard || true` - 検出を実行（失敗しても継続）
- **106行目**: `"$0" "$@"` - 再定義された関数を呼び出し

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

```
clipcopy() [初回呼び出し]
    │
    ├─ unfunction clipcopy clippaste
    │
    ├─ detect-clipboard()
    │       │
    │       ├─ [macOS] → clipcopy() { pbcopy }
    │       ├─ [Cygwin] → clipcopy() { > /dev/clipboard }
    │       ├─ [WSL] → clipcopy() { clip.exe }
    │       ├─ [Wayland] → clipcopy() { wl-copy }
    │       ├─ [X11] → clipcopy() { xsel/xclip }
    │       ├─ [SSH] → clipcopy() { lemonade/doitclient }
    │       ├─ [tmux] → clipcopy() { tmux load-buffer }
    │       └─ [不明] → _retry_clipboard_detection_or_fail
    │
    └─ "$0" "$@" [再定義されたclipcopyを呼び出し]
            │
            └─ プラットフォーム固有のコマンド実行
```

### データフロー図

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

stdin ────────────▶ cat ─────────────▶ プラットフォーム固有
      または                          │   コマンド
ファイル ─────────▶ cat "$1" ────────▶   │
                                        │
                                        ▼
                              システムクリップボード
```

### 関連ファイル一覧

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