# バッチ設計書 71-ansi-color.cmd

## 概要

本ドキュメントは、ANSIカラーのSGR（Select Graphic Rendition）パラメータを網羅的にテスト表示するWindowsコマンドスクリプト `ansi-color.cmd` のバッチ設計書である。

### 本バッチの処理概要

ansi-color.cmdは、ターミナル上でANSIエスケープシーケンスのSGRパラメータ（文字属性・前景色・背景色）の全組み合わせをマトリクス形式のテーブルとして描画し、色やスタイルのレンダリング結果を視覚的に確認できる診断ツールである。テーブルの定義はスクリプト自体に内蔵されているほか、外部定義ファイル（.def）からも読み込み可能であり、柔軟なカスタマイズに対応する。

**業務上の目的・背景**：Windows Terminalおよびコンソールホストの開発において、ANSIエスケープシーケンスの各SGRパラメータ（Bold、Italic、Underline、Blink、Reverse、Conceal、Crossed-out等）と16色/256色のカラーパレットが正しくレンダリングされるかを確認する必要がある。本ツールはColorToolと併用し、適用されたカラースキームの全色を一覧表示する診断ツールとして活用される。

**バッチの実行タイミング**：開発者による手動実行。カラースキームの変更時、ターミナルレンダリングの動作確認時、新しいSGRパラメータのサポート追加時などに随時実行される。

**主要な処理内容**：
1. コマンドライン引数の解析（/H, /A, /R, /U フラグおよび定義ファイルパスの取得）
2. 設定の初期化（テスト文字列、UTF-8モード、スピナー表示、ANSIシーケンス表示モード等）
3. データセグメント（テーブル定義）の読み込み（スクリプト内蔵または外部.defファイルから）
4. マクロ定義の初期化（Batchマクロ方式によるCSI制御、セル出力、テーブル描画等の関数定義）
5. テーブルヘッダー（列ヘッダー：背景色、行ヘッダー：前景色/属性）の構築と出力
6. 各行・各列の組み合わせに対してANSIエスケープシーケンスを生成し、テスト文字列を着色して出力
7. UTF-8コードページの設定・復元（/Uフラグ指定時またはUTF8.REQUIRED設定時）

**前後の処理との関連**：ColorTool（`src/tools/ColorTool`配下のbuild.batでビルド）と相補的な関係にあり、ColorToolが適用したカラースキームの結果を本スクリプトで確認できる。また、同ディレクトリ内の各種.defファイル（sgr.def、fgbg.def、colortest.def、crisman.def等）がテーブル定義として利用される。

**影響範囲**：ターミナルの表示のみに影響し、システムやデータへの永続的な変更は行わない。CHCPコマンドによるコードページの一時変更のみ副作用がある（スクリプト終了時に復元される）。

## バッチ種別

診断ツール / テスト表示

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows環境 | cmd.exe（Windowsコマンドプロンプト）が必要 |
| ANSIエスケープシーケンス対応ターミナル | Windows Terminal、ConEmu等のANSI対応ターミナルで実行すること |
| CHCP（UTF-8使用時） | UTF-8モード利用時はCHCPコマンドが利用可能であること |

### 実行可否判定

特別な実行可否判定ロジックはない。引数解析でエラーが発生した場合（不正なフラグ等）はERRORLEVEL 1を返してスクリプトを終了する。/Hフラグが指定された場合はヘルプを表示して正常終了する。UTF-8が必須の定義ファイル（`UTF8.REQUIRED=#TRUE#`設定）を使用する場合、/Uフラグが指定されていなければエラー終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| /H | フラグ | No | なし | ヘルプメッセージを表示する |
| /A | フラグ | No | なし | ANSIエスケープシーケンスの制御文字を表示する（ESCコードをUnicode表記に置換） |
| /R | フラグ | No | なし | セルテキストの代わりにR1C1参照アドレスを表示する |
| /U | フラグ | No | なし | UTF-8サポートを有効にする（コードページを65001に設定） |
| definition_file | ファイルパス | No | スクリプト内蔵定義 | 外部テーブル定義ファイル（.def）のパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| スクリプト内蔵データセグメント | テキスト（__DATA__セクション） | デフォルトのSGRテーブル定義。行（前景色/属性）と列（背景色）の組み合わせ |
| 外部定義ファイル（.def） | テキスト | __DATA__/__TABLE__/__COLS__/__ROWS__セクションを含むテーブル定義ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力（コンソール画面） | ANSIエスケープシーケンス付きテキスト | SGRパラメータの組み合わせマトリクステーブル |
| 標準出力（リダイレクト時） | テキスト | /Aフラグ使用時はESCコードをUnicode表記に置換したテキストを出力 |

### 出力ファイル仕様

ファイル出力は行わない。標準出力へのリダイレクトにより間接的にファイル出力可能（`ansi-color /a > out.txt`）。

| 項目 | 内容 |
|-----|------|
| ファイル名 | なし（標準出力のみ） |
| 出力先 | コンソール（標準出力） |
| 文字コード | 環境依存（/Uフラグ指定時はUTF-8/コードページ65001） |
| 区切り文字 | セル間のセパレータ文字（定義ファイルで設定可能。デフォルトはスペース） |

## 処理フロー

### 処理シーケンス

```
1. マクロ定義（:DEFINE_MACROS）
   └─ Batchマクロ（@exit, @strlen, @pad, @trim, @maxval, @spinner等）を環境変数として定義
2. エントリポイント（:MAIN）
   └─ SETLOCAL ENABLEDELAYEDEXPANSIONを有効化
3. 引数解析（:PARSE_ARGS）
   └─ /H, /A, /R, /U フラグおよび定義ファイルパスを解析
4. 設定初期化（:CONFIGURATION）
   └─ デフォルトのテスト文字列（CELL=" gYw "）、スピナー、表示モード等の設定
5. コードページの保存・変更
   └─ CHCPで現在のコードページを保存し、UTF-8が必要な場合は65001に変更
6. データセグメント読み込み
   └─ __DATA__/__TABLE__/__COLS__/__ROWS__セクションの解析
      ├─ 外部.defファイル指定時はそのファイルからデータを読み込み
      └─ 未指定時はスクリプト自体の内蔵データを使用
7. テーブル構築
   ├─ __TABLE__セクション: セル文字列、ヘッダー名、セパレータ文字、アラインメント等を設定
   ├─ __COLS__セクション: 列定義（背景色SGRパラメータ）を配列として格納
   └─ __ROWS__セクション: 行定義（前景色/属性SGRパラメータ）を配列として格納
8. テーブル描画
   ├─ ヘッダー行の出力（Stubhead + Boxhead）
   ├─ 各行についてループ処理
   │   ├─ #NUL#: SGRパラメータなしでデフォルト表示
   │   ├─ #SPC#: 空行（ギャップ）を出力
   │   ├─ #LBL#: セクションラベルを出力
   │   └─ SGRパラメータ: 各列との組み合わせでANSIエスケープシーケンスを生成・表示
   └─ 各セルにCSI + 行パラメータ + 列パラメータ + テスト文字列 + SGRリセットを出力
9. クリーンアップ
   └─ コードページの復元（UTF-8モード使用時）、ENDLOCAL
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[マクロ定義]
    B --> C[引数解析]
    C --> D{引数エラー/ヘルプ?}
    D -->|エラー| E[エラー終了]
    D -->|ヘルプ| F[ヘルプ表示して終了]
    D -->|正常| G[設定初期化]
    G --> H[コードページ保存・UTF-8設定]
    H --> I{外部定義ファイル指定?}
    I -->|あり| J[外部.defファイル読み込み]
    I -->|なし| K[内蔵データセグメント使用]
    J --> L[テーブル定義解析]
    K --> L
    L --> M{UTF-8必須チェック}
    M -->|失敗| N[エラー表示して終了]
    M -->|成功| O[セパレータ解決]
    O --> P[テーブルヘッダー出力]
    P --> Q[各行ループ処理]
    Q --> R{行の種別}
    R -->|#NUL#| S[デフォルト表示]
    R -->|#SPC#| T[空行出力]
    R -->|#LBL#| U[ラベル出力]
    R -->|SGRパラメータ| V[各列とのSGR組み合わせ出力]
    S --> W{次の行あり?}
    T --> W
    U --> W
    V --> W
    W -->|あり| Q
    W -->|なし| X[コードページ復元]
    X --> Y[バッチ終了]
```

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

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

データベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | なし | なし | 本バッチはデータベースに対する操作を行わない |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERRORLEVEL 1 | 引数解析エラー | 不正なフラグや引数が指定された場合 | ヘルプメッセージ（/Hフラグ）を参照して正しい引数で再実行する |
| ERRORLEVEL 1 | ファイル読み込みエラー | 指定された定義ファイルが存在しない場合 | 定義ファイルのパスを確認して再実行する |
| ERRORLEVEL 1 | UTF-8設定エラー | UTF-8必須の定義でUTF-8が有効でない場合 | /Uフラグを指定して再実行する |
| ERRORLEVEL 1 | コードページ変更エラー | CHCPによるコードページ変更に失敗した場合 | CHCPコマンドの利用可否を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | なし |
| リトライ対象エラー | なし（リトライ機構は実装されていない） |

### 障害時対応

コードページの変更（CHCP 65001）が行われた状態でスクリプトが異常終了した場合、手動でCHCPコマンドを使用してコードページを元に戻す必要がある（通常は自動復元される）。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（データベースやファイル書き込み操作を行わない） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | SGRパラメータの行列定義数に依存（デフォルトでは約200セル以上のSGR組み合わせ） |
| 目標処理時間 | 数秒〜数十秒（テーブルサイズとスピナー有効/無効に依存） |
| メモリ使用量上限 | cmd.exeの環境変数領域に依存（通常問題にならない） |

## 排他制御

排他制御は不要。複数インスタンスの同時実行が可能である（各インスタンスはSETLOCALにより独立した環境で動作する）。ただし、同一コンソールでの同時実行はコードページの競合が発生する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗表示 | テーブル描画中 | スピナーアニメーション（SPINNER.DISABLED未設定時） |
| エラー出力 | 引数解析エラー時 | エラーメッセージおよびヘルプ情報 |
| ヘルプ出力 | /Hフラグ指定時 | 使用方法とフラグの説明 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | なし | なし（対話的な診断ツールのため監視対象外） |

## 備考

- 本スクリプトはRyan Beesleyにより作成され（https://github.com/rbeesley）、Windows Terminalプロジェクトに組み込まれている
- Batchマクロの概念はEd Dyreen、Jeb、Dave BenhamによりDosTips.comで考案された技法を活用している
- スクリプト自体がUTF-8テキストファイルであり、再コンパイル不要で直接編集可能である
- スクリプト自身が定義ファイルとしても機能し、外部定義ファイルなしで動作可能
- 同梱の定義ファイル群：sgr.def、fgbg.def、colortest.def、crisman.def、colortool.def、ansi-colortool.def、ubuntu.def、rainbow.def、attrib.def、lbl.def、rosetta.def、plaid.def、separator.def、tsgr.def、sgr-intensity.def
- 特殊トークン `#NUL#`（デフォルト値表示）、`#SPC#`（空白行/列）、`#LBL#`（ラベル行）によるテーブルレイアウト制御が可能
- PowerShellから全定義ファイルを一括実行するコマンド: `gci -r .\*.def | %{write ($_ | rvpa -r) && .\ansi-color.cmd $_}`
