jsonpiler 0.9.1

# Jsonpiler — JSON 構文プログラミング言語

[英語(English)](https://github.com/HAL-G1THuB/jsonpiler/blob/main/README-ja.md)

**Jsonpiler** は **JSON** と **JSPL (Jsonpiler Structured Programming Language)** を文法として使うプログラミング言語のコンパイラ兼実行環境です。
JSON で書かれたプログラムを **x86_64 Windows PE** 形式の機械語に変換し、リンクして実行します。
Jsonpiler は、その中間表現（IR）から Windows 用 PE を出力することに特化した **自前実装のアセンブラとリンカ** を内蔵しています。

- [GitHub](https://github.com/HAL-G1THuB/jsonpiler)
- [Crates.io](https://crates.io/crates/jsonpiler)
- [AI 生成ドキュメント: ![badge](https://deepwiki.com/badge.svg)](https://deepwiki.com/HAL-G1THuB/jsonpiler)
- [VSCode 拡張機能](https://marketplace.visualstudio.com/items?itemName=H4LVS.jsplsyntax)

> 🚨 **Windowsのみ(x64)** — Jsonpilerは64ビットWindowsを対象に、
  機械語のPE(Portable Executable)実行ファイルを生成します。

## GUI

Jsonpilerに GUI をサポートする関数が追加されました。

![Jsonpilerで描画されたジュリア集合・ピンポンゲーム](./gui.jpeg)

[Jsonpilerで描画されたマンデルブロ集合のズーム](https://youtu.be/M8wEPkHmYdE)

[ジュリア集合をGUIで描くプログラムのソースコード](https://github.com/HAL-G1THuB/jsonpiler/blob/main/examples/jspl/gui_julia_mouse.jspl)

[マンデルブロ集合をGUIで描くプログラムのソースコード](https://github.com/HAL-G1THuB/jsonpiler/blob/main/examples/jspl/gui_mandelbrot_zoom.jspl)

## 更新情報

### 0.9.1

- 修正
  - `Str`に対する`!=`が正しく機能しない問題

詳細は **[CHANGELOG](https://github.com/HAL-G1THuB/jsonpiler/blob/main/CHANGELOG-ja.md)** を参照してください。

## 必要条件

外部ツールやライブラリは不要です。

**以下のシステム DLL が `C:\Windows\System32\` に存在する必要があります:**

- `gdi32.dll`(`GUI`など)
- `kernel32.dll`(必須)
- `user32.dll`(`message`, `GUI`など)

標準的な Windows 環境ではすでに存在します。

## 拡張機能

VSCodeでJSPLを快適に記述するための拡張機能が利用可能です。

- **自動フォーマット**: コードを整形し、読みやすく保ちます。
- **構文ハイライト**: JSPL のキーワードや演算子を色分けします。
- **実行ボタン**: エディタ右上のボタンからワンクリックでプログラムを実行できます。
- **LSP サポート**: リアルタイムでのエラー診断やフォーマット機能を提供します。

[VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=H4LVS.jsplsyntax)

## インストールと実行

### JSPLを実行する場合

- [VSCode 拡張機能](https://marketplace.visualstudio.com/items?itemName=H4LVS.jsplsyntax)をインストールします。
- `.jspl` ファイルを作成し、エディタ右上の `Run JSPL` ボタンをクリックすることで実行できます。

### 直接実行ファイルを動かす場合

#### Githubリポジトリから

```bash
git clone "https://github.com/HAL-G1THub/jsonpiler.git"
cd "jsonpiler/extension/bin"
jsonpiler.exe
```

#### cargoから

```bash
cargo install jsonpiler
cd "<ホームディレクトリ>/.cargo/bin"
jsonpiler.exe
```

#### 実行

```bash
# JSON | JSPL プログラムをコンパイルして実行
jsonpiler "<input.json | input.jspl>" "[生成exeへの引数]"
```

- `<input.json | input.jspl>` のファイルエンコーディングは
    UTF-8 である必要があります。
- 追加の引数は生成された実行ファイルに渡されます。

## 言語仕様・関数リファレンス

[**言語仕様 (Markdown)**](https://github.com/HAL-G1THuB/jsonpiler/blob/main/docs/specification-ja.md)
[**関数リファレンス (Markdown)**](https://github.com/HAL-G1THuB/jsonpiler/blob/main/docs/functions/README.md)

## 例

準備済みサンプルは [examples/](https://github.com/HAL-G1THuB/jsonpiler/blob/main/examples) にあります。

コード例:

```json
{
  "=": [{ "$": "a" }, "title"],
  "message": [{ "$": "a" }, "345"],
  "+": [1, 2, 3]
}
```

```jspl
a = "title"
message(a, "345")
1 + 2 + 3
```

### 実行順序

- Jsonpiler プログラムは単一の JSON オブジェクトで構成され、キーは **順次評価** されます。
- `"="` は文字列 `"title"` を変数 `a` に代入します。
- `"message"` は `a` の値をタイトルとし、
  `"345"` をテキストとしたメッセージボックスを表示します。
- `"+"` は `1 + 2 + 3` を計算し、結果は **6** です。

プログラムの **最終式の値** はプロセスの **終了コード** になります。

Cargo で実行すると次のように表示される場合があります:

```text
error: process didn't exit successfully: `jsonpiler.exe test.json` (exit code: 6)
```

これは Jsonpiler のエラーではなく、想定された動作です。

## JSPL

Jsonpiler は、独自言語である**JSPL (Jsonpiler Structured Programming Language)** をコンパイルできます。
詳細は上記の言語仕様に記載してあります。
上記のサンプルコードを JSPL で記述した例:

```jspl
a = "title"
message($a, "345")
+(1, 2, 3)
```

## エラー・警告の例

**入力:**

```json
{ "message": ["title", { "$": "does_not_exist" }] }
```

```jspl
message("title", does_not_exist)
```

**出力:**

```text
╭- CompilationError ----------
| Undefined variable:
|   does_not_exist
|-----------------------------
| input.jspl:1:18
|-----------------------------
| message("title", does_not_exist)
|                  ^^^^^^^^^^^^^^
╰-----------------------------
```

## 処理フロー概要

```mermaid
graph TD
  subgraph 読み込み
    A["file.json\n{ &quot;+&quot;: [1, 2] }"] --> B{Jsonpiler}
  end
  subgraph 解析
    B --o C["AST\nJson::Object([
      Json::Str(&quot;+&quot;),
      Json::Array([
        Json::Int(1),
        Json::Int(2)
      ])])"]
    B --x PError[[ParseError]]
  end
  subgraph コンパイル
    C --x CError[[CompileError]]
    C --o E["アセンブラ IR
    ...Inst::MovQQ(Rax, 1),
    Inst::MovQQ(Rcx, 2),
    Inst::AddRR(Rax, Rcx)..."]
  end
  subgraph 評価
    C --o D["Json::Int(一時値)"]
    C --x EError[[TypeError or ArityError]]
    D -->|終了コード検出| E
  end
  subgraph アセンブル
    E --o G["バイナリ機械語
    [...0x48, 0x89, 0o201...]"]
    E --x AError[[InternalError]]
  end
  subgraph リンク
    G --o F["PE形式 (Portable Executable)"]
    G --x LError[[InternalError]]
  end
  subgraph 書き込み
    F --> H[file.exe]
  end
  subgraph 実行
    H --> Exec[(Execute)]
  end
  subgraph DLL
    S[C:\\Windows\\System32\\]
    KERNEL32[kernel32.dll]
    USER32[user32.dll]
    S --> KERNEL32 --> F
    S --> USER32 --> F
  end
```

## 注意事項

- 出力は Windows x64 向けのネイティブ **PE 実行ファイル** です。
- Cargo 実行時に 0 以外の終了コードが返る場合は、プログラムの最終値によるものです。

## ライセンス

ライセンスはリポジトリで確認してください。

## 貢献について

Issues や PR は歓迎します。バグを発見した場合は、以下の情報を含めてください。

> 🚨 Windows x64 であることを確認してください。

- JSON プログラム（可能であれば最小限の再現例）
- Jsonpiler のバージョン