# 機能設計書 60-クリップボード

## 概要

本ドキュメントは、Nushellにおけるクリップボード操作機能の設計仕様を記載する。この機能は、clip copy、clip pasteコマンドを通じてシステムクリップボードへのコピー・ペースト操作を提供する。

### 本機能の処理概要

クリップボード機能は、Nushellのデータをシステムクリップボードにコピーし、クリップボードからデータを取得する。構造化データはテーブル形式の文字列に変換される。

**業務上の目的・背景**：シェル操作の結果を他のアプリケーションと共有したり、外部からのデータをNushellに取り込む際、クリップボードは最も一般的なデータ共有手段である。ANSIエスケープシーケンスを含まないプレーンテキスト出力により、どのアプリケーションでも利用可能。

**機能の利用シーン**：
- コマンド出力結果をドキュメントにペースト
- 他のアプリケーションからのテキストをNushellで処理
- JSONデータのコピー・ペースト
- 構造化データの共有

**主要な処理内容**：
1. clip copyでNushellの値をクリップボードにコピー
2. clip pasteでクリップボードからテキストを取得
3. JSON形式のクリップボード内容の自動パース

**関連システム・外部連携**：
- システムクリップボード（OS依存）
- 外部クリップボードプロバイダー（設定可能）

**権限による制御**：一部の環境でクリップボードアクセスに制限あり

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用コマンド |

## 機能種別

データ共有 / クリップボード操作

## 入力仕様

### 入力パラメータ

#### clip copy

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (パイプライン入力) | Any | Yes | コピーする値 | - |
| --show, -s | Switch | No | コピーした値をパススルー表示 | - |

#### clip paste

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --raw, -r | Switch | No | JSONパースを無効化（デフォルト動作を反転） | - |

### 入力データソース

パイプライン入力（copy）、システムクリップボード（paste）

## 出力仕様

### 出力データ

#### clip copy

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (出力) | Nothing/Any | 通常Nothing、--show時は入力値 |

#### clip paste

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (出力) | Any | クリップボードの内容（JSON時はパース済み） |

### 出力先

パイプライン出力

## 処理フロー

### 処理シーケンス（clip copy）

```
1. 入力取得
   └─ パイプラインから値を取得
2. テキスト変換
   ├─ String: そのまま使用
   └─ その他: render_value_as_plain_table_text()でテーブル化
3. クリップボードコピー
   └─ create_clipboard().copy_text()
4. 結果返却
   └─ --show時は値をパススルー、それ以外はNothing
```

### 処理シーケンス（clip paste）

```
1. クリップボード取得
   └─ create_clipboard().get_text()
2. 空チェック
   └─ 空の場合はエラー
3. パース判定
   ├─ --raw または default_raw: 文字列として返却
   └─ JSON形式の場合: convert_json_string_to_value()
4. 結果返却
   └─ パース結果または文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[clip copy実行] --> B{入力型}
    B -->|String| C[そのまま使用]
    B -->|その他| D[テーブルテキスト変換]
    C --> E[クリップボードにコピー]
    D --> E
    E --> F{--show?}
    F -->|Yes| G[値をパススルー]
    F -->|No| H[Nothing返却]

    I[clip paste実行] --> J[クリップボード取得]
    J --> K{空?}
    K -->|Yes| L[エラー: クリップボードが空]
    K -->|No| M{--raw または default_raw?}
    M -->|Yes| N[文字列として返却]
    M -->|No| O{JSON形式?}
    O -->|Yes| P[JSONパース]
    O -->|No| N
    P --> Q{パース成功?}
    Q -->|Yes| R[パース結果返却]
    Q -->|No| N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | プレーンテキスト変換 | ANSIエスケープなしのテーブル出力 | 非String値のcopy |
| BR-02 | 自動JSONパース | {, [, "で始まる場合JSONパース試行 | paste時 |
| BR-03 | パース失敗時fallback | JSONパース失敗時は文字列として返却 | paste時 |
| BR-04 | default_raw設定 | $env.config.clip.default_rawで動作反転 | paste時 |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| GenericError | 空クリップボード | クリップボードが空 | データをコピーしてから実行 |
| ShellError | コピー失敗 | クリップボードアクセスエラー | クリップボードプロバイダー確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

特になし（即座に完了）

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

- クリップボードは他のアプリケーションからもアクセス可能
- 機密情報のクリップボードコピーは避けること
- 悪意あるスクリプトによるクリップボード監視のリスク

## 備考

- プラグイン形式のクリップボードプロバイダー対応
- 設定で外部クリップボードツール使用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | copy.rs | `crates/nu-command/src/platform/clip/copy.rs` | ClipCopyのシグネチャ |
| 1-2 | paste.rs | `crates/nu-command/src/platform/clip/paste.rs` | ClipPasteのシグネチャ |

**読解のコツ**:
- **copy.rs 30-34行目**: 入力Any、出力Any、--showオプション
- **paste.rs 16-24行目**: 入力Nothing、出力Any、--rawオプション

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | copy.rs | `crates/nu-command/src/platform/clip/copy.rs` | clip copyの実装 |
| 2-2 | paste.rs | `crates/nu-command/src/platform/clip/paste.rs` | clip pasteの実装 |

**主要処理フロー（copy.rs）**:
- **40-57行目**: run()で入力取得、copy_text()呼び出し、--show処理
- **9-22行目**: copy_text()でString/非Stringの分岐処理
- **21行目**: create_clipboard().copy_text()でコピー実行

**主要処理フロー（paste.rs）**:
- **32-65行目**: run()でクリップボード取得、パース処理
- **40行目**: create_clipboard().get_text()でテキスト取得
- **41-48行目**: 空クリップボードのエラー処理
- **51-54行目**: --raw / default_rawの判定
- **56-62行目**: JSON形式の判定とパース

#### Step 3: クリップボードプロバイダーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mod.rs | `crates/nu-command/src/platform/clip/mod.rs` | モジュール構成 |
| 3-2 | get_config.rs | `crates/nu-command/src/platform/clip/get_config.rs` | 設定取得 |

**主要処理フロー**:
- create_clipboard()でClipboardトレイトを実装したプロバイダー取得
- 設定によりネイティブまたは外部ツールを使用

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

```
clip copy コマンド
    │
    └─ run()
           │
           ├─ input.into_value()
           │
           ├─ copy_text()
           │      │
           │      ├─ [String] そのまま使用
           │      │
           │      └─ [非String] render_value_as_plain_table_text()
           │
           ├─ create_clipboard()
           │      └─ Clipboardトレイト実装取得
           │
           └─ clipboard.copy_text()

clip paste コマンド
    │
    └─ run()
           │
           ├─ create_clipboard()
           │
           ├─ clipboard.get_text()
           │
           ├─ 空チェック
           │
           ├─ get_default_raw()
           │      └─ config.clip.default_raw / レガシー設定
           │
           └─ [JSON形式] convert_json_string_to_value()
```

### データフロー図

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

Any (値) ───────────────▶ clip copy ────────────────────▶ Nothing (--showなし)
                         テキスト変換                    Any (--showあり)
                         クリップボードコピー

(なし) ─────────────────▶ clip paste ───────────────────▶ Any (パース結果/文字列)
                         クリップボード読み取り
                         JSONパース（オプション）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-command/src/platform/clip/mod.rs` | ソース | モジュール定義 |
| command.rs | `crates/nu-command/src/platform/clip/command.rs` | ソース | clipコマンド（ヘルプ） |
| copy.rs | `crates/nu-command/src/platform/clip/copy.rs` | ソース | clip copyコマンド |
| paste.rs | `crates/nu-command/src/platform/clip/paste.rs` | ソース | clip pasteコマンド |
| get_config.rs | `crates/nu-command/src/platform/clip/get_config.rs` | ソース | クリップボード設定取得 |
| clip.rs | `crates/nu-protocol/src/config/clip.rs` | ソース | クリップボード設定構造体 |
