# 画面設計書 9-nim dump（設定ダンプ）

## 概要

本ドキュメントは、Nimコンパイラの設定情報やパス情報をダンプするサブコマンド`nim dump`のCLIインターフェース設計書です。

### 本画面の処理概要

`nim dump`コマンドは、現在のNimコンパイラの設定情報（定義済みシンボル、検索パス、出力ディレクトリ等）を出力するサブコマンドです。デバッグや設定確認、ビルドスクリプトでの環境情報取得に使用されます。テキスト形式またはJSON形式での出力をサポートします。

**業務上の目的・背景**：コンパイラの設定状態を可視化し、ビルド問題のデバッグや環境設定の確認を容易にします。特にCI/CDパイプラインでの環境確認やクロスコンパイル設定の検証に有用です。

**画面へのアクセス方法**：ターミナルから`nim dump <filename.nim>`または`nim dump --dump.format:json <filename.nim>`を実行します。

**主要な操作・処理内容**：
1. プロジェクト設定の読み込み
2. 定義済みシンボルの収集
3. 検索パスの収集
4. 各種設定値の収集
5. テキストまたはJSON形式で出力

**画面遷移**：
- 入力元：`nim`メインコマンドから`cmdDump`として呼び出し
- 遷移先：なし（出力完了後終了）

**権限による表示制御**：OSのファイルシステム権限に依存。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Nimコンパイラ本体 | 主機能 | コンパイラ設定やパス情報をダンプする処理 |

## 画面種別

CLIサブコマンド（設定ダンプ）

## URL/ルーティング

```
nim dump [options] [projectfile.nim]
```

オプション例：
- `nim dump` - 現在の設定をテキスト形式で出力
- `nim dump hello.nim` - プロジェクト設定をテキスト形式で出力
- `nim dump --dump.format:json hello.nim` - JSON形式で出力

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| projectfile | string | 入力 | いいえ | 対象のNimソースファイル |
| --dump.format | enum | 入力 | いいえ | 出力形式（text/json） |
| 標準出力 | text/json | 出力 | - | ダンプ結果 |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| version | Nimコンパイラバージョン | JSON形式時 |
| nimExe | nim実行ファイルパス | JSON形式時 |
| prefixdir | インストールプレフィックス | JSON形式時 |
| libpath | 標準ライブラリパス | JSON形式時 |
| project_path | プロジェクトファイルパス | JSON形式時 |
| defined_symbols | 定義済みシンボル一覧 | 常時 |
| lib_paths | ライブラリ検索パス一覧 | JSON形式時 |
| lazyPaths | 遅延読み込みパス | JSON形式時 |
| outdir | 出力ディレクトリ | JSON形式時 |
| out | 出力ファイル名 | JSON形式時 |
| nimcache | nimcacheディレクトリ | JSON形式時 |
| hints | ヒント設定 | JSON形式時 |
| warnings | 警告設定 | JSON形式時 |

## イベント仕様

### 1-コマンド処理開始

`commands.nim`で`"dump"`を`cmdDump`にマップ（行496）：

1. `parseCommand("dump")` -> `cmdDump`
2. 設定とオプションの初期化

### 2-ダンプ処理（JSON形式）

`main.nim`の`cmdDump`ケース（行372-407）でJSON形式出力：

```nim
of cmdDump:
  if getConfigVar(conf, "dump.format") == "json":
    wantMainModule(conf)

    var definedSymbols = newJArray()
    for s in definedSymbolNames(conf.symbols): definedSymbols.elems.add(%s)

    var libpaths = newJArray()
    var lazyPaths = newJArray()
    for dir in conf.searchPaths: libpaths.elems.add(%dir.string)
    for dir in conf.lazyPaths: lazyPaths.elems.add(%dir.string)
    ...
```

### 3-JSON出力項目

- **行392-405**: 以下のJSONオブジェクトを構築
  - `version`: `VersionAsString`
  - `nimExe`: `getAppFilename()`
  - `prefixdir`: `conf.getPrefixDir().string`
  - `libpath`: `conf.libpath.string`
  - `project_path`: `conf.projectFull.string`
  - `defined_symbols`: 定義済みシンボル配列
  - `lib_paths`: 検索パス配列
  - `lazyPaths`: 遅延パス配列
  - `outdir`: `conf.outDir.string`
  - `out`: `conf.outFile.string`
  - `nimcache`: `getNimcacheDir(conf).string`
  - `hints`: ヒント設定オブジェクト
  - `warnings`: 警告設定オブジェクト

### 4-ダンプ処理（テキスト形式）

`main.nim`行409-415でテキスト形式出力：

```nim
else:
  msgWriteln(conf, "-- list of currently defined symbols --",
             {msgStdout, msgSkipHook, msgNoUnitSep})
  for s in definedSymbolNames(conf.symbols): msgWriteln(conf, s, ...)
  msgWriteln(conf, "-- end of list --", {msgStdout, msgSkipHook})

  for it in conf.searchPaths: msgWriteln(conf, it.string)
```

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

本CLIツールはデータベースを使用しません。

### ファイルシステム操作

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| 参照 | nim.cfg等 | READ | 設定ファイル読み込み |
| 参照 | *.nim | READ | プロジェクトファイル参照（JSON形式時） |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| 出力 | "-- list of currently defined symbols --" | テキスト形式時 |
| 出力 | "-- end of list --" | テキスト形式時 |
| 出力 | JSON形式のダンプデータ | JSON形式時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| プロジェクトファイル不在（JSON形式時） | "cannot open file: $1" | エラー終了 |

## 備考

- JSON形式ではプロジェクトファイルが必須（`wantMainModule`）
- テキスト形式ではプロジェクトファイルなしでも動作
- `nimconf.nim`行309: `cmdDump`時は設定エラーを無視
- 成功メッセージは表示されない（`cmdDump`は`genSuccessX`対象外）
- ヒント/警告設定はJSON形式でのみ出力される
- ビルドスクリプトからの環境情報取得に便利

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.nim | `compiler/options.nim` | cmdDump（Command列挙型行174） |
| 1-2 | options.nim | `compiler/options.nim` | ConfigRef型（設定保持） |

**読解のコツ**: `ConfigRef`型がコンパイラの全設定を保持。`symbols`, `searchPaths`, `lazyPaths`等のフィールドがダンプ対象。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | commands.nim | `compiler/commands.nim` | parseCommand "dump" -> cmdDump（行496） |
| 2-2 | main.nim | `compiler/main.nim` | cmdDumpケース（行372-415） |

**主要処理フロー**:
1. **commands.nim 行496**: `"dump"` -> `cmdDump`
2. **main.nim 行372**: `of cmdDump:` でダンプ処理開始

#### Step 3: JSON形式出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | main.nim | `compiler/main.nim` | JSON形式判定（行373） |
| 3-2 | main.nim | `compiler/main.nim` | JSONオブジェクト構築（行391-405） |

**主要処理フロー**:
- **行373**: `getConfigVar(conf, "dump.format") == "json"`で形式判定
- **行374**: `wantMainModule(conf)` - プロジェクトファイル必須
- **行376-382**: シンボルとパスの配列構築
- **行384-389**: ヒント/警告設定の収集
- **行391-405**: JSONオブジェクトの構築
- **行407**: `msgWriteln`でJSON出力

#### Step 4: テキスト形式出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | main.nim | `compiler/main.nim` | テキスト形式出力（行409-415） |

**主要処理フロー**:
- **行410-411**: ヘッダー出力
- **行412**: 定義済みシンボル一覧出力
- **行413**: フッター出力
- **行415**: 検索パス一覧出力

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

```
nim.nim::handleCmdLine()
    │
    ├─ mainCommand()
    │      │
    │      └─ case cmdDump
    │             │
    │             ├─ if dump.format == "json"
    │             │      │
    │             │      ├─ wantMainModule()
    │             │      │
    │             │      ├─ definedSymbolNames() -> JArray
    │             │      │
    │             │      ├─ conf.searchPaths -> JArray
    │             │      │
    │             │      ├─ conf.lazyPaths -> JArray
    │             │      │
    │             │      ├─ hintMin..hintMax -> hints JObject
    │             │      │
    │             │      ├─ warnMin..warnMax -> warnings JObject
    │             │      │
    │             │      ├─ dumpdata JObject構築
    │             │      │
    │             │      └─ msgWriteln(JSON出力)
    │             │
    │             └─ else (テキスト形式)
    │                    │
    │                    ├─ "-- list of currently defined symbols --"
    │                    │
    │                    ├─ definedSymbolNames() 出力
    │                    │
    │                    ├─ "-- end of list --"
    │                    │
    │                    └─ conf.searchPaths 出力
    │
    └─ [genSuccessX未呼び出し - cmdDumpは対象外]
```

### データフロー図

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

nim.cfg ───▶ 設定読み込み ───▶ ConfigRef
                 │
*.nim ───▶ プロジェクト解析 ───▶ project_path, outdir等
                 │
                 ▼
          ┌─────────────────┐
          │  dump.format?   │
          └────────┬────────┘
                   │
       ┌───────────┴───────────┐
       │                       │
       ▼                       ▼
  [JSON形式]              [テキスト形式]
       │                       │
       ├─ version              ├─ "-- list of ... --"
       ├─ nimExe               ├─ シンボル一覧
       ├─ prefixdir            ├─ "-- end of list --"
       ├─ libpath              └─ 検索パス一覧
       ├─ project_path
       ├─ defined_symbols
       ├─ lib_paths
       ├─ lazyPaths
       ├─ outdir
       ├─ out
       ├─ nimcache
       ├─ hints
       └─ warnings
              │
              ▼
         標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.nim | `compiler/main.nim` | ソース | cmdDumpケース（行372-415） |
| commands.nim | `compiler/commands.nim` | ソース | parseCommand "dump" -> cmdDump（行496） |
| options.nim | `compiler/options.nim` | ソース | cmdDump定義（行174）、ConfigRef型 |
| nimconf.nim | `compiler/nimconf.nim` | ソース | cmdDump時の設定エラー無視（行309） |
