# magic-script-antlr

**Repository Path**: yaoqis/magic-script-antlr

## Basic Information

- **Project Name**: magic-script-antlr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# magic-script-antlr

一个使用 ANTLR 4 构建的、可嵌入 JVM 的小型动态脚本语言。项目当前版本为 `1.0.0-SNAPSHOT`，包含独立 AST、词法作用域、闭包、解释器、完整 ASM Java 8 字节码后端、`invokedynamic` 调用点、模块、受控 Java 互操作和开发工具接口。

## 已实现

- `var`、`let`、只读 `const`
- 块级词法作用域和闭包
- Lambda：`x => x + 1`、`(a, b) => { return a + b; }`
- `if/else`、`while`、`for (key, value in source)`
- `return`、`break`、`continue`
- `throw`、`try/catch/finally`
- 递归列表/Map 解构、末尾 rest 绑定
- 列表、Map 和调用参数 spread
- 支持 `${expression}` 的模板字符串及嵌套花括号
- 数字、字符串、布尔值、`null`、List 和 Map
- 算术、比较、逻辑、三元和复合赋值
- 函数调用、属性访问、索引访问和 `?.`
- 宿主函数、显式模块注册和白名单 Java 反射
- 解释器/ASM 双执行模式与差分测试
- 执行步数、调用深度、源码长度和稳定异步取消门面
- 线程安全的源码/字节码缓存和并发执行
- 类、方法、字段三级 Java 互操作授权
- ASM 运行时错误源码定位和生成类显式释放
- Lambda 编译为独立静态方法，闭包只保存显式捕获 Cell，无解释式回退
- 调用、算术、属性和索引操作使用独立 `invokedynamic` 调用点
- JVM local、Frame slot、捕获 Cell 三层变量存储策略
- 同步断点调试、步入/步过/步出、终止和局部变量快照
- 可嵌入语言服务：诊断、文档符号和关键字补全
- stdio JSON-RPC Language Server Protocol 入口
- 编译缓存、解释器和 ASM 的线程安全性能指标
- 具有 `StableApi`、`ExperimentalApi` 和 `InternalApi` 分级的 1.0 API 契约

## 环境

- JDK 8+
- Maven 3.8+
- ANTLR Tool/runtime 4.9.3

项目固定在 ANTLR 4.9.3，因为当前构建环境是 JDK 8，而 4.10.1 和 4.13.1 的已发布 Tool 都是 Java 11 字节码。若升级到新的 ANTLR 版本，构建 grammar 需要 JDK 11，但生成代码仍可配置为面向 Java 8。

## 构建与运行

```bash
./mvnw test
./mvnw package
java -jar target/magic-script-antlr-1.0.0-SNAPSHOT.jar examples/demo.ms
```

Windows 使用 `mvnw.cmd`。CI 在 JDK 8 和 JDK 11 上运行同一套 `verify`；仓库同时提供 GitHub Actions 配置和可供 Gitee Jenkins 流水线使用的 `Jenkinsfile`。

也可以嵌入 Java：

```java
MagicScriptEngine engine = MagicScriptEngine.standard();
engine.setGlobal("price", 12);
try (CompiledMagicScript script = engine.compile("return price * 2;")) {
    Object interpreted = engine.execute(script);
    Object compiled = engine.execute(script, null, ExecutionMode.BYTECODE);
}
```

## 架构

![magic-script-antlr 中文整体架构](docs/images/magic-script-architecture.png)

上图是中文详细总览，技术类名保留英文以对应源码；下方 Mermaid 图保留具体模块关系，作为可维护的架构来源。

```mermaid
flowchart TB
    JAVA["Java 嵌入应用"] --> ENGINE["MagicScriptEngine<br/>稳定 API：编译、执行、配置"]
    CLI["MagicScript CLI"] --> ENGINE
    IDE["IDE / 编辑器"] --> LSP["Language Server<br/>stdio JSON-RPC"]
    LSP --> LS["MagicScriptLanguageService<br/>诊断、符号、补全"]

    ENGINE --> CACHE["Source LRU Cache"]
    CACHE --> PARSER["ParserFacade<br/>ANTLR Lexer / Parser"]
    LS --> PARSER
    GRAMMAR["MagicScriptLexer.g4<br/>MagicScriptParser.g4"]
    GRAMMAR -. "生成" .-> PARSER
    PARSER --> TREE["ANTLR ParseTree"]
    TREE --> BUILDER["AstBuilder"]
    BUILDER --> AST["独立不可变 AST<br/>SourceSpan"]
    AST --> ANALYZER["SemanticAnalyzer"]
    ANALYZER --> RESOLUTION["Resolution<br/>Scope / Symbol / FunctionLayout / Capture"]

    RESOLUTION --> SCRIPT["CompiledMagicScript<br/>已解析、已绑定脚本"]
    RESOLUTION --> STORAGE["变量分层策略<br/>JVM local / Frame slot / Cell"]
    SCRIPT --> INTERPRETER["Interpreter<br/>语义参考实现"]
    SCRIPT --> ASM["AsmCompiler<br/>Java 8 字节码"]
    STORAGE --> INTERPRETER
    STORAGE --> ASM
    ASM --> VERIFY["CheckClassAdapter<br/>字节码校验"]
    VERIFY --> BYTECODE["BytecodeProgram<br/>invokedynamic / 静态 Lambda"]
    DEBUGGER["DebugSession<br/>断点、单步、变量快照"] -. "仅解释器模式" .-> INTERPRETER

    INTERPRETER --> RUNTIME["共享运行时语义<br/>ExecutionContext / ExecutionBudget<br/>Frame / Cell / CompiledClosure<br/>ValueOperations / DynamicCallSite<br/>HostInterop / HostAccessPolicy"]
    BYTECODE --> RUNTIME
    GLOBALS["Globals / Host Functions"] --> RUNTIME
    MODULES["Registered Modules"] --> RUNTIME
    OBJECTS["允许访问的 Java 对象"] --> RUNTIME
    RUNTIME --> RESULT["结果或带 SourceSpan 的异常"]

    ENGINE -. "缓存指标" .-> METRICS["MetricsRecorder<br/>编译、缓存、执行、失败"]
    INTERPRETER -. "执行指标" .-> METRICS
    BYTECODE -. "执行指标" .-> METRICS

    classDef entry fill:#e8f1ff,stroke:#2563eb,color:#172554
    classDef api fill:#ecfdf5,stroke:#059669,color:#064e3b
    classDef frontend fill:#fff7ed,stroke:#ea580c,color:#7c2d12
    classDef semantics fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
    classDef backend fill:#fef2f2,stroke:#dc2626,color:#7f1d1d
    classDef runtime fill:#f0fdfa,stroke:#0d9488,color:#134e4a
    classDef host fill:#f8fafc,stroke:#64748b,color:#1e293b
    classDef engineering fill:#fefce8,stroke:#ca8a04,color:#713f12

    class JAVA,CLI,IDE entry
    class ENGINE,SCRIPT,LS,LSP api
    class GRAMMAR,PARSER,TREE,BUILDER,AST frontend
    class ANALYZER,RESOLUTION,STORAGE semantics
    class INTERPRETER,ASM,VERIFY,BYTECODE,DEBUGGER backend
    class RUNTIME runtime
    class GLOBALS,MODULES,OBJECTS,RESULT host
    class CACHE,METRICS engineering
```

ANTLR 生成的 `ParserRuleContext` 只存在于解析阶段，`AstBuilder` 之后全部模块只依赖独立 AST。`SemanticAnalyzer` 统一完成作用域、符号和闭包捕获分析，生成的 `Resolution` 同时驱动解释器和 ASM 后端，便于进行全语法差分测试。

解释器是语义参考实现；ASM 后端生成并校验 Java 8 class，将 Lambda 编译成独立静态方法，并通过 `invokedynamic` 完成动态调用和运算。两种模式共享 `ExecutionContext`、动态值语义、宿主访问策略和执行预算。调试器挂接解释器语句边界，LSP 和语言服务复用同一套解析及语义分析前端。

## 文档

- [快速开始](docs/GETTING_STARTED.md)
- [嵌入与运行时](docs/EMBEDDING.md)
- [语言规范](docs/LANGUAGE_SPEC.md)
- [调试器、语言服务和 LSP](docs/TOOLING.md)
- [架构](docs/ARCHITECTURE.md)
- [API 兼容策略](docs/API_COMPATIBILITY.md)
- [测试策略与用例目录](docs/TESTING.md)
- [发布流程](docs/RELEASING.md)

## 本机基准

```bash
java -cp target/magic-script-antlr-1.0.0-SNAPSHOT.jar io.github.magicscript.cli.BenchmarkCli 10000
```

该入口先预热，再分别测量解释器和字节码模式；它用于同一机器上的回归比较，不作为跨机器性能承诺。

## 安全边界

Java 反射默认全部拒绝。`allowHostClass` 放行一个普通类的全部公开成员；更小权限的嵌入场景应使用 `allowHostMethod(type, name)` 和 `allowHostField(type, name)`。JavaBean 属性读写分别校验真实的 getter/setter 方法名，注册模块不会隐式开放反射。反射、进程、类加载器、线程和 JDK 内部类型不能被授权。生产环境仍应暴露窄接口对象，并设置执行步数、调用深度和源码长度限制。

## 兼容性

1.x 在 Java 8 及以上版本运行。标记为 `StableApi` 的类型和成员遵循语义化版本兼容承诺；实验性入口、内部包、AST/语义模型及生成字节码不在二进制兼容范围内。详细规则见 [API 兼容策略](docs/API_COMPATIBILITY.md)。