# 画面設計書 30-JSON to Lua変換

## 概要

本ドキュメントは、Lua Language Serverにおける「JSON to Lua変換」機能の画面設計書です。LSPコマンド `lua.jsonToLua` に対応し、JSON形式のテキストをLuaテーブル形式に変換します。

### 本画面の処理概要

JSON to Lua変換機能は、選択されたJSON形式のテキスト（またはJSONC形式）を解析し、等価なLuaテーブル表現に変換するコマンドです。

**業務上の目的・背景**：ゲーム開発やアプリケーション開発において、設定ファイルやAPIレスポンスなどでJSON形式のデータを扱うことが多くあります。このデータをLuaコードに組み込む際、手動で変換作業を行うのは時間がかかり、エラーが発生しやすくなります。この機能により、JSONをコピー&ペーストしてコマンドを実行するだけで、正しいLuaテーブル形式に自動変換でき、開発効率が大幅に向上します。

**画面へのアクセス方法**：この機能は、以下の方法で呼び出されます：
- JSON形式のテキストを選択した状態でコードアクションメニューから選択
- コマンドパレットから `lua.jsonToLua` を実行
- 診断結果からのクイックフィックスとして実行

**主要な操作・処理内容**：
1. コマンド `lua.jsonToLua` がトリガーされる（変換対象の範囲情報を含む）
2. 対象範囲のテキストをJSON（またはJSONC）としてパース
3. パース結果をLuaテーブル形式の文字列に変換（`util.dump`）
4. キー付きJSONの場合（`"key": {...}`）、Luaの代入形式に変換
5. `workspace/applyEdit` リクエストでエディタに適用

**画面遷移**：独立したコマンドとして動作し、特定の画面遷移はありません。処理結果は現在のエディタに直接反映されます。

**権限による表示制御**：特別な権限制御はありません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | JSONからLuaへ変換 (lua.jsonToLua) | 主機能 | JSONをLuaテーブルに変換するコマンド処理 |

## 画面種別

LSPコマンド

## URL/ルーティング

LSPコマンド: `lua.jsonToLua`
LSPメソッド: `workspace/executeCommand`

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| uri | uri | はい | 対象ドキュメントのURI |
| start | number | はい | 変換開始位置 |
| finish | number | はい | 変換終了位置 |

### 出力パラメータ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | 戻り値なし（workspace/applyEditで変更を適用） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | エディタ上でLuaテーブルに変換された結果が表示される |

## イベント仕様

### 1-JSON to Lua変換コマンド実行

1. ユーザーが `lua.jsonToLua` コマンドを実行
2. `workspace/executeCommand` ハンドラが呼び出される
3. `core/command/jsonToLua.lua` が実行される
4. 対象範囲のテキストを取得
5. JSONパターン（`[` または `{` で始まる）を抽出
6. `jsonc.decode_jsonc` でJSONをパース
7. `util.dump` でLuaテーブル形式に変換
8. キー付きの場合は代入形式に変換
9. `workspace/applyEdit` リクエストでエディタに適用

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| JSON to Lua変換コマンド実行 | - | - | データベース操作なし（ファイル編集のみ） |

## メッセージ仕様

| メッセージID | 種別 | 表示内容 | 発生条件 |
|-------------|------|----------|----------|
| COMMAND_JSON_TO_LUA_FAILED | 警告 | JSONパースエラーメッセージ | JSONのパースに失敗した場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイル状態が取得できない | 処理を終了（何もしない） |
| ファイルテキストが取得できない | 処理を終了（何もしない） |
| JSONパースに失敗 | 警告メッセージを表示して終了 |
| パース結果がnull | 警告メッセージを表示して終了 |

## 備考

- JSONC形式（コメント付きJSON）もサポート
- キー付きJSON（`"key": {...}`）の場合：
  - 有効なLua識別子の場合：`key = {...}` 形式
  - 無効な識別子の場合：`["key"] = {...}` 形式
- 配列・オブジェクトは再帰的にLuaテーブルに変換
- `json.null` は変換対象外（エラー扱い）
- 編集ラベルは "json to lua"

---

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

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

### 推奨読解順序

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

JSON→Luaの変換規則を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | jsonToLua.lua | `script/core/command/jsonToLua.lua` | 変換処理（12-53行目）を確認 |

**読解のコツ**: JSONオブジェクトはLuaテーブルに、JSON配列もLuaテーブルに変換されます。キーの扱いに注意が必要です。

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

コマンドハンドラがどのように呼び出されるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | `workspace/executeCommand` ハンドラ（977-1021行目）を確認 |

**主要処理フロー**:
1. **977行目**: `m.register 'workspace/executeCommand'` でハンドラを登録
2. **999-1001行目**: `lua.jsonToLua` の場合、jsonToLua.luaを実行

#### Step 3: コア処理を理解する

実際のJSON変換処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | jsonToLua.lua | `script/core/command/jsonToLua.lua` | 変換処理（12-54行目）を確認 |

**主要処理フロー**:
- **13-17行目**: ファイル状態とテキストの取得、エラーチェック
- **18-20行目**: 対象範囲のテキストを抽出
- **21行目**: JSONパターン（`[` または `{`）を抽出
- **22-28行目**: JSONパースとエラーハンドリング
- **30行目**: `util.dump` でLuaテーブル形式に変換
- **31-39行目**: キー付きJSONの場合の処理
- **41-53行目**: `workspace/applyEdit` で変更を適用

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

```
workspace/executeCommand (provider.lua:977-1021)
    │
    └─ 'lua.jsonToLua' (999-1001行目)
           │
           └─ core/command/jsonToLua.lua (12-54行目)
                  │
                  ├─ files.getState(uri) - ファイル状態取得
                  │
                  ├─ files.getText(uri) - テキスト取得
                  │
                  ├─ text:sub(start + 1, finish) - 範囲抽出
                  │
                  ├─ jsonStr:match '[%{%[].*' - JSONパターン抽出
                  │
                  ├─ jsonc.decode_jsonc(jsonStr) - JSONパース
                  │
                  ├─ util.dump(res) - Luaテーブル変換
                  │
                  └─ proto.awaitRequest('workspace/applyEdit', ...)
```

### データフロー図

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

{                              1. ファイル取得                  workspace/applyEdit {
  uri: '...',                  2. 範囲テキスト抽出                label: 'json to lua',
  start: 100,                  3. JSONパターン抽出                edit: {
  finish: 200                  4. JSONパース                       changes: {
}                                 jsonc.decode_jsonc()              [uri]: [
                               5. Luaテーブル変換                     {
    │                            util.dump(result)                   range: ...,
    │                          6. キー処理                           newText: '{...}'
    │                             ├─ 識別子: key = {...}             }
JSON例:                           └─ 非識別子: ["key"] = {...}      ]
{"name": "value",              7. applyEdit送信                    }
 "count": 42}                                                    }
                                                                }
    │
    ▼
Lua変換結果:
{
  name = "value",
  count = 42,
}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPコマンドハンドラの登録・処理 |
| jsonToLua.lua | `script/core/command/jsonToLua.lua` | ソース | JSON変換処理のコアロジック |
| files.lua | `script/files.lua` | ソース | ファイル状態・テキストの管理 |
| utility.lua | `script/utility.lua` | ソース | dump関数（Luaテーブル文字列化） |
| jsonc.lua | `script/jsonc.lua` | ソース | JSONC（コメント付きJSON）パーサー |
| json.lua | `script/json.lua` | ソース | JSON基本処理・null定義 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| define.lua | `script/proto/define.lua` | ソース | MessageType定義（Warning等） |
| converter.lua | `script/proto/converter.lua` | ソース | LSPプロトコル型変換 |
| language.lua | `script/language.lua` | ソース | メッセージ定義 |
