# 機能設計書 22 --eval オプション

## 概要

本ドキュメントは、CoffeeScript CLIツールの `--eval` (`-e`) オプションの機能設計を記述する。このオプションは、コマンドライン引数として渡された文字列をCoffeeScriptコードとして評価・実行する機能を提供する。

### 本機能の処理概要

`--eval` オプションは、CoffeeScriptコードを直接コマンドライン上で実行するための機能を提供する。ファイルを作成せずに短いスクリプトをワンライナーで実行したい場合に便利である。

**業務上の目的・背景**：開発やシステム管理の現場では、ファイルを作成せずに短いスクリプトを即座に実行したいケースが頻繁に発生する。`--eval` オプションにより、CoffeeScriptコードをファイルに保存することなく、コマンドラインから直接実行できる。これはシェルスクリプトとの連携、簡単な計算、データ変換などに活用される。

**機能の利用シーン**：
- 短いCoffeeScriptスニペットをコマンドラインから直接実行したい場合
- シェルスクリプト内でCoffeeScriptの処理を行いたい場合
- REPLを起動せずにワンライナーでコードを評価したい場合
- CI/CDパイプラインで簡単なスクリプトを実行したい場合

**主要な処理内容**：
1. コマンドライン引数からCoffeeScript文字列を取得する
2. compileScript関数を呼び出し、コードをコンパイル・実行する
3. `--print` オプションと組み合わせた場合、コンパイル結果を標準出力に表示する
4. 実行モード（デフォルト）では、CoffeeScript.run()でコードを即座に実行する

**関連システム・外部連携**：Node.js VM（仮想マシン）モジュール

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIオプションのため関連画面なし |

## 機能種別

コード評価 / スクリプト実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --eval / -e | boolean | No | 文字列評価モードを有効にする | オプションの有無で判定 |
| code | string | Yes（-e指定時） | 評価するCoffeeScript文字列 | 引数として渡された最初の位置引数 |

### 入力データソース

- コマンドライン引数（`opts.arguments[0]`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| execution result | any | コード実行結果（実行モードの場合） |
| compiled JS | string | コンパイルされたJavaScript（`--print` 併用時） |

### 出力先

- 標準出力（`--print` 併用時のコンパイル結果）
- プログラム実行による副作用出力

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数をパース
   └─ --eval オプションが指定されているか確認

2. 評価対象コードの取得
   └─ opts.arguments[0] からCoffeeScript文字列を取得

3. compileScript関数の呼び出し
   └─ file引数はnull、input引数に評価対象文字列を渡す

4. コンパイルオプションの構築
   └─ compileOptions関数でオプションオブジェクトを生成

5. モードに応じた処理分岐
   ├─ --print: CoffeeScript.compile() → 標準出力
   └─ 実行モード: CoffeeScript.run() → コード実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始: coffee -e 'console.log 1'] --> B[引数パース]
    B --> C{--eval 指定?}
    C -->|No| D[通常処理へ]
    C -->|Yes| E[opts.arguments#91;0#93;からコード取得]
    E --> F[compileScript null, code]
    F --> G[compileOptions作成]
    G --> H{--print 指定?}
    H -->|Yes| I[CoffeeScript.compile]
    I --> J[printLine: 標準出力へ]
    H -->|No| K{--run モード?}
    K -->|Yes| L[CoffeeScript.run]
    K -->|No| M[CoffeeScript.compile + 出力]
    J --> N[終了]
    L --> N
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | コード位置引数 | 評価対象コードは最初の位置引数から取得する | --eval指定時 |
| BR-22-02 | 暗黙のprint | --eval と --compile を併用すると暗黙的に --print が有効になる | --eval かつ --compile 指定時 |
| BR-22-03 | ファイル名null | ファイルからの入力ではないためfile引数はnullとなる | --eval指定時 |
| BR-22-04 | プリロード対応 | --require オプションで指定されたモジュールが事前にロードされる | --require 併用時 |

### 計算ロジック

特になし

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntaxError | 構文エラー | CoffeeScriptの文法エラー | エラーメッセージを標準エラー出力に表示して終了コード1 |
| ReferenceError | 参照エラー | 未定義変数の参照 | エラーメッセージを標準エラー出力に表示して終了コード1 |
| TypeError | 型エラー | 不正な型操作 | エラーメッセージを標準エラー出力に表示して終了コード1 |

### リトライ仕様

本機能はリトライ処理を行わない。エラー発生時は即座に終了する。

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

本機能はトランザクション処理を使用しない。

## パフォーマンス要件

特になし（ワンショット実行のため）

## セキュリティ考慮事項

- 信頼できないソースからのコードを評価しないこと
- `--eval` で渡されたコードはNode.jsの権限で実行される

## 備考

- `--print` オプションと併用するとコンパイル結果を標準出力に表示できる
- `--bare` オプションと併用するとトップレベル関数ラッパーなしでコンパイルできる
- `--require` オプションと併用すると、コード評価前にモジュールをプリロードできる

---

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

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

### 推奨読解順序

#### Step 1: オプション定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.coffee | `src/command.coffee` | SWITCHESの `--eval` 定義（38行目）を確認 |

**読解のコツ**: `['-e', '--eval', '...']` の形式で短縮形と長形式が定義されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | run関数（72行目〜）での--eval処理分岐 |

**主要処理フロー**:
1. **102行目**: `return compileScript null, opts.arguments[0] if opts.eval`
2. **449行目**: `o.print = !! (o.print or (o.eval or o.stdio and o.compile))` で暗黙のprint有効化

#### Step 3: コンパイル・実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command.coffee | `src/command.coffee` | compileScript関数（202行目〜）の実装 |
| 3-2 | index.coffee | `src/index.coffee` | CoffeeScript.run関数（35行目〜）の実装 |

**主要処理フロー**:
- **202行目**: compileScript関数の開始
- **214-217行目**: opts.runの場合、CoffeeScript.runを呼び出し

#### Step 4: 実行環境を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.coffee | `src/index.coffee` | CoffeeScript.eval関数（66行目〜）の実装 |

**主要処理フロー**:
- **66行目**: eval関数の開始
- **68-103行目**: VMコンテキストの構築とコード評価

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

```
exports.run (72行目)
    │
    └─ compileScript null, opts.arguments[0] (102行目)
           │
           ├─ compileOptions (203行目)
           │      └─ オプションオブジェクト構築
           │
           └─ [モード分岐]
                  ├─ opts.print → CoffeeScript.compile → printLine (231行目)
                  │
                  └─ opts.run → CoffeeScript.run (217行目)
                         │
                         └─ index.coffee: CoffeeScript.run (35行目)
                                │
                                └─ CoffeeScript.compile
                                └─ mainModule._compile
```

### データフロー図

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

コマンドライン引数
'console.log 1' ───▶ opts.arguments[0] (102行目)
                              │
                              ▼
                        compileScript (202行目)
                              │
                              ▼
                    ┌─────────┴─────────┐
                    ▼                   ▼
              [--print]           [実行モード]
                    │                   │
                    ▼                   ▼
          CoffeeScript.compile   CoffeeScript.run
                    │                   │
                    ▼                   ▼
              printLine ───▶     コード実行 ───▶ 副作用出力
              標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIメイン処理、--eval分岐処理 |
| index.coffee | `src/index.coffee` | ソース | CoffeeScript.run/eval関数の実装 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイル処理の実装 |
| optparse.coffee | `src/optparse.coffee` | ソース | コマンドライン引数パーサー |
