# 機能設計書 101-colors

## 概要

本ドキュメントは、Nim標準ライブラリの`colors`モジュールの機能設計を記述する。このモジュールは、RGB形式の色の操作およびCSS色名の解析機能を提供する。

### 本機能の処理概要

`colors`モジュールは、色のミキシング、CSS色名の解析、RGB値の抽出・変換など、色に関する各種操作を行う標準ライブラリである。

**業務上の目的・背景**：GUI開発、Web開発、画像処理など、多くのアプリケーションで色の操作が必要となる。CSS標準の色名と16進数表記の両方をサポートすることで、開発者が直感的に色を扱えるようにする。特に、Webアプリケーション開発において、CSSで定義された標準色名との互換性を確保することが重要である。

**機能の利用シーン**：HTMLドキュメント生成、ターミナルカラー出力、ゲームやGUI開発での色処理、画像生成・変換ツールなど、色の表現や操作が必要な場面全般で利用される。

**主要な処理内容**：
1. 色の加算・減算（飽和演算）
2. RGB成分の抽出
3. 色の強度（輝度）調整
4. CSS色名文字列から色値への変換
5. 色値から16進数文字列への変換
6. RGB値からColor型の構築

**関連システム・外部連携**：特になし。純粋なユーティリティライブラリとして機能する。

**権限による制御**：権限による制御は存在しない。

## 関連画面

本モジュールは標準ライブラリであり、特定の画面との関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

計算処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| a, b | Color | Yes | 色の加算・減算用の2つの色 | 有効なColor型 |
| f | float | Yes | 輝度調整係数 | 0.0〜1.0の範囲 |
| name | string | Yes | CSS色名または#付き16進数 | 有効な色名または#xxxxxx形式 |
| r, g, b | range[0..255] | Yes | RGB各成分 | 0〜255の範囲 |

### 入力データソース

プログラムコードからの直接呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Color | distinct int | RGB色値（16進数で0xRRGGBB形式） |
| string | string | "#RRGGBB"形式の文字列 |
| tuple[r, g, b] | range[0..255] | RGB各成分のタプル |
| bool | bool | 色名の有効性 |

### 出力先

呼び出し元への戻り値。

## 処理フロー

### 処理シーケンス

```
1. 色の加算処理 (`+`)
   └─ 各RGB成分を加算し、255を超えたら飽和させる

2. 色の減算処理 (`-`)
   └─ 各RGB成分を減算し、0未満なら0に飽和させる

3. RGB抽出 (extractRGB)
   └─ ビットシフトとAND演算でR/G/Bを分離

4. 輝度調整 (intensity)
   └─ 各成分に係数を掛けて新しい色を生成

5. 色名解析 (parseColor)
   └─ #で始まる場合は16進数として解析
   └─ そうでなければcolorNames配列から二分探索

6. 色名検証 (isColor)
   └─ parseColorと同様のロジックで有効性を確認
```

### フローチャート

```mermaid
flowchart TD
    A[開始: parseColor] --> B{#で始まる?}
    B -->|Yes| C[parseHexIntで16進数解析]
    B -->|No| D[binarySearchで色名検索]
    D --> E{見つかった?}
    E -->|Yes| F[対応するColor値を返却]
    E -->|No| G[ValueError例外]
    C --> H[Color型として返却]
    F --> I[終了]
    H --> I
    G --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 飽和演算 | 色の加算で255を超えた場合は255、減算で0未満の場合は0に制限 | 色の加算・減算時 |
| BR-02 | 色名の大文字小文字 | 色名の解析は大文字小文字を区別しない | parseColor、isColor呼び出し時 |
| BR-03 | 16進数形式 | #RRGGBBまたは色名のみ有効 | parseColor呼び出し時 |

### 計算ロジック

**飽和加算（satPlus）**:
```nim
result = a +% b
if result > 255: result = 255
```

**飽和減算（satMinus）**:
```nim
result = a -% b
if result < 0: result = 0
```

**RGB抽出**:
```nim
r = a.int shr 16 and 0xff
g = a.int shr 8 and 0xff
b = a.int and 0xff
```

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

本モジュールはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValueError | 実行時例外 | 無効な色名をparseColorに渡した場合 | 有効な色名または#RRGGBB形式を使用 |

### リトライ仕様

リトライは不要。エラー発生時は入力値を修正して再実行。

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

トランザクション管理は不要。

## パフォーマンス要件

- 色名の検索は二分探索（O(log n)）で実装
- 147種類のCSS色名に対応

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

特になし。純粋な計算処理のみ。

## 備考

- Color型は`distinct int`として定義されており、通常の整数との誤用を防止
- 定義済み色定数は148色（colAliceBlue〜colYellowGreen）

---

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

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

### 推奨読解順序

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

Color型の定義と色定数の理解が基盤となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | colors.nim | `lib/pure/colors.nim` | 16行目: Color型の定義（distinct int） |
| 1-2 | colors.nim | `lib/pure/colors.nim` | 148-446行目: 色定数と色名マッピング |

**読解のコツ**: `distinct int`はNimの独自型機能で、型安全性を確保しつつ内部的にはintとして扱える。

#### Step 2: 基本演算を理解する

色の加算・減算の飽和演算ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | colors.nim | `lib/pure/colors.nim` | 30-36行目: extract/rawRGBテンプレート |
| 2-2 | colors.nim | `lib/pure/colors.nim` | 43-50行目: satPlus/satMinus関数 |
| 2-3 | colors.nim | `lib/pure/colors.nim` | 51-77行目: `+`と`-`演算子の実装 |

**主要処理フロー**:
- **30-33行目**: extractテンプレートでRGB成分を分離
- **35-36行目**: rawRGBテンプレートでColor値を合成
- **43-45行目**: satPlusで加算結果を255で制限
- **47-49行目**: satMinusで減算結果を0で制限

#### Step 3: 色の解析処理を理解する

CSS色名や16進数からの変換ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | colors.nim | `lib/pure/colors.nim` | 455-456行目: colorNameCmp比較関数 |
| 3-2 | colors.nim | `lib/pure/colors.nim` | 458-478行目: parseColor関数 |
| 3-3 | colors.nim | `lib/pure/colors.nim` | 480-499行目: isColor関数 |

**主要処理フロー**:
- **473-474行目**: #で始まる場合はparseHexIntで解析
- **476-478行目**: そうでなければbinarySearchで色名検索

#### Step 4: ユーティリティ関数を理解する

その他の便利な関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | colors.nim | `lib/pure/colors.nim` | 79-97行目: extractRGB関数 |
| 4-2 | colors.nim | `lib/pure/colors.nim` | 99-116行目: intensity関数 |
| 4-3 | colors.nim | `lib/pure/colors.nim` | 118-145行目: mixテンプレート |
| 4-4 | colors.nim | `lib/pure/colors.nim` | 448-453行目: `$`演算子 |
| 4-5 | colors.nim | `lib/pure/colors.nim` | 501-507行目: rgb関数 |

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

```
colors.nim
    │
    ├─ Color型定義
    │      └─ distinct int
    │
    ├─ 演算子
    │      ├─ `+` ─── colorOp ─── satPlus
    │      ├─ `-` ─── colorOp ─── satMinus
    │      ├─ `==` (borrow)
    │      └─ `$` ─── toHex
    │
    ├─ 抽出・構築
    │      ├─ extractRGB ─── extract template
    │      ├─ rgb ─── rawRGB template
    │      ├─ intensity ─── extract, rawRGB
    │      └─ mix ─── extract, rawRGB
    │
    └─ 解析
           ├─ parseColor ─── parseHexInt / binarySearch
           └─ isColor ─── binarySearch
```

### データフロー図

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

Color値 (int) ──────▶ extractRGB ──────────────▶ tuple[r, g, b]
                          │
                          ▼
r, g, b (0..255) ──────▶ rgb ───────────────────▶ Color値

Color + Color ──────────▶ satPlus per component ─▶ Color値

Color - Color ──────────▶ satMinus per component ▶ Color値

"#RRGGBB" / "colorname" ▶ parseColor ────────────▶ Color値
                              │
                              └─▶ binarySearch(colorNames)

Color値 ────────────────▶ `$` ───────────────────▶ "#RRGGBB"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| colors.nim | `lib/pure/colors.nim` | ソース | メインモジュール、全機能の実装 |
| strutils.nim | `lib/pure/strutils.nim` | 依存 | parseHexInt、HexDigits定数 |
| algorithm.nim | `lib/pure/algorithm.nim` | 依存 | binarySearch関数 |
