# 画面設計書 28-nimgrepメイン画面

## 概要

本ドキュメントは、Nimgrepツールのメイン画面（CLIインターフェース）に関する画面設計書である。

### 本画面の処理概要

nimgrepは、Nim向けに最適化された高機能なgrep（検索・置換）ツールである。正規表現およびPEG（Parsing Expression Grammar）パターンによる検索・置換をサポートする。

**業務上の目的・背景**：大規模なコードベースで特定のパターンを検索・置換する際、標準のgrepコマンドでは機能が不足することがある。nimgrepはNimコードに特化した検索機能を提供し、スタイル無視検索（アンダースコアやケースの違いを無視）、PEGパターンマッチング、マルチスレッド検索など、高度な機能を備える。

**画面へのアクセス方法**：コマンドラインから直接実行する。
```
nimgrep [options] PATTERN [REPLACEMENT] [paths...]
```

**主要な操作・処理内容**：
1. コマンドライン引数を解析（パターン、置換文字列、対象パス）
2. 検索オプション（正規表現/PEG、大文字小文字、スタイル無視等）を設定
3. 対象ファイル/ディレクトリを走査
4. パターンマッチングを実行
5. 結果を表示（または置換を実行）

**画面遷移**：
- 遷移元: シェル/ターミナルからの直接実行
- 遷移先: 処理完了後、マッチ数とエラー数を表示してシェルに戻る

**権限による表示制御**：本ツールはCLIベースであり、権限による表示制御は存在しない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | Nimgrep | 主機能 | Nim向け高機能grep検索・置換のメイン処理 |
| 38 | pegs | 補助機能 | PEGパターンによる検索処理 |

## 画面種別

コマンドライン（CLI）

## URL/ルーティング

```
# 基本検索
nimgrep "pattern" path/

# 正規表現検索
nimgrep --re "pattern" path/

# PEG検索
nimgrep --peg "pattern" path/

# 置換
nimgrep --replace "pattern" "replacement" path/

# スタイル無視検索
nimgrep -y "myVariable" .  # myVariable, my_variable, myVARIABLE等にマッチ

# 再帰検索
nimgrep -r "pattern" .

# マルチスレッド
nimgrep -j4 "pattern" .
```

## 入出力項目

### コマンドラインオプション（主要なもの）

| オプション | 型 | 説明 |
|-----------|-----|------|
| -f, --find | flag | 検索モード（デフォルト） |
| -!, --replace | flag | 置換モード |
| --peg | flag | PEGパターンを使用 |
| --re | flag | 正規表現を使用（デフォルト） |
| -r, --recursive | flag | 再帰的にディレクトリを検索 |
| -i, --ignoreCase | flag | 大文字小文字を無視 |
| -y, --ignoreStyle | flag | スタイルを無視（アンダースコア、ケース） |
| -w, --word | flag | 単語単位でマッチ |
| -j, --threads | int | スレッド数 |
| --confirm | flag | 置換前に確認 |
| -c, --count | flag | マッチ数のみ表示 |
| --ext | string | 対象拡張子 |
| --nocolor | flag | 色付けなし |
| -b, --beforeContext | int | マッチ前のコンテキスト行数 |
| -a, --afterContext | int | マッチ後のコンテキスト行数 |

### 入力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PATTERN | string | 検索パターン（正規表現またはPEG） |
| REPLACEMENT | string | 置換文字列（--replace時） |
| paths | seq[string] | 検索対象パス |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| マッチ結果 | string | ファイル名、行番号、マッチ内容 |
| 統計情報 | string | マッチ数、エラー数 |

## 表示項目

検索結果として以下の情報が表示される:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| ファイル名 | マッチしたファイル | `src/main.nim` |
| 行番号 | マッチした行 | `42:` |
| マッチ内容 | ハイライトされたマッチ箇所 | `proc **myFunc**()` |
| 統計 | 総マッチ数 | `15 matches` |

## イベント仕様

### 1-コマンドライン解析

1. getoptでオプションを解析（行1247-1389）
2. 検索パターン、置換文字列、パスを抽出
3. searchOpt、walkOptに設定を格納

### 2-ファイル走査

1. walkRec/walkDirBasicでディレクトリを再帰走査（行983-1044）
2. 拡張子、ファイル名パターンでフィルタリング
3. バイナリファイルの検出・除外

### 3-パターンマッチング

1. processFileでファイル内を検索（行845-926）
2. searchFileイテレータでマッチを収集（行689-732）
3. コンテキスト（前後の行）を取得

### 4-結果出力/置換

1. printOutputで結果を表示（行669-687）
2. 置換モードではreplaceMatchesでファイルを更新（行1046-1071）

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベースは使用しない |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|---------|
| エラー | `Error: empty pattern was given` | パターン未指定時 |
| エラー | `Error: no such file or directory` | パスが存在しない時 |
| エラー | `cannot specify both '$#' and '$#'` | 相反オプション指定時 |
| 情報 | `X matches` | 検索完了時 |
| 情報 | `X errors` | エラーがあった場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| パターンが空 | エラーメッセージを表示して終了 |
| ファイルが見つからない | エラーを出力、他ファイルの処理は継続 |
| PCREサイズ制限超過 | エラーメッセージを出力 |
| 相反オプション | エラーメッセージを表示して終了 |

## 備考

- バージョン2.0.0（行14）
- 正規表現（re）がデフォルト、PEGもサポート
- マルチスレッド対応（--threads/-j）
- カラーテーマ: simple, bnw, ack, gnu
- バイナリファイルの自動検出（--bin:off/on/only）
- PCRE正規表現のサイズ制限あり（MaxReBufSize）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nimgrep.nim | `tools/nimgrep.nim` | TOption列挙型（行61-64）、検索オプション |
| 1-2 | nimgrep.nim | `tools/nimgrep.nim` | SearchOpt/WalkOpt型（行112-131）、設定構造 |
| 1-3 | nimgrep.nim | `tools/nimgrep.nim` | Output型（行73-91）、結果構造 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nimgrep.nim | `tools/nimgrep.nim` | メインブロック（行1418-1434） |

**主要処理フロー**:
1. **行1247-1389**: コマンドライン解析
2. **行1391-1401**: オプション検証
3. **行1418-1434**: 実行ブロック

#### Step 3: 検索処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nimgrep.nim | `tools/nimgrep.nim` | run1Thread関数（行1112-1130） |
| 3-2 | nimgrep.nim | `tools/nimgrep.nim` | processFile関数（行845-926） |
| 3-3 | nimgrep.nim | `tools/nimgrep.nim` | searchFile関数（行689-732） |

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

```
main (行1418)
    │
    ├─ getopt - コマンドライン解析 (行1247)
    │
    ├─ checkOptions - オプション検証 (行1391)
    │
    ├─ run1Thread (シングルスレッド) (行1112)
    │      │
    │      ├─ walkRec - ディレクトリ走査
    │      │
    │      └─ processFileResult
    │             │
    │             ├─ processFile - ファイル検索
    │             │      │
    │             │      └─ searchFile - パターンマッチ
    │             │
    │             └─ printOutput / replaceMatches
    │
    └─ runMultiThread (マルチスレッド) (行1186)
           │
           ├─ pathProducer - パス生成スレッド
           │
           └─ worker - ワーカースレッド（複数）
```

### データフロー図

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

コマンドライン            nimgrep                         ターミナル
    │                         │                              │
    │  pattern, paths         │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    ディレクトリ走査                    │
    │                         │                              │
    │                    ファイル読み込み                    │
    │                         │                              │
    │                    パターンマッチ                      │
    │                         │                              │
    │                         │  マッチ結果（色付き）        │
    │                         │──────────────────────────────>│
    │                         │                              │
    │                         │  統計情報                    │
    │                         │──────────────────────────────>│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nimgrep.nim | `tools/nimgrep.nim` | ソース | メイン処理、検索・置換ロジック |
| pegs.nim | `lib/pure/pegs.nim` | ライブラリ | PEGパターンマッチング |
| re.nim | `lib/impure/re.nim` | ライブラリ | 正規表現（PCRE） |
| terminal.nim | `lib/pure/terminal.nim` | ライブラリ | カラー出力 |
