# 画面設計書 41-nim --help

## 概要

本ドキュメントは、Nimコンパイラの`nim --help`コマンドによるヘルプ表示画面の設計書である。

### 本画面の処理概要

この画面は、Nimコンパイラの使用方法を表示するCLIヘルプ画面である。ユーザーがコマンドラインでNimコンパイラの使い方を確認するために使用する。

**業務上の目的・背景**：Nimコンパイラは多機能なコンパイラであり、多数のコマンドとオプションを持つ。開発者が適切なコマンドやオプションを選択し、効率的にコンパイル作業を行うためには、包括的かつわかりやすいヘルプ情報へのアクセスが不可欠である。この画面は、新規ユーザーのオンボーディングから経験者のオプション確認まで、幅広いユースケースに対応する。

**画面へのアクセス方法**：
- `nim --help` または `nim -h` コマンドを実行
- 引数なしで `nim` を実行した場合も同様のヘルプが表示される

**主要な操作・処理内容**：
1. コマンドライン引数の解析（`--help` または `-h` の検出）
2. ヘルプメッセージの構築（バージョン情報、コマンド一覧、オプション一覧）
3. 標準出力へのヘルプメッセージの表示
4. 終了コード0でのプログラム終了

**画面遷移**：
- この画面へ遷移：コマンドラインから直接アクセス
- この画面から遷移：なし（ヘルプ表示後にプログラム終了）

**権限による表示制御**：なし（すべてのユーザーが同一のヘルプを閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Nimコンパイラ本体 | 主機能 | nimコマンドのヘルプ表示処理 |

## 画面種別

ヘルプ表示（情報出力）

## URL/ルーティング

```
nim --help
nim -h
nim (引数なし)
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| --help | フラグ | - | ヘルプ表示を要求するオプション |
| -h | フラグ | - | ヘルプ表示を要求するオプション（短縮形） |

### 出力項目

| 項目名 | 説明 |
|--------|------|
| バージョン情報 | Nimコンパイラのバージョン、プラットフォーム情報、コンパイル日時 |
| Usage | 基本的な使用法パターン |
| Command | 利用可能なコマンド一覧（compile, r, doc等） |
| Arguments | 引数の説明 |
| Options | 利用可能なオプション一覧（-p, -d, -f等） |

## 表示項目

### ヘルプメッセージ構成

```
Nim Compiler Version X.X.X [OS: CPU]
Compiled at YYYY-MM-DD
Copyright (c) 2006-YYYY by Andreas Rumpf

    nim command [options] [projectfile] [arguments]

Command:
  compile, c              compile project with default code generator (C)
  r                       compile to $nimcache/projname, run with `arguments`
  doc                     generate the documentation for inputfile

Arguments:
  arguments are passed to the program being run (if --run option is selected)

Options:
  -p, --path:PATH           add path to search paths
  -d, --define:SYMBOL(:VAL) define a conditional symbol
  -u, --undef:SYMBOL        undefine a conditional symbol
  -f, --forceBuild:on|off   force rebuilding of all modules
  --stackTrace:on|off       turn stack tracing on|off
  --lineTrace:on|off        turn line tracing on|off
  --threads:on|off          turn support for multi-threading on|off
  -x, --checks:on|off       turn all runtime checks on|off
  -a, --assertions:on|off   turn assertions on|off
  --opt:none|speed|size     optimize not at all or for speed|size
  --debugger:native         use native debugger (gdb)
  --app:console|gui|lib|staticlib
                            generate a console app|GUI app|DLL|static library
  -r, --run                 run the compiled program with given arguments
  --eval:cmd                evaluate nim code directly
  --fullhelp                show all command line switches
  -h, --help                show this help
  -v, --version             show detailed version information

Note, single letter options that take an argument require a colon. E.g. -p:PATH.
```

## イベント仕様

### 1-ヘルプオプション検出

**トリガー**: コマンドライン引数に`--help`または`-h`が指定された場合

**処理フロー**:
1. `processSwitch`関数でオプションを解析
2. `helpOnError`関数を呼び出し
3. `getCommandLineDesc`関数でヘルプメッセージを構築
4. `msgWriteln`関数で標準出力に出力
5. `msgQuit(0)`で正常終了

### 2-引数なし実行

**トリガー**: `nim`コマンドを引数なしで実行

**処理フロー**:
1. `handleCmdLine`関数で引数数をチェック
2. `paramCount() == 0`の場合、`writeCommandLineUsage`を呼び出し
3. ヘルプメッセージを表示して正常終了

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

該当なし（データベース操作を行わない画面）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| - | 情報 | ヘルプメッセージ全文 | --helpまたは-hオプション指定時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|---------|
| 不正なオプション指定 | エラーメッセージを表示し、ヘルプを案内 |

## 備考

- ヘルプメッセージの詳細版は`--fullhelp`オプションで表示可能
- 高度なオプションは`--advanced`オプションで表示可能
- ヘルプメッセージの内容は`doc/basicopt.txt`ファイルから読み込まれる

---

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

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

### 推奨読解順序

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

まず、コンパイラの設定情報を管理するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.nim | `compiler/options.nim` | ConfigRef型の定義、コンパイラオプションの管理方法 |
| 1-2 | msgs.nim | `compiler/msgs.nim` | メッセージ出力関連の型と関数 |

**読解のコツ**: ConfigRefはコンパイラ全体で共有される設定オブジェクト。targetフィールドにOS/CPU情報が格納されている。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nim.nim | `compiler/nim.nim` | コンパイラのエントリーポイント |

**主要処理フロー**:
1. **行98-106**: `handleCmdLine`関数 - コマンドライン処理の起点
2. **行104-106**: `paramCount() == 0`のチェックとヘルプ表示

#### Step 3: コマンドライン解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | commands.nim | `compiler/commands.nim` | オプション解析とヘルプ表示の実装 |

**主要処理フロー**:
- **行50-52**: HelpMessage定数 - バージョン情報のテンプレート
- **行61-62**: Usage, AdvancedUsage定数 - ヘルプテキストの読み込み
- **行64-67**: `getCommandLineDesc`関数 - ヘルプメッセージの構築
- **行69-72**: `helpOnError`関数 - ヘルプ表示とプログラム終了
- **行110-111**: `writeCommandLineUsage`関数 - 使用法の出力
- **行1000-1002**: `processSwitch`内の"help", "h"ケース処理

#### Step 4: メッセージ出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | msgs.nim | `compiler/msgs.nim` | msgWriteln, msgQuit関数の実装 |

**主要処理フロー**:
- `msgWriteln`: 標準出力へのメッセージ出力
- `msgQuit`: 指定した終了コードでプログラム終了

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

```
nim (エントリーポイント)
    │
    ├─ handleCmdLine (compiler/nim.nim:98)
    │      │
    │      ├─ paramCount() == 0 チェック
    │      │      └─ writeCommandLineUsage (compiler/commands.nim:110)
    │      │              └─ getCommandLineDesc
    │      │                      └─ msgWriteln
    │      │
    │      └─ processCmdLine → processSwitch
    │              └─ "help", "h" ケース
    │                      └─ helpOnError (compiler/commands.nim:69)
    │                              ├─ getCommandLineDesc
    │                              ├─ msgWriteln
    │                              └─ msgQuit(0)
```

### データフロー図

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

コマンドライン引数 ───▶ parseopt.initOptParser ───▶ OptParser
        │
        ▼
    引数解析 ───────────▶ processSwitch ───────────▶ オプション判定
        │
        ▼
 --help/-h 検出 ───────▶ helpOnError ─────────────▶ stdout
        │                    │
        ▼                    ▼
 引数なし検出 ─────────▶ writeCommandLineUsage ───▶ stdout
                             │
                             ▼
                         msgQuit(0) ──────────────▶ プロセス終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nim.nim | `compiler/nim.nim` | ソース | コンパイラのメインエントリーポイント |
| commands.nim | `compiler/commands.nim` | ソース | コマンドライン引数の解析とヘルプ表示 |
| options.nim | `compiler/options.nim` | ソース | コンパイラ設定の管理 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力機能 |
| cmdlinehelper.nim | `compiler/cmdlinehelper.nim` | ソース | コマンドライン処理のヘルパー関数 |
| basicopt.txt | `doc/basicopt.txt` | テキスト | 基本ヘルプメッセージのテンプレート |
| advopt.txt | `doc/advopt.txt` | テキスト | 高度なヘルプメッセージのテンプレート |
| nversion.nim | `compiler/nversion.nim` | ソース | バージョン情報の定義 |
