# 機能設計書 66-ビット演算

## 概要

本ドキュメントは、Nushellにおけるビット演算機能（bits コマンド群）の設計を記述する。整数およびバイナリデータに対するビット単位の論理演算・シフト・ローテーション操作を提供する。

### 本機能の処理概要

ビット演算機能は、整数値やバイナリデータに対してビット単位の操作を行う。AND、OR、XOR、NOT の論理演算、左右シフト、左右ローテーションをサポートし、低レベルのデータ操作や暗号処理、プロトコル解析などに使用できる。

**業務上の目的・背景**：フラグ操作、ビットマスク処理、暗号アルゴリズムの実装、バイナリプロトコルの解析など、ビット単位の操作が必要な場面がある。本機能により、外部ツールに頼らずNushell内でビット演算が可能となる。

**機能の利用シーン**：
- フラグのセット・クリア・トグル
- ビットマスクによるデータ抽出
- 暗号処理（XOR暗号など）
- バイナリプロトコルのフィールド操作
- ハードウェアレジスタの操作シミュレーション

**主要な処理内容**：
1. `bits and` - ビット単位のAND演算
2. `bits or` - ビット単位のOR演算
3. `bits xor` - ビット単位のXOR演算
4. `bits not` - ビット単位のNOT演算（論理否定）
5. `bits shl` - 左シフト
6. `bits shr` - 右シフト
7. `bits rol` - 左ローテーション
8. `bits ror` - 右ローテーション

**関連システム・外部連携**：外部システムとの直接連携はない。

**権限による制御**：特別な権限制御はなく、すべてのユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用機能（画面関連なし） |

## 機能種別

データ変換 / ビット操作

## 入力仕様

### 入力パラメータ

#### bits and / bits or / bits xor（二項演算）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| target | Int or Binary | Yes | 右辺オペランド | - |
| --endian, -e | String | No | エンディアン（native/little/big） | native, little, big のいずれか |

#### bits not（単項演算）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --signed, -s | Switch | No | 符号付き数値として扱う | - |
| --number-bytes, -n | Int | No | ワードサイズ（1, 2, 4, 8） | 1, 2, 4, 8 のいずれか |

#### bits shl / bits shr / bits rol / bits ror（シフト・ローテーション）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| bits | Int | Yes | シフト/ローテーションするビット数 | 正の整数 |
| --signed, -s | Switch | No | 符号付き数値として扱う | - |
| --number-bytes, -n | Int | No | ワードサイズ（1, 2, 4, 8） | 1, 2, 4, 8 のいずれか |

### 入力データソース

- **パイプライン入力**: Int, Binary, List[Int], List[Binary]

## 出力仕様

### 出力データ

| コマンド | 出力型 | 説明 |
|---------|--------|------|
| bits and | Int / Binary | AND演算結果 |
| bits or | Int / Binary | OR演算結果 |
| bits xor | Int / Binary | XOR演算結果 |
| bits not | Int / Binary | NOT演算結果 |
| bits shl | Int / Binary | 左シフト結果 |
| bits shr | Int / Binary | 右シフト結果 |
| bits rol | Int / Binary | 左ローテーション結果 |
| bits ror | Int / Binary | 右ローテーション結果 |

### 出力先

パイプラインへの出力（PipelineData）。

## 処理フロー

### 処理シーケンス

```
1. コマンドの引数解析
   └─ オペランド、フラグを取得

2. 入力データの判定
   └─ Int の場合は整数演算
   └─ Binary の場合はバイト配列演算
   └─ List の場合は各要素に演算を適用

3. ビット演算の実行
   └─ 二項演算: binary_op() で演算実行
   └─ 単項演算/シフト: action() で演算実行

4. 結果の返却
   └─ PipelineData として出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{入力の種類}
    B -->|Int| C[整数演算]
    B -->|Binary| D[バイト配列演算]
    B -->|List| E[各要素に演算適用]
    C --> F{演算種別}
    D --> F
    E --> F
    F -->|and| G[l & r]
    F -->|or| H[l \| r]
    F -->|xor| I[l ^ r]
    F -->|not| J[!val]
    F -->|shl| K[val << bits]
    F -->|shr| L[val >> bits]
    F -->|rol| M[val.rotate_left]
    F -->|ror| N[val.rotate_right]
    G --> O[Value::int / Value::binary]
    H --> O
    I --> O
    J --> O
    K --> O
    L --> O
    M --> O
    N --> O
    O --> P[PipelineData返却]
    P --> Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 型の一致 | 入力と引数は同じ型（Int同士またはBinary同士） | and/or/xor |
| BR-002 | エンディアン処理 | Binary同士で長さが異なる場合、パディングの方向をエンディアンで制御 | and/or/xor |
| BR-003 | 自動サイズ | --number-bytes 省略時は値に応じた最小サイズを自動選択 | not/shl/shr/rol/ror |
| BR-004 | シフト上限 | シフト/ローテーションビット数は利用可能ビット数未満 | shl/shr/rol/ror |
| BR-005 | 符号付き処理 | --signed で符号付き整数として演算 | not/shl/shr/rol/ror |

### 計算ロジック

- **bits and**: `l & r`（整数）、バイトごとに `l[i] & r[i]`（バイナリ）
- **bits or**: `l | r`（整数）、バイトごとに `l[i] | r[i]`（バイナリ）
- **bits xor**: `l ^ r`（整数）、バイトごとに `l[i] ^ r[i]`（バイナリ）
- **bits not**: `!val`（整数、マスク適用）、バイトごとに `!b`（バイナリ）
- **bits shl**: `(val as uN) << bits`（整数）、バイト・ビットシフト（バイナリ）
- **bits shr**: `(val as uN) >> bits`（整数）、バイト・ビットシフト（バイナリ）
- **bits rol**: `val.rotate_left(bits)`（整数）、バイト・ビットローテーション（バイナリ）
- **bits ror**: `val.rotate_right(bits)`（整数）、バイト・ビットローテーション（バイナリ）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OnlySupportsThisInputType | 型エラー | Int/Binary以外の入力 | Int または Binary を入力 |
| OnlySupportsThisInputType | 型エラー | 入力と引数の型が不一致 | 同じ型を使用 |
| TypeMismatch | 型エラー | 無効なエンディアン指定 | native/little/big のいずれかを指定 |
| UnsupportedInput | 型エラー | 無効な number-bytes 値 | 1, 2, 4, 8 のいずれかを指定 |
| IncorrectValue | 値エラー | シフトビット数がサイズを超過 | より小さいビット数を指定 |
| PipelineEmpty | 入力エラー | 空のパイプライン入力 | 有効な値をパイプで渡す |

### リトライ仕様

リトライは不要。

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

本機能はトランザクション管理を行わない。

## パフォーマンス要件

- ビット演算はCPUのネイティブ命令にマッピングされ、高速
- Binary のシフト/ローテーションはバイト配列の操作が必要
- リスト入力の場合、各要素に対して演算が適用される

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

- XOR演算は暗号処理に使用されることがあるが、単純なXOR暗号は安全ではない
- ビット操作によるデータ改ざんに注意

## 備考

- 8コマンドすべて nu-cmd-extra クレートに配置（拡張機能）
- Category::Bits として分類

---

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

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

### 推奨読解順序

#### Step 1: モジュール構成と共通関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mod.rs | `crates/nu-cmd-extra/src/extra/bits/mod.rs` | 公開コマンドと共通関数 |

**主要処理フロー**:
- **11-19行目**: 8つのコマンドのエクスポート
- **24-31行目**: NumberBytes 列挙型（ワードサイズ）
- **33-62行目**: InputNumType 列挙型と num_bits() メソッド
- **64-81行目**: get_number_bytes() でワードサイズを解析
- **83-121行目**: get_input_num_type() で入力値から適切な型を判定
- **123-184行目**: binary_op() で二項演算を汎用的に実行

#### Step 2: 二項論理演算（and/or/xor）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | and.rs | `crates/nu-cmd-extra/src/extra/bits/and.rs` | bits and 実装 |
| 2-2 | or.rs | `crates/nu-cmd-extra/src/extra/bits/or.rs` | bits or 実装 |
| 2-3 | xor.rs | `crates/nu-cmd-extra/src/extra/bits/xor.rs` | bits xor 実装 |

**主要処理フロー（and.rs）**:
- **31-36行目**: --endian フラグ定義
- **59-73行目**: エンディアンの解析（native/little/big）
- **80-83行目**: `binary_op()` で `l & r` を実行

#### Step 3: 単項演算（not）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | not.rs | `crates/nu-cmd-extra/src/extra/bits/not.rs` | bits not 実装 |

**主要処理フロー**:
- **40-50行目**: --signed, --number-bytes フラグ定義
- **85行目**: operate() で各値に action を適用
- **135-182行目**: action() 関数
- **143-165行目**: 整数の NOT（マスク適用で unsigned 扱い）
- **167-168行目**: バイナリの NOT（各バイトを反転）

#### Step 4: シフト演算（shl/shr）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | shift_left.rs | `crates/nu-cmd-extra/src/extra/bits/shift_left.rs` | bits shl 実装 |
| 4-2 | shift_right.rs | `crates/nu-cmd-extra/src/extra/bits/shift_right.rs` | bits shr 実装 |

**主要処理フロー（shift_left.rs）**:
- **43行目**: bits 引数（シフトビット数）
- **130-229行目**: action() 関数
- **145-158行目**: シフト上限チェック
- **159-186行目**: 整数型ごとのシフト処理
- **190-215行目**: バイナリのシフト処理
- **231-255行目**: shift_bytes_left(), shift_bytes_and_bits_left() 補助関数

#### Step 5: ローテーション演算（rol/ror）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | rotate_left.rs | `crates/nu-cmd-extra/src/extra/bits/rotate_left.rs` | bits rol 実装 |
| 5-2 | rotate_right.rs | `crates/nu-cmd-extra/src/extra/bits/rotate_right.rs` | bits ror 実装 |

**主要処理フロー（rotate_left.rs）**:
- **40行目**: bits 引数（ローテーションビット数）
- **144-168行目**: 整数型ごとの rotate_left() 呼び出し
- **173-198行目**: バイナリのローテーション処理
- **213-240行目**: rotate_bytes_left(), rotate_bytes_and_bits_left() 補助関数

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

```
bits (bits_.rs)
    │
    ├─ bits and (and.rs)
    │      └─ run() → binary_op(|(l, r)| l & r)
    │
    ├─ bits or (or.rs)
    │      └─ run() → binary_op(|(l, r)| l | r)
    │
    ├─ bits xor (xor.rs)
    │      └─ run() → binary_op(|(l, r)| l ^ r)
    │
    ├─ bits not (not.rs)
    │      └─ run() → operate(action)
    │             └─ action(): !val (with mask)
    │
    ├─ bits shl (shift_left.rs)
    │      └─ run() → operate(action)
    │             └─ action(): val << bits
    │
    ├─ bits shr (shift_right.rs)
    │      └─ run() → operate(action)
    │             └─ action(): val >> bits
    │
    ├─ bits rol (rotate_left.rs)
    │      └─ run() → operate(action)
    │             └─ action(): val.rotate_left(bits)
    │
    └─ bits ror (rotate_right.rs)
           └─ run() → operate(action)
                  └─ action(): val.rotate_right(bits)
```

### データフロー図

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

Int ──────────────────▶ 整数演算 ────────────────────────▶ Int
                              │
Binary ───────────────▶ バイト配列演算 ──────────────────▶ Binary
                              │
List[Int/Binary] ─────▶ 各要素に演算適用 ────────────────▶ List[Int/Binary]
                              │
                              ▼
                       PipelineData返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-cmd-extra/src/extra/bits/mod.rs` | ソース | モジュール定義・共通関数 |
| bits_.rs | `crates/nu-cmd-extra/src/extra/bits/bits_.rs` | ソース | 親コマンド（ヘルプ表示） |
| and.rs | `crates/nu-cmd-extra/src/extra/bits/and.rs` | ソース | bits and 実装 |
| or.rs | `crates/nu-cmd-extra/src/extra/bits/or.rs` | ソース | bits or 実装 |
| xor.rs | `crates/nu-cmd-extra/src/extra/bits/xor.rs` | ソース | bits xor 実装 |
| not.rs | `crates/nu-cmd-extra/src/extra/bits/not.rs` | ソース | bits not 実装 |
| shift_left.rs | `crates/nu-cmd-extra/src/extra/bits/shift_left.rs` | ソース | bits shl 実装 |
| shift_right.rs | `crates/nu-cmd-extra/src/extra/bits/shift_right.rs` | ソース | bits shr 実装 |
| rotate_left.rs | `crates/nu-cmd-extra/src/extra/bits/rotate_left.rs` | ソース | bits rol 実装 |
| rotate_right.rs | `crates/nu-cmd-extra/src/extra/bits/rotate_right.rs` | ソース | bits ror 実装 |
