语言 API 与命令行

6. 标准库(内置函数,不可重定义;均提供英文别名)

别名与中文名指向同一函数,可混用。调用非内置且未定义的函数、参数个数不符 → 编译错(非运行时错)。

实现形态(v2.12):表中 分割/连接/开头是/结尾是/重复/去空白/转大写/转小写/转整数/编码BASE64/解码BASE64/正则转义/编码URL/解码URL/哈希SHA256/哈希MD5/映射/过滤/归约/绝对值 二十条(以及 v2.39 新增的 字符串构造/字符串追加/字符串取值/字符串长度/串长 与 加溢出/减溢出/乘溢出/加检/减检/乘检、索引/计数/去重/求和/反序/扁平/最大元素/最小元素/复制/合并/字典筛选/字典映射)由 zhlang 源码实现(仓库 标准库/{字符串,编码,容器,数学,摘要}.zh,隐式装载,见 §3.3;按需发射——未被引用的模块不进入产物);行为与本规格一致(函数名、参数、错误文案逐字不变,保持原语义)。差别仅在运行时错误的行号指向标准库实现行(见 §7)。另有用户可引入的标准库模块 标准库/集合.zh(反转(原地反转)、最大值(a, b)、最小值(a, b),等值返回 a;裸名 @引入 "集合.zh" 即可,见 §3.3)与 标准库/同步.zh(互斥锁/条件/读写锁/等待组/一次,见 §6.5)、标准库/错误.zh(类型化错误基类/工厂/文本提取,见 §6.6)。

6.1 正则(v2.0)

语法:字面字符、.(任意码点,不含 \n)、^ $(串首/串尾;非多行时 $ 也匹配结尾换行前)、\A \Z(严格串首/串尾)、 字符类 [abc] [^abc] [a-z] [一-龥](] 作首字符为字面)、预定义类 \d \D \w \W \s \S、 词界 \b \B、分组 (...) 与 (?:...)、或 |、 量词 * + ? {n} {n,} {n,m}(均可后缀 ? 表示懒匹配)、转义 \n \t \r \f \v \0 \uXXXX \xNN 与标点字面。

选项(第 3 参,缺省空串;i 忽略大小写(ASCII、全角字母、Latin-1)、s 让 . 匹配换行、m 让 ^ $ 按行): 正则匹配(文本, 模式, "is")。

语义(与 Python re 逐项对齐):最左匹配、备选取先(左优先)、量词贪婪(懒匹配后缀 ?); 空匹配的处理同 Python 扫描器——某位置匹配为空时,同位置再试一次非空匹配,再前进一个码点 (故 正则全部("aaaa", "a*?") 得 9 个结果:"", "a", "", "a", …)。

未支持:反向引用(\1)、命名分组、环视 (?=…)、条件分组、POSIX 字符类 [[:alpha:]]、\p{…} —— 用到即报「不支持/未知转义」错。 Unicode 口径是近似:\w 对非 ASCII 默认算词字符,但 CJK 标点(U+3000–303F)、通用标点(U+2000–2BFF)、全角标点、表情符号除外(与 Python 对 CJK 文本大体一致); \d 认 ASCII 与全角数字;\s 认 ASCII 空白与常见 Unicode 空白(含 U+3000)。

限定与错误:模式是运行时值,模式错误与超限都走运行时错误(带行号): 正则模式错误:…(如「分组未闭合(缺少 ))」「不支持反向引用(\1)」「字符类范围颠倒」); 回溯有步数上限(约 2 亿步)——病态模式(如 (a+)+b 长串)报「回溯步数超限」而不是挂死; 含「或/重复」的分组重复在长输入上有约 100 轮的嵌套上限(报「回溯嵌套过深」), 而确定性体(如 (?:ab)*、(\d\d,)*)与前缀单字符重复(a*、\d+)走迭代实现,不受轮数限制。

6.2 网络与 TLS(v2.1)

取网页 / 网页请求 / 连接到 / 监听 / 接受连接 是内置网络栈;其中 原生后端的 https 走纯 zhlang TLS 1.3(标准库/TLS.zh);冻结的 C 版/自举编译器走自包含 mbedTLS 3.6.2 (代码 vendored 在 third_party/mbedtls/,见其 ZHLANG-VENDOR.md)。

• 协议:TLS 1.3 与 1.2(客户端;C 版/自举的 mbedTLS 路径)。原生后端的纯 zhlang TLS 仅实现 TLS 1.3(TLS_CHACHA20_POLY1305_SHA256 + x25519);只支持 TLS 1.2、或不提供 ChaCha20 密码套件的服务器(部分 badssl 用例、百度等)无法连接,可用 ZHLANG_HTTPS=curl 回退系统 curl。SNI 送出;只做客户端,不提供 DTLS/服务端/客户端证书/会话票据持久化。
• 撤销检查:mbedTLS 路径(C 版/自举)不做 OCSP/CRL;原生后端的纯 zhlang TLS 支持 CRL

(本地 PEM 文件 + CDP 抓取,吊销命中硬失败)与 OCSP 钉接(只验证服务器在 CertificateEntry 中钉接的响应,不主动请求响应器)。

• 校验:VERIFY_REQUIRED——证书链必须链到受信任 CA,且主机名必须与证书 SAN(无 SAN 时回退 CN)匹配;

任一不符即运行时错误(TLS 握手失败(主机名:TLSv1.3):X509 - Certificate verification failed…), 绝不静默放行。

• CA 来源(按序):环境变量 ZHLANG_CA_FILE / SSL_CERT_FILE → 系统包

(/etc/ssl/certs/ca-certificates.crt、/etc/pki/tls/certs/ca-bundle.crt、 /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem、/etc/ssl/cert.pem 等) → 内嵌的 CA 包(third_party/ca-bundle.crt,三个目标都随产物携带,最小容器/真机开箱可用)。 全部落空 → 报错并提示安装 ca-certificates 或设置 ZHLANG_CA_FILE/SSL_CERT_FILE。 系统包优先于内嵌包,系统更新 CA 后立即生效。

• 超时:连接 5s;收发沿用套接字读超时 10s(TLS 层把读超时映射为错误而不是空转)。
• 收尾:对端直接关连接而未发 close_notify(精简实现常见)按正常结束处理;正文以连接关闭定界,

不做 Content-Length 截断检测(需要严格截断防护的场景请自行核对响应长度)。

• 排查开关:ZHLANG_TLS_DEBUG=2(1~4 递增)打印 mbedTLS 报文级日志到 stderr。
• 原生后端(纯 zhlang TLS,M4):x86_64/aarch64 Linux 的 https 由 标准库/TLS.zh 完成 TLS 1.3 握手、证书链/主机名校验与传输;不依赖 curl、不链接 C 库。信任库顺序:ZHLANG_CA_FILE → SSL_CERT_FILE → 系统 CA 文件 → 编译期内嵌 third_party/ca-bundle.crt(ZHLANG_CA_EMBEDDED=1 可强制内嵌)。校验失败必定报错,不静默回退;套接字在原生后端就是 fd/SOCKET 整数,类型(监听(...)) 返回 整数,打印按整数输出;套接字 类型标注按整数承载检查(见 §2.3);ZHLANG_HTTPS=curl 可显式改用系统 curl -sS -i。Windows PE 仍用 WinHTTP(系统 TLS/CA)。TLS 代码与内嵌 CA 只在程序用到 取网页/网页请求 时发射。
• 体积账:TLS 代码只在程序用到 取网页/网页请求 时才链进产物(编译期门控 ZHLANG_HTTP_TLS),

用到时约 +0.6~0.9MB;不用 HTTP 的程序体积不变。交叉目标从 sysroot/<目标>/lib/libzhtls-<目标>.a 取归档(缺档则 https 回退为「暂不支持」错误,明文 http 不受影响)。

6.4 进程与终端(v2.6)

这六个内置供 CLI/REPL 用语言自身实现而设(自举编译器 编译主.zh 的 --repl 通路)。都可用英文别名调用。

• 执行捕获(程序, 参数数组) —— 与 执行 的关键差别是不经 shell:

参数按数组原样进 argv(空格、引号、通配符都不会被再解释一遍),退出码 也不会被 shell 覆盖;stdout 与 stderr 合流捕获(顺序即真实写出顺序), 返回 {"输出": 字符串, "退出码": 整数}(被信号结束记 1)。 程序无法启动(不存在/无执行权限)→ 可捕获的运行时错误 「无法执行「…」:<原因>(程序不存在或无法启动)」。 参数数组只能放字符串,否则运行时错误。 平台注:Windows 的 argv 经 ANSI 码页,非 ANSI 字符到不了子进程(与 shell 无关的既有约束)。

• 是终端() —— isatty(0)。REPL 据此决定要不要印提示符(>>> / ... );

管道/重定向里为假,REPL 输出因此可稳定对拍。

• 忽略中断(真/假) —— 置 SIGINT 为 SIG_IGN/SIG_DFL。REPL 开头调

忽略中断(真):子进程收到 Ctrl-C 不会把 REPL 一起带走。

• 程序路径() —— argv[0]。CLI 靠它定位自身可执行文件所在目录,

进而找 <程序目录>/sysroot/<三元组> 里的交叉归档(自举编译器的关键依赖)。

• 输入结束() —— feof(stdin)。读入 在 EOF 与「用户敲了空行」都返回 "",

REPL 靠这个区分 Ctrl-D 与回车续行。

• 输出(s) —— 逐字写 stdout、不补换行、立即冲刷。打印 会补换行并加空格分隔,

输出 不会 —— REPL 的提示符与「只显示新增输出」的前缀裁剪要的正是前者。

6.5 同步原语(标准库/同步.zh)

标准库/同步.zh 是可引入的标准库模块(不是内置、不隐式注入),纯 zhlang 用通道实现, 为共享内存并发提供 Go sync 风格的锁。裸名引入(见 §3.3):

@引入 "同步.zh" 只 互斥锁, 读写锁, 等待组, 一次
@引入 "同步.zh" 为 同步

• 互斥锁:初始化()、加锁()(阻塞)、解锁()(未持有时抛可捕获错误;不校验解锁者身份)、

尝试加锁() → 真/假、加锁执行(f)(作用域锁:f 正常返回或抛错都会解锁,返回 f 的结果)。

• 条件:初始化(互斥锁)、等待()、通知() → 真/假、通知全部() → 被唤醒数。

与 Go sync.Cond 同规:等待/通知/通知全部 必须在关联的互斥锁持有期间调用; 等待者进入 FIFO 队列后释放锁,被唤醒后重新加锁。

• 读写锁:读锁()/读解锁()、写锁()/写解锁()、尝试读锁()/尝试写锁()、

读锁执行(f)/写锁执行(f)。读者共享、写者独占,写者优先(有写者在等时新读者等待, 避免写者饿死);非重入。读/写解锁在计数不符时抛错。

• 等待组:添加(n)、完成()(=添加(-1))、等待()。计数减到 0 时广播唤醒全部等待者;

添加 须在 等待 之前完成(Go sync.WaitGroup 同规),归零后可复用;负计数抛错。

• 一次:执行一次(f)。首个调用者执行 f 并返回 真,其余调用者等待 f 结束(或抛错)后返回 假;

f 的返回值不向外传。f 抛错也算「已执行」——错误只抛给执行者,等待者不重跑;递归调用自身会死锁 (与 Go sync.Once 相同)。

限制与约定:

• 全部阻塞都是通道阻塞,由调度器挂起协程,不占死 worker;实现只依赖 通道/选择,不新增运行时。
• 互斥锁/读写锁不是重入锁,也不校验持有者身份(与 Go sync 一致)。
• zhlang 没有 finally;临界区可能抛错时用 加锁执行/读锁执行/写锁执行,手写加解锁需覆盖所有退出路径。
• 通道只保护队列本身,不保护负载;数组/字典内部仍无锁,并发读写共享容器必须用这里的锁或通道所有权。
• 同步模块基于协程/通道,自举原生版已支持(x86_64/aarch64 实测,Windows PE 经 wine 验证)。

6.6 类型化错误(标准库/错误.zh)

标准库/错误.zh 是可引入模块(不是内置),提供共享的错误基类、工厂与判别工具, 配合 §3.4 的 抛出对象 使用。

• 错误基类:字段 消息 字符串、代码 整数、原因(默认 假);方法 文本() 返回消息。

它作为原型链的基类:继承(错误基类, {...}) 或工厂函数都能创建带该原型的错误对象。

• 工厂:新建错误(消息)、新建错误码(消息, 代码)、新建错误类型(类型, 消息, 代码)。

返回带 错误基类 原型与 消息/代码/原因 字段的字典;新建错误类型 额外写 类型 标签。

• 工具:错误文本(e)(字符串原样;字典优先取 消息;其余转字符串)、

是错误(e)(字典且沿原型链是 错误基类)、错误类型(e)(是错误时返回 类型 字段,缺省空串)。

@引入 "错误.zh" 只 新建错误类型, 是错误, 错误类型
尝试
    抛出对象(新建错误类型("参数错误", "年龄必须为正", 400))
捕捉 e
    如果 是错误(e)
        打印(错误类型(e), e.消息, e.代码)

捕捉变量得到对象(字典),可 是(e, 错误基类)、读字段;普通 抛出 与运行时错误仍是字符串。 未捕获的 抛出对象 优先打印对象的 消息 字段(含原型链),没有该字段时按显示规则打印整个值。

限制:语言目前只支持同一模块内的 类 子类(父类) 继承;跨模块类继承不支持。 因此本模块用原型链 + 类型 字段做错误分类。若需要真正的类继承,可在同一文件内自行 声明错误基类与子类(类语法、是、初始化继承都可用),再用 抛出对象 保留实例。

原生实验后端支持 抛出对象 与字典/原型错误的捕捉;未捕获对象只打印「未捕获的异常」, 不打印消息字段。

6.7 可引入命名空间模块(v2.23 增补)

以下模块都不是内置、不隐式注入,源码在 标准库/,用裸名引入(见 §3.3)后限定调用:

网页 是 HTML 构建/渲染库:节点是普通值(文本/原样/片段/元素),文本与属性值 默认转义,只有 原样 输出未转义 HTML。核心输出方式是动态的:逐块输出(节点, 写块) 按文档顺序把片段逐块交给写块,不构造完整字符串;动态(节点) 返回渲染器函数; 响应(节点)/响应码(节点, 状态) 直接得到可交给 服务 的动态响应(HTTP/1.1 分块传输)。 渲染/渲染美化 与 写出/写出美化 保留为一次性收集/静态落盘的兼容接口。

@引入 网页
@引入 服务
常量 页 = 网页.页面("你好", [
    网页.区块({"class": "卡片"}, [
        网页.标题(1, "你好,zhlang"),
        网页.段落("安全转义: <b> & \"引号\""),
        网页.链接("https://example.com/", "去看看"),
    ]),
])
网页.写出("index.html", 页)              // 直接输出 HTML 到文件
服务.GET(应用, "/", (请求) => 网页.响应(页))  // 动态输出

// 动态加载:先出占位节点,浏览器端加载脚本拉取片段并替换
常量 板 = 网页.片段([
    网页.标题(1, "慢慢来"),
    网页.动态加载("/片段/统计"),
    网页.加载脚本(),
])

JS 用 zhlang 构造 JavaScript 源码:节点是普通值;字符串借 JSON 规则转义,标识符 做形状与 JS 保留字校验;二元/一元表达式自动加括号避免优先级陷阱;渲染 产出 2 空格 缩进的多行代码,渲染紧凑 产出一行内联代码,写出/写出紧凑 直接落盘;原样 是 唯一不转义的入口(调用方保证可信)。本库只生成 JS 文本,不把 zhlang 编译成 JS, 可配合 网页.脚本(JS.渲染(脚本)) 内联到页面。

@引入 JS

常量 脚本 = JS.程序([
    JS.常量声明("x", 1),
    JS.函数声明("add", ["a", "b"], [
        JS.返回语句(JS.二元("+", JS.标识("a"), JS.标识("b")))
    ]),
    JS.表达式语句(JS.调用(JS.成员(JS.标识("console"), "log"), [
        JS.调用(JS.标识("add"), [JS.标识("x"), 2])
    ]))
])
JS.写出("app.js", 脚本)

产出:

const x = 1;
function add(a, b) {
  return (a + b);
}
console.log(add(x, 2));

服务 是 Flask/Gin 风格的 HTTP 服务框架:路由支持静态段、:名字(单段捕获)与 *名字(剩余路径);使用 组合中间件((请求, 下一个) => 响应,不调用下一个即短路), 分组 带前缀注册并拥有独立中间件;请求侧提供查询/头/Cookie/表单/JSON/路由参数, 响应侧提供文本/HTML/JSON/状态码/加头/重定向/文件/空;自动处理 404、405(带 Allow)、 OPTIONS 与 HEAD;静态 映射目录(拒绝 .. 穿越),支持二进制、ETag/If-None-Match 与单区间 Range(206/416)。每连接一个协程,支持 HTTP/1.1 保持连接、Content-Length、 分块请求体与 100-continue、请求头/体大小上限;配置 读超时(默认 30s)给每个连接设 收发超时,最大连接(默认 1024,0=不限)超限回 503 并立即关闭(背压),停止(应用) 置停止标记、关闭监听并在 停机超时(默认 10s)内排空在途连接。上传与推送: multipart/form-data(表单文件/表单值/上传文件)、SSE(事件流/发事件/ 发事件名/发事件编号/发注释);处理函数置 请求["接管"]=真 后框架不再写 HTTP 响应(WebSocket 等自写协议)。访问日志写 stdout:服务:GET / [200] 0ms 2B 对端 UA=…,状态码按类别着色(2xx 绿/3xx 青/4xx 黄/5xx 红),耗时 ≥300ms 黄、≥1s 红; 配置 彩色 取 真/假/"自动"(默认;仅交互终端),NO_COLOR=1 关闭、ZHLANG_COLOR=1 强制。装饰器 @服务.装饰(应用, 方法, 路径) 供原生后端使用,C 引导器改走三参调用。 响应体可以是字符串,也可以是 (写块) => … 的动态渲染器:动态HTML/动态HTML码 默认在发送前收集动态体并给 Content-Length(对大页面更稳);流式HTML/流式HTML码 显式选择 Transfer-Encoding: chunked 边渲染边发送(HTTP/1.0/HEAD 下仍自动收集)。 响应体(响应) 用于测试时收集动态体。测试请求/测试请求体 不启动服务器, 直接跑一次分派,便于单元测试。头编码:头值中的非 ASCII/控制字节按 UTF-8 逐字节 %XX 编码(响应与 网页请求 请求头同口径),线上头保持 ASCII,读取端 可用 解码URL 还原;请求头名必须是 ASCII 令牌(§6.2)。

@引入 服务

常量 应用 = 服务.新应用()
服务.GET(应用, "/", (请求) => 服务.文本("你好,zhlang"))
服务.GET(应用, "/api/用户/:id", (请求) =>
    服务.JSON({"id": 服务.取参数(请求, "id")}))
服务.运行(应用, 8080)

限制:无 TLS 服务端与 HTTP/2;WebSocket 需用连接接管(请求["接管"])自写帧。 本模块使用原生后端的套接字超时/地址原语,须用自举原生编译器(build/原生)编译; 已冻结的 C 引导器不能编译本模块。动态响应体仍按字符串采集,静态文件可发二进制。

样式 用 zhlang 写 CSS:声明键可写中文(如 颜色/字号/内边距,映射到 CSS)或标准 CSS 名(--自定义变量 原样通过);数组值按空格连接(内边距: [像素(12), 像素(16)]), 假 值跳过(条件样式)。规则/媒体/关键帧/根变量组合成样式表;与网页库配合用 网页.页面带样式(标题, 体, css) 内联,或 网页.样式链接("样式.css") 外链。

@引入 样式
@引入 网页

常量 css = 样式.样式表([
    样式.规则(样式.类选择器("卡片"), {
        "背景色": "#fff",
        "圆角": 样式.像素(8),
        "内边距": [样式.像素(12), 样式.像素(16)],
    }),
    样式.媒体("(max-width: 600px)", [
        样式.规则(样式.类选择器("卡片"), {"内边距": 样式.像素(8)}),
    ]),
])
网页.写出("样式.css", css)
网页.写出("index.html", 网页.页面带样式("标题", [网页.段落("你好")], css))

原生内容可以自由混入(内容由调用方保证可信):HTML 用 网页.原样(html),CSS 用 网页.样式块(css) / 网页.样式链接(url) 或 样式.原样(css) 混进样式表,JS 用 网页.脚本(js) / 网页.脚本链接(url) / 网页.脚本模块(url);网页.页面带资源(标题, 体, css, js) 一次带上原样 CSS 与 JS。

约定:

• 模块内不 @引入 其他模块,只依赖内置;同名包装(如 文件.写文件)内部用英文内置别名

或不同的中文内置名调用,避免递归。

• 普通函数没有默认参数,因此可选参数一律拆成独立变体(如 正则.匹配选项,

进程.环境变量或)。

• 官网自举原生版以原生后端为准:原生 x86_64/aarch64 Linux 可用全部可引入模块

(含 同步,纯 zhlang 通道实现),包括 文件/JSON/正则(含 i/s/m 选项)/ 进程/终端/时间/随机/路径工具/集合/错误/网页/网络 (TCP/HTTP/HTTPS;Linux DNS 内置/HTTPS 纯 zhlang TLS,PE 用 gethostbyname + WinHTTP); 未覆盖的内置会明确报错。原生 Windows PE 目标自 v2.23 增补起支持文件 IO (宽字符路径;目录存在性用 GetFileAttributesW 判定)与目录列举 (FindFirstFileW/FindNextFileW/FindClose);进程(执行/执行捕获)也已覆盖 (CreatePipe + CreateProcessW,命令行 MSVCRT 引用规则,输出按 ACP 解码)。

6.8 原生编译器:自举与 Go 式多端(v2.23 增补)

纯 zhlang 原生编译器(自举/原生.zh)自本版起可以编出自身:

• 自举不动点:stage0(仓库 stage-0 引导器)→ stage1(stage0 编译编译器源码)

→ stage2(stage1 再编译自身);cmp stage1 stage2 逐字节相同(make selfhost)。

• Go 式多目标:一个原生编译器二进制内建 x86_64 ELF/PE 与 aarch64 后端。

--target 可用三元组或 Go 风格 系统/架构(linux/amd64、windows/amd64、 linux/arm64);选择优先级:--target > ZHC_TARGET > ZHC_GOOS+ZHC_GOARCH > 宿主。--targets 列出目标、产物后缀与能力表。 目标表的唯一来源是 自举/驱动/目标.zh,驱动不再散落按目标名判断。

• Windows PE 目标:读文件/写文件/追加文件/文件存在/文件大小/删除文件/建目录

已实现(CreateFileW/ReadFile/WriteFile/SetFilePointer/DeleteFileW/ CreateDirectoryW/GetFileAttributesW);路径、命令行、环境变量全部走 UTF-16 W 版 API,通过 MultiByteToWideChar/WideCharToMultiByte 与 UTF-8 互转, 中文源码名/参数/文件名在 Windows 上可用;参数()/程序路径() 从 GetCommandLineW 解析;PE 堆改为 64MB/256MB 的 bump 分配器(旧实现每次分配 调用一次 VirtualAlloc,无法支撑自举)。

• Windows 交叉自举:Linux 上的 stage0 可直接产出 PE 编译器;该 PE 编译器

在 wine/Windows 上能再编译自身,也能交叉输出 Linux ELF(同一编译器多目标)。

• aarch64 交叉自举:a64 后端已与 x86_64 后端同覆盖面(容器/字典/异常/

闭包/结构体/类/浮点/模块/文件 IO/JSON/正则/进程/终端),tests/原生 全部语料 在 qemu 下与 x86_64 产物逐字一致。make selfhost-a64 由 x86_64 宿主产出 arm64 编译器,该编译器在 qemu 下继续产出 arm64 程序; ZHC_SELFHOST_A64_FULL=1 时再让它编译自身并做逐字节不动点比对 (v2.23 已在 qemu 下验证 stage1 与 stage2 逐字节相同)。

• 原生网络与接口(v2.25):x86_64-linux 原生后端新增纯 syscall 网络栈

(连接到/套接字发送/套接字接收/关闭套接字/监听/接受连接 与 取网页/网页请求,HTTP/1.1、chunked、DNS;HTTPS 纯 zhlang TLS(Linux,aarch64 同样)/WinHTTP(PE)) 与 Go 式结构化 接口、参数类型标注(见 §3.2);套接字是文件描述符整数, PE 网络已接入(WinSock + WinHTTP),PE 目录列举与进程 IO(CreateProcess)亦已接入。网络/TLS 的完整版实现仍更全。

• 仍未打通:PE 目标上的 REPL 行编辑/终端路径未在真机充分验证;

原生网络未移植(网络在编译期报错)。

6.9 原生后端:无符号 64 位 / 64×64→128 intrinsic

原生后端(x86_64 与 aarch64)提供一组 intrinsic。值仍是整数(tag=1),64 位载荷按 二补码解释;负数视为 2^64+v,没有独立的“无符号”类型,类型() 仍返回“整数”。

英文别名:umul128 / umulhi / umullo / ushr64 / ucmp64 / udiv64 / umod64。 参数必须是整数(否则运行时类型错误)。普通 + - * & | ^ << 的 64 位环绕语义不变; 普通 >> 仍是算术右移,需要逻辑右移时用 原无符号右移。这些 intrinsic 为原生后端专用。

常量 组 = 原乘128(-1, -1)          // (2^64-1)^2
打印(组[0] == -2)                  // 高 64 位 0xFFFFFFFFFFFFFFFE
打印(组[1] == 1)                   // 低 64 位 1
打印(原无符号右移(-1, 1))          // 9223372036854775807

6.10 调试断点(原生后端,v2.27 增补)

• 指令:@断点调试[(等级, 内容)],可写在顶层或函数/块内;也接受

@调试断点、@breakpoint。等价函数调用:调试断点([等级, 内容])、 断点(...)、breakpoint(...)(可作为表达式使用)。省略等级时只写内容; @断点调试() 无内容。

• 等级:标准等级如下(越小越重要),名称与整数等价,打印在 [ ] 里:

| 名称 | 数值 | 用途 | | --- | --- | --- | | 错误 / error | 0 | 必须立刻看 | | 警告 / warning / warn | 1 | 可疑状态 | | 信息 / info | 2 | 一般流程 | | 调试 / debug | 3 | 细节/高频 |

环境变量 ZHLANG_DEBUG_LEVEL 写数值或名称作为上限,等级大于上限的断点 不输出也不暂停;其它非标准值不参与过滤,始终显示。

• 开关:只有 -d/--debug 才生成断点代码;不加时整条指令剥掉,参数表达式

不求值。原生 源.zh -d 是调试运行——编译到临时文件后直接执行(用后删除, 不留下二进制;交互终端下 stdout/stderr 直连终端,断点提示实时可见),退出码即 被调试程序退出码;原生 源.zh -o 产物 -d 则产出带断点的调试二进制。 非终端(管道/重定向)下只捕获被调试程序的 stdout 并回放到标准输出, stderr(断点/诊断)继承父进程的 stderr,不再与程序输出合流。 交叉目标不能直接运行,必须写 -o。

• 输出:运行时向 stderr 打印一行 断点 <文件>:<行> <函数> [<等级>] <内容>;

顶层语句的函数名为 (顶层)。文件是传给编译器的模块路径。交互终端下等级标签按 等级着色(错误红/警告黄/信息青/调试灰);stderr 不是终端时输出纯文本。

• 暂停策略:stdin 不是终端时打印后继续(便于 CI/重定向);

ZHLANG_DEBUG=0 完全关闭;ZHLANG_DEBUG=1 强制进入命令循环(管道调试)。

• 命令:交互提示符为 调试 <文件>:<行>>,暂停位置始终可见;

c/continue/继续 继续运行;q/quit/exit/退出 终止程序; b/bt/栈 再次显示当前位置(调用栈回溯尚未支持);?/h/help/帮助。

函数 处理(n)
    @断点调试(1, "n=" + 转字符串(n))
    返回 n + 1

打印(处理(1))

$ ./原生 例.zh -d
断点 例.zh:2 处理 [1] n=1
调试 例.zh:2> c
2

6.11 网页动态输出与动态加载(v2.28 增补)

网页 的主输出路径不再返回整段 HTML 字符串,而是逐块输出:

动态加载有两层:

• 服务端按需:按需(加载函数) 节点的加载函数在输出到该位置时才调用,返回要渲染的

节点;节点数组/子节点里也可以直接放函数值 () => 节点。

• 浏览器端动态:动态加载(地址)/动态加载文本(地址, 占位) 输出带 data-src 的

占位 div;页面加入 加载脚本()(或单独引用 加载脚本文本())后,脚本在 DOMContentLoaded 时 fetch 地址并用返回的 HTML 片段替换内容。片段端点可直接返回 网页.响应(片段)。加载成功加类 已加载,失败加 加载失败 并显示错误文本。

直接输出 HTML 仍然完整保留:渲染/渲染美化 出字符串,写出/写出美化 落盘; 静态站点生成与动态服务端渲染共用同一棵节点树。

6.12 数据库(标准库/数据库.zh)

标准库/数据库.zh 是可引入模块(不是内置),纯 zhlang 实现的嵌入式表/文档数据库: 记录是字典,表是记录数组,JSON 文件持久化,可选主键、字段索引与事务回滚。

@引入 数据库
常量 库 = 数据库.打开("应用.db")
常量 用户 = 库.建表("用户", "编号")
用户.插入({"编号": 1, "名字": "张三", "年龄": 30})
用户.建索引("名字")
打印(用户.按(1)["名字"])               // 主键查
打印(用户.找("名字", "张三"))           // 字段查(参数化)
打印(用户.查询(r => r["年龄"] > 26))    // 条件函数查
用户.更新(1, {"年龄": 31})
用户.删除(1)
库.保存()

语义与约束:

• 记录:只允许 JSON 数据(字典/数组/整数/浮点/字符串/布尔,字典键必须是字符串)。

插入/更新时深拷贝并校验,外部改不动库内状态。

• 主键:只接受 整数/字符串,插入与更新时保证唯一;按 用主键命中原行或返回 假。
• 读取返回副本:按/找/查询/第一/全部 都返回深拷贝,修改必须走 更新/删除,

避免绕过主键与索引约束。

• 索引:建索引(字段) 只加速 字符串/布尔 的等值查询;数值与容器值走线性扫描,

保证跨 整数/浮点 的 == 语义正确。

• 持久化:保存() 先写 路径.bak 再写主文件;打开 时主文件损坏则回退 .bak。

文件内容是 {"格式":1,"表":{…}} 的 JSON。JSON 不区分整数/浮点:整数值浮点(如 4.0) 重新读回会变成整数 4。

• 事务:事务(f) 在任何抛出时把全部表恢复到进入前状态并重抛;不支持嵌套;

事务进行中调用 保存() 会抛错(不自动落盘)。

• 并发:本地库对象不是协程安全的;跨协程共享请用 同步.互斥锁 保护。
• 远程:远程服务(库, 端口, 令牌) 启动令牌认证服务,远程连接(地址, 端口, 令牌)

返回远程库代理(方法:建表 删表 有表 表名 保存 关闭;表代理: 插入 按 找 全部 计数 更新 删除)。协议是换行分隔 JSON、值参数化, 不接收 SQL 文本;条件函数与事务不能跨进程。内置 监听 绑 0.0.0.0,必须使用 非空令牌;协议为明文 TCP(无服务端 TLS),公网须走反向代理/隧道。服务端串行化 请求;服务器程序应使用 ≥2 个 worker(默认按 CPU 数)。

• 外部数据库网关:纯 zhlang 且原生后端无 C 混写,不能直接加载 JDBC/ODBC/

原生驱动。网关连接 把「SQL 语句 + 参数数组」发给网关进程,由网关用目标数据库 的驱动绑定执行;参考网关 tools/数据库网关.py 用 Python 标准库 sqlite3, PostgreSQL/MySQL 按同一协议扩展(关闭多语句、引号外 ? 安全转换)。 值永远走参数绑定,禁止把用户数据拼进 SQL;zhlang 侧不解析 SQL。

// 外部数据库:网关连接(参考网关为 Python sqlite3;PG/MySQL 同协议扩展)
@引入 数据库
常量 网 = 数据库.网关连接("127.0.0.1", 18932, "令牌")
网.执行("CREATE TABLE 用户 (编号 INTEGER PRIMARY KEY, 名字 TEXT)", [])
网.执行("INSERT INTO 用户 (编号, 名字) VALUES (?, ?)", [1, "张三"])
常量 行 = 网.查询("SELECT 编号, 名字 FROM 用户 WHERE 编号 = ?", [1])
打印(行[0]["名字"])            // 张三
常量 载荷 = "Robert'); DROP TABLE 用户;--"
网.执行("INSERT INTO 用户 (编号, 名字) VALUES (?, ?)", [2, 载荷])  // 只是数据
网.关闭()

注入安全:本地/远程表引擎没有 SQL 解析器,传入的字符串永远是数据; 网关客户端只发「语句 + 参数数组」,值由网关侧绑定。因此不存在可被绕过的转义层。 回归用例把 Robert'); DROP TABLE 用户;--、" OR "1"="1 等载荷作为参数存取, 并验证表结构不变。SQL 文本必须由开发者编写占位符,用户数据只进参数数组。

6.13 原生后端内部原语(不保证兼容)

下列名称由原生后端运行时/编译器内部使用,普通用户代码可调用但不承诺兼容性:误用可读写任意进程内存、破坏运行时状态或直接崩溃进程。

原分配 原读8 原读64 原写8 原写64 原拷贝 原系统 原标签 原载荷 原错误 原线程取 原原子交换64 原原子写64 原原子加64(以及 原生_ 前缀的运行时内部函数)。

标准库与规格示例不应使用这些名称;后续版本可能改名、限制参数或禁止用户代码调用。需要文件/网络/进程/内存等能力时使用 §6 的公开内置。

6.14 标准库扩展 API(v2.39)

本节是 §6.7 模块表与隐式标准库新增函数的完整签名/返回值/错误口径。隐式模块 (字符串/编码/容器/数学/摘要)的函数全局可用;可引入模块用 模块.函数(…)。

数学(隐式,标准库/数学.zh)

字符串(隐式,标准库/字符串.zh)

集合(可引入,标准库/集合.zh)

时间(可引入,标准库/时间.zh)

随机(可引入,标准库/随机.zh)

随机种子由运行时自动初始化,混入秒级时间、单调毫秒与栈地址低 10 位,同一秒 启动的多个进程不再产生相同序列(仍为确定性伪随机,不用于密码学)。

文件 / 路径工具 / 编码 / 摘要 / JSON / 进程

HTTP 头编码:服务端响应头与 网页请求 请求头中的非 ASCII/控制字节按 UTF-8 逐字节 %XX 编码,ASCII(含已有 %)原样;线上头保持 ASCII。请求头名必须是 ASCII 令牌。读取端用 解码URL 还原。

@引入 时间
@引入 摘要
@引入 集合

常量 d = 时间.分解(1700000000)
打印(d["年"], d["月"], d["日"], d["星期"])       // 2023 11 15 3
打印(时间.解析日期("2023-11-15T06:13:20+08:00")) // 1700000000
打印(摘要.哈希HMAC("key", "x"))                  // 4fc3b7ea…
打印(集合.分块([1,2,3,4,5], 2))                  // [[1, 2], [3, 4], [5]]

6.15 包管理与测试(v2.40)

原生 get <包名>[@版本] [--仓库 网址] [--目录 项目根](自举发行版编译器;stage-0 zhc 不带): 从静态仓库下载并安装包;默认仓库 ZHLANG_仓库 环境变量或 https://pingsec.top/repo。仓库协议:

<仓库>/索引.json
<仓库>/包/<名>/<版本>/<文件>.tar.b64

索引.json(UTF-8):{"格式":1,"包":{"名":{"最新":"1.0.0","说明":"…", "版本":{"1.0.0":{"文件":"包/名/1.0.0/名-1.0.0.tar.b64","sha256":"…","编码":"base64", "依赖":{"其他包":"1.0.0"},"需要编译器":"2.40"}}}}}。sha256 是 base64 文本的 摘要(stage-0 C 运行时的哈希/字节数组按 C 串处理,二进制串会在 NUL 截断;base64 传输让 C 引导编译器与原生编译器行为一致)。依赖 递归安装;""/最新/^/~ 按仓库最新版本处理(v2.40 不做 semver 区间求值)。安装布局: <项目根>/包/<名>/…(ustar 内相对路径原样展开;拒绝绝对路径、..、反斜杠、 盘符与符号链接以外的条目),并合并写 zh包.json(依赖)与 zh包锁.json (精确版本 + sha256)。

测试框架:标准库/测试.zh(可引入)提供 测试套件(名)、测试(套, 名, 体)、 运行(套, 用例表)、断言/断言真/断言假/断言相等/断言不等/断言近似、 报告(套)(返回失败数)。体 可为无参函数或函数数组;断言失败抛可捕获错误, 由 测试 收集并继续。注意:块体箭头函数不能直接写在调用括号里(括号内换行被 忽略),多断言用 [() => 断言…, () => 断言…] 或先赋给变量。

环绕运算:数学.环绕加/环绕减/环绕乘 提供显式模 2^64 运算,不触发「整数溢出」。

@引入 "测试.zh" 只 测试套件, 测试, 断言相等, 报告
变量 t = 测试套件("示例")
测试(t, "相等", [() => 断言相等(1 + 1, 2, "1+1")])
如果 报告(t) != 0
    抛出("测试失败")