# QuantoScript
**一种小巧、易读且具备双执行引擎的脚本语言。**
动态类型 · `try`/`oops` 异常 · 具有共享标识的类 · 包含树遍历解释器*和*字节码 VM · 可选的 native-C 编译器。
[](https://github.com/PySudo/QuantoScript/actions/workflows/ci.yml)
[](CHANGELOG.md)
[](src/quanto.c)
[](LICENSE)
[](#building-from-source)
[文档](DOCS.md) · [示例](examples/) · [更新日志](CHANGELOG.md) · [贡献指南](CONTRIBUTING.md)
## 目录
- [为什么选择 QuantoScript？](#why-quantoscript)
- [安装](#installation)
- [快速开始](#quick-start)
- [语言漫游](#language-tour)
- [执行引擎](#execution-engines)
- [编译后的字节码 (`.qvm`)](#compiled-bytecode-qvm)
- [原生编译器](#native-compiler)
- [标准库](#standard-library)
- [命令行界面](#command-line-interface)
- [包管理器](#package-manager)
- [从源码构建](#building-from-source)
- [项目结构](#project-structure)
- [已知限制](#known-limitations)
- [路线图](#roadmap)
- [贡献](#contributing)
- [许可证](#license)
## 为什么选择 QuantoScript？
QuantoScript 是一种小巧、可嵌入的脚本语言，专为可读性和简洁性而设计——想象一下 Python 的清晰度，加上更简单的、基于大括号的语法。它附带了两个可互换的执行后端（用于快速迭代的树遍历解释器和用于高性能的字节码 VM），以及一个可选的 native-C 编译器，用于计算密集型的数字代码。
| | |
|---|---|
| **大括号，而非缩进** | 代码块由 `{ }` 界定——没有强制性的空格。 |
| **友好的关键字** | 使用 `maybe` 代替 `elif`，`oops` 代替 `except`。 |
| **从 1 开始的索引** | 列表和字符串从索引 `1` 开始。 |
| **共享对象标识** | 类实例是引用，而不是副本。 |
| **双引擎** | 同一个程序可以在解释器或字节码 VM 上运行，并且输出完全一致。 |
| **原生快速通道** | 算术密集型代码可以编译为 C，实现约 10 倍的加速。 |
| **单文件核心** | 整个语言是一个 C99 合并文件——易于嵌入和进行 vendor。 |
## 安装
获取 QuantoScript 最快的方式是使用单行安装程序。它会下载一个预编译的、独立的二进制文件（内置了 OpenSSL——无需安装任何依赖），将其放置在 `~/.quanto` 目录下，并将其添加到您的 `PATH` 中。不需要编译器，也不需要 `sudo` 权限。
### macOS / Linux
```
curl -fsSL https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.sh | sh
```
### Windows (PowerShell)
```
irm https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.ps1 | iex
```
然后打开一个新的终端并运行 `qs --help`。
安装程序选项
**macOS / Linux** (`install.sh`)
```
# 安装特定版本
curl -fsSL https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.sh | sh -s -- --version 1.0.0
# 自定义安装路径 (默认: ~/.quanto)
QUANTO_INSTALL="$HOME/.local" curl -fsSL .../install.sh | sh
# 不修改你的 shell profile
NO_MODIFY_PATH=1 curl -fsSL .../install.sh | sh
# 卸载
curl -fsSL https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.sh | sh -s -- --uninstall
```
**Windows** (`install.ps1`)
```
# 安装特定版本
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.ps1))) -Version 1.0.0
# 卸载
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/PySudo/QuantoScript/main/install.ps1))) -Uninstall
```
想自己构建？请参阅[从源码构建](#building-from-source)。
## 快速开始
已经安装好了？直接跳到 Hello World。否则，请使用 `make` 构建解释器（有关 OpenSSL 的说明，请参阅[从源码构建](#building-from-source)）。
```
qs examples/full_tour.qs # run a script
qs # or drop into the REPL
```
**Hello, World!**
```
print("Hello, World!")
func greet(name) {
return "Hello, " + name + "!"
}
print(greet("QuantoScript"))
```
```
qs hello.qs # tree-walk interpreter
qs vm hello.qs # bytecode VM (identical output)
```
## 语言漫游
### 变量与类型
```
x = 42 # integer
pi = 3.14 # float
name = "QS" # string
flag = true # boolean
nothing = null # null
items = [1, 2, 3] # list
user = {"name": "QS"} # map
```
### 函数与 Lambda
```
func add(a, b) {
return a + b
}
print(add(3, 4)) # 7
double = fn(x) -> x * 2 # lambda expression
print(double(5)) # 10
```
### 控制流
```
if x > 10 {
print("big")
} maybe x > 5 { # "maybe" == "else if"
print("medium")
} else {
print("small")
}
repeat 5 { i = i + 1 } # counted loop
while x < 100 { x = x * 2 } # conditional loop
```
### 异常处理 — `try` / `oops`
```
func safe_div(a, b) {
if b == 0 {
oops("division by zero") # raise
}
return a / b
}
try {
print(safe_div(10, 0))
} oops e { # catch, binding the error to `e`
print("caught: " + e)
}
```
### 具有共享标识的类
```
class Person {
init(name) {
self.name = name
}
greet() {
print("Hi, I'm " + self.name)
}
}
p = Person("Alice")
p.greet() # Hi, I'm Alice
c = p # c and p reference the SAME object
c.name = "Bob"
p.greet() # Hi, I'm Bob
```
### 集合
```
nums = [3, 1, 4, 1, 5]
print(len(nums)) # 5
nums.push(9)
print(nums.contains(4)) # true
user = {"name": "QS", "version": 1}
print(user["name"]) # QS
print(user.keys()) # [name, version]
```
**内置方法**
| 类型 | 方法 |
|------|---------|
| String | `upper` · `lower` · `title` · `len` · `contains` · `replace` · `startsWith` · `endsWith` · `split` |
| List | `len` · `push` / `append` · `pop` · `contains` · `index` · `remove` |
| Map | `keys` · `values` · `items` · `has` · `remove` · `len` |
有关完整的语言参考，请参阅 [DOCS.md](DOCS.md)。
## 执行引擎
相同的源码可以在任何一个后端上运行，并产生相同的输出。
| 引擎 | 命令 | 最适用于 |
|--------|---------|----------|
| 树遍历解释器 | `qs program.qs` | 开发、调试、快速脚本 |
| 字节码 VM | `qs vm program.qs` | 更好的运行时性能 |
| 原生 C 编译器 | `qs native program.qs` | 对算术密集型代码实现约 10 倍加速 |
## 编译后的字节码 (`.qvm`)
将 QuantoScript 编译为稳定的二进制字节码格式，以实现更快的启动和分发速度，而无需发布源码。
```
qs build program.qs # -> program.qvm
qs build program.qs -o custom.qvm # custom output path
qs vm program.qvm # run compiled bytecode
qs vm --dump-bytecode program.qs # disassemble for debugging
```
`.qvm` 格式 (**version 4**) 包含 magic-header 检查、版本验证、CRC32 源码校验和，以及对格式错误文件的全面处理。有关完整规范，请参阅 [docs/QVM_FORMAT.md](docs/QVM_FORMAT.md)。
## 原生编译器
对于算术密集型工作负载，QuantoScript 可以生成 C 代码并将其编译为原生二进制文件：
```
qs native program.qs # emit a_native.c
gcc -O2 a_native.c -o program_native
./program_native
```
**支持：** 整数算术、`if`/`else`、`while`、`repeat`、变量赋值、`print`。
**不支持：** 函数、字符串、列表、映射、闭包、类、异常。
## 标准库
使用 `from "
" import ` 导入模块。公共模块位于 `stdlib/` 中；内部运行时钩子（`sys_*`）保持隐藏。
```
User code → stdlib modules → native runtime → OS
```
```
from "stdlib/http.qs" import get, post
from "stdlib/json.qs" import parse_json, to_json
from "stdlib/os.qs" import run, capture, cwd, chdir, exists
from "stdlib/fs.qs" import read, write, list_dir
from "stdlib/text.qs" import lower, upper, split
from "stdlib/time.qs" import now, localtime
from "stdlib/log.qs" import log_info, log_error
from "stdlib/websocket.qs" import connect, send, recv, close
```
**示例**
```
# HTTP
from "stdlib/http.qs" import get
resp = get("https://httpbin.org/get")
print(resp)
# JSON
from "stdlib/json.qs" import parse_json
data = parse_json("{\"key\": \"value\"}")
# 进程执行
from "stdlib/os.qs" import run, capture, exists
run("echo Hello") # returns exit code
version = capture("git --version") # returns stdout
print(exists("gcc")) # true / false
```
| 模块 | 用途 |
|--------|---------|
| `core.qs` | 核心辅助工具和断言 |
| `math.qs` | 数值工具 |
| `text.qs` | 字符串处理 |
| `fs.qs` | 文件系统操作 |
| `os.qs` | 进程执行与工作目录 |
| `http.qs` | HTTP 客户端 (`get`, `post`, `put`, `delete`, `patch`) |
| `net.qs` | 底层网络 |
| `websocket.qs` | WebSocket 客户端 |
| `json.qs` | JSON 解析 / 序列化 |
| `time.qs` | 时间与时钟操作 |
| `log.qs` | 结构化日志 |
| `random.qs` | 伪随机数 |
| `async.qs` | 任务队列 *（实验性功能——请参阅 [已知限制](#known-limitations)）* |
在运行时，stdlib 模块通过 `QUANTO_HOME` 环境变量进行解析。运行 `qs home` 可打印配置的路径。有关完整的架构详情，请参阅 [docs/LANGUAGE_ARCHITECTURE_AUDIT.md](docs/LANGUAGE_ARCHITECTURE_AUDIT.md)。
## 命令行界面
```
qs interactive REPL
qs run with the tree-walk interpreter
qs run run with the bytecode VM
qs vm run with the bytecode VM (alias for run)
qs build [-o out.qvm] compile to .qvm bytecode
qs native emit native C (a_native.c)
qs compile [out] compile to a native binary
qs init scaffold a new project
qs check validate syntax without executing
qs fmt format source code
qs lint report common mistakes
qs doc generate documentation from comments
qs profile profile function calls
qs test [directory] run *_test.qs files
qs install install a package
qs list list installed packages
qs remove remove a package
qs home print the QUANTO_HOME directory
qs version print the version
```
**标志**
```
--dump-bytecode print compiled bytecode to stderr
--trace print a per-instruction VM trace
--sandbox [path] restrict file access to the given path
```
## 包管理器
QuantoScript 具有内置的、基于 Git 的包管理器。包是从 GitHub 克隆到本地的 `packages/` 目录中的，并且它们的 `quanto.json` 依赖项会被递归解析。
```
qs install https://github.com/owner/repo
qs list
qs remove repo
```
```
from "packages/owner_repo/main.qs" import something
```
通过 `qs init` 搭建带有清单文件的项目脚手架，它会创建 `main.qs`、一个 `test/` 目录以及一个 `quanto.json`。
## 从源码构建
QuantoScript 是一个单一的 C99 合并文件 (`src/quanto.c`)。它需要一个 C 编译器和 **OpenSSL**（由 HTTP/WebSocket 栈使用）。不同平台的网络库有所不同。
### 前置条件
| 平台 | 工具链 | OpenSSL |
|----------|-----------|---------|
| macOS | Xcode Command Line Tools (`clang`) 或 `gcc` | `brew install openssl@3` |
| Linux | `gcc` / `clang` | `libssl-dev` (Debian/Ubuntu) 或 `openssl-devel` (Fedora) |
| Windows | MSYS2 / MinGW-w64 `gcc` | `pacman -S mingw-w64-ucrt-x86_64-openssl` |
### macOS
Homebrew 将 OpenSSL 安装在默认搜索路径之外，因此需要将编译器指向它：
```
SSL=$(brew --prefix openssl@3)
cc -std=c99 -O2 -Isrc -I"$SSL/include" src/quanto.c -o qs \
-L"$SSL/lib" -lssl -lcrypto -lpthread -lm
```
### Linux
```
gcc -std=c99 -O2 -Isrc src/quanto.c -o qs \
-lssl -lcrypto -lpthread -ldl -lm
```
### Windows (MSYS2 / MinGW-w64)
```
gcc -std=c99 -O2 -Isrc src/quanto.c -o qs.exe \
-lssl -lcrypto -lws2_32 -lwinhttp -lwininet -lcrypt32
```
### 使用 Make (推荐)
`Makefile` 会自动检测 OpenSSL（在 macOS 上通过 Homebrew，在其他平台上通过 `pkg-config`）：
```
make # build build/qs
make test # build and run the regression suite
make clean # remove build artifacts
```
有用的覆盖项：
```
make OPENSSL_DIR=/path/to/openssl # point at a specific OpenSSL prefix
make STATIC_SSL=1 # statically link OpenSSL (self-contained binary)
make CC=clang # choose the compiler
```
### 使用 CMake
```
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
# 可选: 独立二进制文件与打包
cmake -S . -B build -DQS_STATIC_OPENSSL=ON && cmake --build build
cpack --config build/CPackConfig.cmake # produce a .tar.gz / .zip
```
### 可选：Python 嵌入
使用 `-DQS_PYTHON` 和 Python 头文件进行构建，可以启用 Python FFI 示例。
## 项目结构
```
src/ C source (single-file amalgamation)
quanto.c Entry point that includes the parts below
parts/ Language modules (.inc): parser, VM, compiler, runtime, CLI, …
stdlib/ Standard library modules (.qs)
examples/ Example programs (see full_tour.qs)
tests/ Regression and stress test suite
docs/ Language & format documentation, audit reports
tools/ Benchmarks, CMake helpers, packaging metadata
scripts/ Build and install scripts
build/ Build output (gitignored)
```
## 已知限制
这是一个 **v1.0.0** 版本。以下是已知并正在跟踪的问题：
- **闭包**与捕获的变量无法正常工作——捕获外部局部变量的内部函数会返回 `null`。
- **类方法体**必须每行编写一条语句（不支持多行语法）。
- **返回类型注解**会被解析，但尚未强制执行。
- **Async/await 无法正常工作。** 当有两个或更多任务时，`stdlib/async.qs` 任务队列会挂起，并在高负载下不确定地崩溃。单任务的 `spawn`/`run`/`result` 可以正常工作。请参阅 [docs/ASYNC_VALIDATION.md](docs/ASYNC_VALIDATION.md)。
- 树遍历解析器不支持单行的 `try`/`oops` 语法。
- **Python 嵌入**需要 `-DQS_PYTHON` 构建标志和 Python 头文件。
## 路线图
| 版本 | 重点 |
|---------|-------|
| **v0.2.0** | 可用的闭包、更丰富的字符串/map 方法 |
| **v0.3.0** | Async/await、更广泛的原生编译器覆盖范围 |
## 贡献
欢迎提交 Issues 和 pull requests。有关指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)；有关发布历史，请参阅 [CHANGELOG.md](CHANGELOG.md)。提交更改时，请先运行回归测试套件：
```
make test
```
## 许可证
基于 [MIT 许可证](LICENSE) 发布。