# 画面設計書 7-nim e（スクリプト実行）

## 概要

本ドキュメントは、NimScript（.nims）ファイルを実行するサブコマンド`nim e`のCLIインターフェース設計書です。

### 本画面の処理概要

`nim e`コマンドは、NimScript（.nimsファイル）をコンパイルせずに直接実行するサブコマンドです。NimScriptはNimのサブセットで、コンパイル時の設定やビルドスクリプト、軽量なスクリプティングに使用されます。内部的にはNimの仮想マシン（VM）上で解釈実行されます。

**業務上の目的・背景**：ビルド設定（config.nims）やタスク自動化のためのスクリプト言語として使用します。コンパイルのオーバーヘッドなしにNimの文法でスクリプトを実行でき、nimble.packageやプロジェクト設定で広く使われています。

**画面へのアクセス方法**：ターミナルから`nim e <filename.nims>`を実行します。

**主要な操作・処理内容**：
1. NimScriptファイルの読み込み
2. 字句解析・構文解析
3. NimScript用のシンボル定義
4. VM（仮想マシン）のセットアップ
5. スクリプトの解釈実行
6. 結果の出力

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 仮想マシン（VM） | 主機能 | NimScriptの実行を行うインタプリタ処理 |

## 画面種別

CLIサブコマンド（スクリプト実行）

## URL/ルーティング

```
nim e [options] <scriptfile.nims>
```

オプション例：
- `nim e script.nims` - スクリプト実行
- `nim e -d:debug script.nims` - デバッグモードで実行
- `nim e config.nims` - 設定スクリプト実行

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| scriptfile | string | 入力 | はい | 実行対象のNimScriptファイル |
| -d:NAME | string | 入力 | いいえ | 条件コンパイルシンボル定義 |
| 標準出力 | text | 出力 | - | スクリプト出力 |
| 標準エラー | text | 出力 | - | エラー出力 |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| スクリプト出力 | echo等の出力 | デフォルト |
| エラーメッセージ | 実行時エラー | エラー発生時 |

## イベント仕様

### 1-スクリプト実行開始

`main.nim`で`cmdNimscript`として処理されます：

1. スクリプトファイルの存在確認
2. 設定の読み込み（loadConfigs内で処理）

### 2-VM初期化

`scriptconfig.nim`の`setupVM`関数（行34-194）でVMをセットアップ：
- `newCtx`でVM コンテキスト作成
- `emRepl`モードに設定
- コールバック関数を登録（ファイル操作、環境変数等）

### 3-コールバック登録

NimScript固有の機能をVMに登録：
- **ファイル操作**: listFilesImpl, listDirsImpl, removeDir, removeFile, createDir等
- **環境変数**: getEnv, existsEnv, putEnv, delEnv
- **プロジェクト情報**: projectName, projectDir, projectPath, thisDir
- **設定操作**: put, get, exists, switch, setCommand
- **外部実行**: rawExec（コマンド実行）

### 4-スクリプト実行

`runNimScript`関数（行196-259）でスクリプトを実行：
- `defineSymbol("nimscript")`, `defineSymbol("nimconfig")`
- `EvalPass`パイプラインでコンパイル・実行
- 実行後にシンボルを解除

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

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

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

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| 実行 | *.nims | READ | NimScriptファイル読み込み |
| スクリプト | 任意 | READ/WRITE | スクリプト内でのファイル操作 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| エラー | "NimScript file does not exist: $1" | ファイル不在時 |
| エラー | VM実行時エラー | スクリプトエラー時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| ファイル不在 | "NimScript file does not exist: $1" | エラー終了 |
| 構文エラー | パースエラーメッセージ | エラー終了 |
| 実行時エラー | VM実行時エラー | エラー終了 |

## 備考

- NimScriptはNimの安全なサブセット
- ポインタ操作やFFI呼び出しは不可
- `when defined(nimscript)`で条件分岐可能
- config.nimsはプロジェクト設定に自動使用
- nimble.nimsはパッケージ定義に使用
- `--check`モード時はファイル操作がスキップされる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | vmdef.nim | `compiler/vmdef.nim` | PEvalContext型（VMコンテキスト） |
| 1-2 | vm.nim | `compiler/vm.nim` | VM実行エンジン |

**読解のコツ**: PEvalContextはVMの実行コンテキストを保持し、registerCallbackでNimScript固有機能を追加。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.nim | `compiler/main.nim` | cmdNimscriptケース（行441-445） |
| 2-2 | commands.nim | `compiler/commands.nim` | parseCommand "e" -> cmdNimscript（行483） |

**主要処理フロー**:
1. **main.nim 行441-445**: ファイル存在確認後、loadConfigsで処理
2. **commands.nim 行483**: `"e"` -> `cmdNimscript`

#### Step 3: VMセットアップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | scriptconfig.nim | `compiler/scriptconfig.nim` | setupVM関数（行34-194） |
| 3-2 | scriptconfig.nim | `compiler/scriptconfig.nim` | runNimScript関数（行196-259） |

**主要処理フロー**:
- **行34-38**: `setupVM`でコンテキスト作成、`emRepl`モード設定
- **行46-194**: 各種コールバック登録（cbconf, cbos, cbexcテンプレート使用）
- **行196-259**: `runNimScript`でスクリプト実行

#### Step 4: コールバック実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | scriptconfig.nim | `compiler/scriptconfig.nim` | cbconf/cbos/cbexcテンプレート（行46-61） |

**主要処理フロー**:
- **行46-49**: `cbconf`テンプレート - 設定関連コールバック
- **行51-58**: `cbexc`テンプレート - 例外処理付きコールバック
- **行60-61**: `cbos`テンプレート - OSError例外付きコールバック

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

```
main.nim::mainCommand()
    │
    └─ case cmdNimscript
           │
           └─ (loadConfigs内で処理)
                  │
                  └─ scriptconfig.runNimScript()
                         │
                         ├─ setupVM()
                         │      │
                         │      ├─ newCtx() [VMコンテキスト作成]
                         │      │
                         │      └─ registerCallback() [各種コールバック]
                         │             ├─ ファイル操作
                         │             ├─ 環境変数
                         │             ├─ プロジェクト情報
                         │             └─ 設定操作
                         │
                         ├─ defineSymbol("nimscript")
                         │
                         ├─ defineSymbol("nimconfig")
                         │
                         ├─ setPipeLinePass(EvalPass)
                         │
                         ├─ compilePipelineSystemModule()
                         │
                         └─ processPipelineModule()
                                │
                                └─ VM解釈実行
```

### データフロー図

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

*.nims ───▶ レキサー/パーサー ───▶ AST
                 │
                 ▼
AST ───▶ setupVM() ───▶ VMコンテキスト + コールバック
                 │
                 ▼
VMコンテキスト ───▶ EvalPass ───▶ 解釈実行
                 │
                 ├─ echo → 標準出力
                 │
                 ├─ exec → 外部コマンド実行
                 │
                 └─ switch → コンパイラ設定変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| scriptconfig.nim | `compiler/scriptconfig.nim` | ソース | setupVM、runNimScript関数 |
| vm.nim | `compiler/vm.nim` | ソース | VM実行エンジン |
| vmdef.nim | `compiler/vmdef.nim` | ソース | VM型定義（PEvalContext等） |
| main.nim | `compiler/main.nim` | ソース | cmdNimscriptケース |
| commands.nim | `compiler/commands.nim` | ソース | parseCommand "e" |
