zhlang 语言规格(规范)

zhlang 是一门中英混合关键字的动态类型语言:手感取 Python 的简易(动态类型、缩进块、模板字符串、真值规则),并发取 Go 的轻量(协程 + 通道),并支持 C 风格指针。源码由纯 zhlang 自举编译器直接生成原生二进制,无需任何外部工具链。

• 中文与英文关键字完全等价,可混用(变量 x = 1 = var x = 1;常量/const 同理)。
• 文件扩展名 .zh,源文件为 UTF-8(允许开头 BOM)。

1. 词法

1.1 字符集与标识符

• 源文件必须是合法 UTF-8,否则报错。
• 标识符:以 ASCII 字母、_ 或 CJK 表意字符(U+3400–4DBF、U+4E00–9FFF、U+F900–FAFF)开头,后接上述字符或数字。中英文关键字与标识符按「整词最长匹配」:先扫出完整标识符串,再查关键字表。因此:
  • 否则如果 是关键字(elif);单独 否则 是关键字(else);
  • 如果x 是一个标识符,不是「如果 + x」——关键字后跟标识符时必须留空格(如 如果 x);
  • 变量x 同理是一个名为「变量x」的标识符。
• 整数字面量:十进制,64 位有符号(9223372036854775807 以内),越界报「整数太大」;另支持 0x/0X(十六)、0b/0B(二)、0o/0O(八)进制,满 64 位按二补数解读(0xFFFFFFFFFFFFFFFF = -1,遮罩友好);数字间可夹 _ 作分隔(1_000_000,解析时忽略)。
• 浮点字面量:1.5、2e5、1.5e-3;禁止 1. 与 .5(报错)。
• 字符串字面量:"...",转义 \n \" \\ \t \r;未知转义报错(报文会提示正则等场景改用原始字符串);字符串内可含真实换行。
• 原始字符串:r"..."——反斜杠一律原样保留(写正则模式的惯用形式),\" 只用于「不结束字面量」且反斜杠仍留在值里(与 Python 同规则:r"引号\"内侧" 的值是 引号\"内侧);未闭合报「原始字符串未闭合」。
• 模板字符串:反引号 包裹,字面部分仅支持 \ 与 \${ 两个转义(其余反斜杠按字面处理);${表达式} 插值,表达式内可嵌套任意表达式并跨行(其中的换行被忽略),花括号配对到与之匹配的 }。
• 注释:// 到行尾(换行符本身保留为语句分隔);/* ... */ 块注释(内部换行不产生语句分隔),未闭合报错。
• 分号 ; 等价于一个换行。

1.2 换行敏感规则(语句分隔)

词法先产生独立的「换行 token」(连续换行与空行折叠为一个;; 亦产生换行 token;EOF 前补一个),随后做过滤遍,删除满足以下任一条件的换行 token:

1. 前一个 token 是 + - * / % < <= > >= == != && || ! &、=、,、.、(、[、{,或关键字 与/或/非/从/到(即行尾是「期待后续」的位置;|/^/~/<</>> 与 : 不在其列);
2. 下一个 token 是 )、]、}、否则、否则如果、从、到;
3. 当前处于括号深度 > 0(小括号、方括号、花括号或模板插值内)——因此数组/字典字面量与索引可跨多行书写。

保留下来的换行即语句分隔符。语义后果(Go 同款取舍):

• 下一行以二元运算符开头时,不会自动续行:变量 a = 1\n+2 中 +2 是非法表达式语句;
• 返回\nx 视为无返回值的 返回(想返回下一行的表达式,写 返回 ( 换行 x) 或同一行)。

1.2.1 缩进块(Python 式)

块由行首缩进表示,不使用花括号(花括号用于字典字面量、结构体声明的字段表与命名构造;语句位置出现的 {/} 会得到引导性报错):

• 缩进可用空格或制表符 Tab:空格算 1 列,Tab 跳到下一个 8 列制表位(Python 同款);每层缩进的宽度不必统一,只需严格「更深层更多」。空格/Tab 混用时按视觉宽度比较,宽度相同即同一层。
• 块 = 头部行(如 如果 条件)行尾换行 + 缩进增加 + 语句序列 + 缩进退回;缩进与既有任何层级都不匹配 → 报「缩进与之前的层级都不匹配」;
• 块不能为空;EOF 自动闭合全部层级。
• 可选冒号(Python 风格):块头部行的条件/表达式之后可写可选冒号 :,与换行等价——如果 x > 0: ≡ 如果 x > 0。支持位置:如果/否则如果/否则、当、循环(含 在 遍历与 从…到…)、尝试/捕捉/最终、选择 及其臂(接收/发送)。冒号后必须换行缩进,不支持单行块。

1.3 非法字符与友好提示

• 全角标点(,、;、:、(、)、"、'、、、。、!、? 等)逐项报错,如:「非法字符「,」,请使用半角 ','」。
• 语句位置的 }:「本语言用缩进表示块」;. 仅用于模块.函数() / 对象.方法() 限定调用与字段访问,其余位置报错。
• 其他非法字节:报「非法字符」并显示该 Unicode 码点。

1.4 运算符与优先级(从低到高)

复合赋值:+= -= *= /= %= &= |= ^= <<= >>=(目标子表达式只求值一次)。 二元运算符一律左结合。=>(箭头函数)不出现在上表:它只能在表达式开头(primary 位置)出现,函数体向右贪婪延伸到最近的括号/逗号边界,或在 => 后以换行+缩进给出语句块体(见 §2.5)。

2. 类型与值(动态)

运行时值共十种:

2.1 运算语义

• +:两侧均为数值 → 加法(int/float 混算升为 float);任一侧为字符串 → 拼接,另一侧自动转字符串;两侧均为数组 → 拼接为新数组;数组与字符串/数值混搭、含布尔 → 运行时错误。
• - *:仅数值(布尔/字符串报错)。
• 整数溢出(v2.40 起默认检查):+ - * 与一元 - 的整数结果超出 int64 范围时,运行期抛「整数溢出」,不再静默回绕。需要显式模 2^64 环绕语义时用 标准库/数学.zh 的 环绕加/环绕减/环绕乘。% 的 INT64_MIN % -1 按数学值返回 0(不崩溃)。
• /:真除法,总是返回浮点(5 / 2 == 2.5);除数为 0(整数或浮点 0)→ 运行时错误「除以零」。
• %:取模,要求两侧均为整数;模 0 → 运行时错误「取模为零」。
• & | ^(位与/位或/位异或)、~(按位取反)、<< >>(左移/算术右移,符号扩展):要求整数(否则运行时错误),移位次数须在 0..63;复合赋值 &= |= ^= <<= >>= 同名支持。优先级(高→低):移位 > 比较 > 相等 > & > ^ > |(& 在双目位置是位与,单目位置仍是取地址;| 为位或,逻辑或用 或 或 ||)。
• 比较 < <= > >=:数值互比(混算按数值比较);字符串与字符串按码点序(即 UTF-8 字节序);其他混搭 → 运行时错误。
• == !=:同型比较(字符串按内容;通道/套接字按身份;int/float 按数值互比;数组/字典按深度比较——逐元素/逐键值递归,每层先做同一对象短路,循环引用因此终止,嵌套超 64 层视为不等;原型链不参与比较,继承对象只比自身条目);不同类型 == 恒为假(!= 恒为真),不报错。
• 逻辑运算对待操作数按真值规则,返回布尔值:与/或/非。
• 指针:&变量 取该变量槽的地址(只能对变量);*p 读取所指值;*p = 值 通过指针写入。指针 ==/!= 按地址比较;其他运算不支持。指针可存入变量、传参、放入通道。箭头成员访问:p->字段 ≡ 基若为指针先解引用一层、基若已是对象引用则直接使用,再取字段;p->方法(实参…) 同理(接收者为解引用后的对象);属性可赋值与复合赋值;可链式(p->a->b、f()->x),基可以是变量、函数/方法返回值或链式结果。与 C 相同的危险:指向已返回函数的局部变量是悬垂指针(未定义行为);GC 不追踪指针的目标生命周期(指针指向栈上的变量槽,本身不受回收影响)。

2.2 真值规则(Python 式)

2.3 转字符串(拼接、打印、转字符串 共用)

• 整数:%lld 十进制;浮点:最短往返表示(如 2.5、1e+20);
• 布尔:真 / 假;通道:「通道:0x…」;指针:「指针:0x…」;套接字:「套接字:N」;函数:<函数 名>(名 = 函数名或「匿名(第 N 行)」;原生后端函数值对象在 +24 保存编译期静态名字指针);字符串:原样。原生后端套接字即文件描述符整数,按整数打印(见 §6 网络内置说明)。
• 数组/字典:递归显示为 [1, "二", [3]]、{"名": "张三"}——嵌套在容器内的字符串带引号(顶层仍为裸文本);嵌套超过 8 层显示 [...] / {...}(循环引用安全)。

2.4 容器:数组与字典

数组 —— 有序、可变长、元素为任意值:

• 字面量 [e1, e2, …](元素间可跨行,见 §1.2);空数组 [];
• 读 a[i] / 写 a[i] = 值:下标须为整数;负数从尾部数(a[-1] 为末元素);越界 → 运行时错误「下标越界:N(长度 L)」;不自动扩容;
• 追加(a, v1, v2, …) 末尾追加(1 至 7 个值),返回数组本身;弹出(a) 移除并返回末元素(空数组 → 运行时错误);
• a + b 拼接为新数组,a、b 原样不变;
• 引用语义:变量 b = a 后 a、b 是同一个数组——对任一方的追加/索引赋值另一方可见;传参、放入通道同理。无拷贝操作(需要副本时用 + [] 或遍历构造)。

字典 —— 键值表,保持插入顺序:

• 字面量 {k1: v1, k2: v2, …};空字典 {};键限整数/浮点/字符串/布尔(其他类型 → 运行时错误「字典键不能是…」;-0.0 与 0.0 视为同键);
• 读 d[k]:键不存在 → 运行时错误「字典键不存在:…」;安全读取用 取(d, k[, 默认]);写 d[k] = 值:不存在即插入、存在即覆盖;删除(d, k) 移除键,返回 真/假(是否原本存在);删除不改变其余键的相对顺序;
• 键(d) / 值(d) 返回按键序的数组;包含(d, k) 查键(对数组则按值查)。

索引的统一规则:c[k] 对数组(整数下标)、字典(键)、字符串(按码点取单字符子串,只读——赋值 → 运行时错误)有效;其他类型 → 运行时错误「[]索引需要数组、字典或字符串」。

切片 c[起:止]:半开区间(起含、止不含);两端均可省略(s[:3]、s[3:]、s[:] 取全);负数从尾部数(与下标一致);越界钳位不报错,起 ≥ 止 得空;字符串按码点、数组按元素;其他类型 → 运行时错误「「[起:止]」切片需要字符串或数组」;端点非整数 → 运行时错误「切片端点需要整数」;切片不可作赋值目标(编译错)。数组切片产生新数组(元素按值引用语义,与数组赋值别名同款)。

字段访问(结构体糖):表达式.标识符 ≡ 表达式["字段名"](仅字典;字段名须为合法标识符,不能是关键字)——p.名字 读、p.年龄 = 值 写,与索引完全互通(遍历/深相等/键值照用);写字段不存在即新建键(动态语义)。对非字典容器/值 → 按统一索引规则报运行时错误;模块.函数 不带括号 = 函数值(见 §3.3);模块名下没有该函数/结构体 → 编译错。

对象.方法(…):与字段访问同源的语法糖,对象.方法(实参…) ≡ 对象["方法"](实参…)。resolve 期区分:点号前的名字是已引入模块 → 模块调用(模块名优先);否则必须是变量(对象)→ 方法调用。被调值不是函数 → 运行时错误「调用了非函数值…」;参数个数在运行时检查(同其他间接调用)。

原型链(继承):继承(原型[, 添加字段字典]) 生成携带隐藏原型指针的新字典(参数非字典 → 运行时错误):

• 读走链:d[k]/d.字段/取/包含 在自身缺键时沿原型链向上找;链穷仍缺 → 按各自既有规则(索引报错 / 取 返回默认 / 包含 为假);
• 写落自身:d[k] = 值 永远写自身条目——自然覆盖原型中的同名项(影子语义),原型不受影响;
• 枚举只看自己:长度/键/值/循环 在 遍历/删除/JSON 编码/== 深相等只作用于自身条目;
• 带原型的字典恒为真(即使自身无字段);打印形如 {…} (原型 …);
• 原型指针隐藏且只读(无赋值语法),链因此不可能成环;继承(原型) 省略第二参等价于添加空字典。

类型判断:是(对象, 原型) —— 对象自身或原型链上任一节点与原型身份相同(指针相等,不按结构)→ 真;第一参非字典 → 假(类型探测);第二参非字典 → 运行时错误。是(狗, 狗) 为真(自包含)。

结构体(声明式):结构体 名 + 缩进块每行一个字段标识符,或花括号形式 结构体 名 { 字段, … }(两种等价;至少 1 个字段,不得重复;顶层声明,函数/模块文件均可)。花括号内换行被词法层忽略,字段以逗号或空白分隔。

• 构造:名(值1, 值2, …) —— 实参个数须等于字段数(编译期检查);字段按声明序填入,实例是携带字段校验标记的原型链字典(proto = 模板);
• 初始化方法(构造):类体内 函数 初始化(参数 [= 默认], …) 至多一个。构造 类名(实参…) 时先按字段声明填默认值/零值,再调用初始化方法,表达式结果恒为对象本身;初始化体内 返回 只能不帶值(带值编译错),参数默认值参与调用点补参,缺参/未知/重复参数为编译错;有初始化方法时命名构造的键对应初始化参数。子类初始化方法执行前自动调用父类初始化(参数按同名匹配,父类必填参数缺失则编译错);子类没有自己的初始化时继承父类签名。初始化方法挂载在隐藏名 __初始化_类名 上,不能显式 对象.初始化(…);构造经合成的 __构造_类名 工厂(跨模块构造同样可用,跨模块命名构造除外);
• 命名构造:名{字段: 值, …} —— 键为字段名(标识符或字符串字面量),顺序任意,不必写全;缺省字段补零值(假;类按字段声明补默认值/零值)。未知字段、重复字段为编译错;命名与位置构造不可混用。命名构造只支持本文件已声明的结构体/类(跨模块请用位置构造);解析期展开为普通构造调用,后续语义与位置构造完全一致;
• 字段校验:点写只能写声明过的字段,否则运行时错误「结构体「点」没有字段「zzz」」;点读缺字段同款专用错误;实例["字段"] 索引访问不经校验(原始字典语义,面向反射/克隆类代码);
• 模板是值:结构体名可作值/取模板;模板本身不受字段校验(可挂方法:点.移动 = 本 => …);
• 方法调用:p.移动(p)(显式传自身)或 p.移动()(声明参数数 = 实参数+1 时自动把 p 作为第一个参数传入);是(p, 点) 为真;继承(点, {字段…}) 得到校验延续的子对象;
• 模块:模块.结构体(值…) 构造、是(p, 模块.结构体) 判断均可用;
• 打印/枚举/深相等与字典一致(只看自身条目)。

类(脱糖为结构体,继承/封装/多态):类 名[(父类)] + 缩进类体;类体可直接写字段 名字 [类型] [= 默认](前缀可写 变量/常量/属性,三者目前等价:类字段脱糖为原型字典槽,不做只读强制),也可写实例方法 函数 方法(参数)(签名等价于 本 => 方法体,参数自动加上 本)。类体内的 @私有 表示整个类仅当前文件可用(与声明上一行的 @私有 同义)。

• 方法定义:类体内 函数 方法(参数) 为实例方法;顶层 @类方法(类名) + 函数 方法(参数) 等价;顶层 @类函数(类名) + 函数 函数名(参数) 为静态方法(不注入 本,以 类名.函数(实参…) 调用,参数个数须严格相等)。
• 继承:父类须先声明;子类字段 = 父类字段(按序)+ 自身字段;子类重写同名继承字段只改默认值、不改字段位置;类模板的原型指向父类模板,方法沿原型链查找,子类同名方法覆盖父类(多态);是(实例, 父类) 沿链为真。
• 构造:类名(实参…);缺省实参按字段默认值/零值自动补齐(无类型→假,数值/整数→0,浮点→0.0,字符串→"",数组/字典→空);字段仍可用点写/索引写。
• 调用:实例方法可写 对象.方法(实参…)(声明参数数 = 实参数+1 时自动传 本)或 对象.方法(对象, 实参…);静态方法只写 类名.函数(实参…)(也可选择性引入类后写 类名.函数(…))。
• 跨模块方法挂载(v2.23):顶层 @类方法(模块.类名) / @类函数(模块.类名) 可给已加载模块中的类挂实例/静态方法(模块写真实名或本文件 引入 … 为 的别名);解析期不要求类别在本文件声明,名字解析期校验目标是 类、非 @私有、非标准库模块;同一方法跨模块重复挂载为编译错,同一模块内重复保持后者覆盖。挂载语句在模块初始化阶段执行,所有类模板先于模块初始化创建。
• 模块:类可写在被引入的模块文件中(模块文件里允许的顶层语句仅限类方法挂载);模块.类(…) 构造与 模块.类.静态方法(…) 链式调用均支持(别名同样可用;链式只用于静态方法,实例方法仍写 实例.方法(…));也支持对模块做 只 类名 选择性引入后以 类名.函数(…) 调用。引入 … 为 别名 允许别名与该模块自身同名(冗余但无害,便于显式命名空间)。@私有 类不能被其他文件限定访问或选择性引入。

遍历:循环 x 在 容器 —— 数组遍历元素、字典遍历键、字符串遍历码点(单字符);循环变量在循环块作用域内;容器只求值一次;循环中修改容器是否影响本轮遍历不做保证(实现按长度快照遍历)。

2.5 一等函数与箭头函数

函数是值:可存入变量/容器、作参数与返回值、经任意表达式调用(f(3)、加(3)(4)、策略["加"](x, y)、列表[0](x))。

• 函数名作值:常量 f = 双倍(不带调用括号即函数值);模块.函数 与 @模块.函数 同样作值(可绑定/传参/回调)。内置函数不能作值(编译错,提示包一层箭头函数)。
• 箭头函数:x => 表达式、(x, y) => 表达式、() => 表达式(体为单个表达式,贪婪延伸到最近的括号/逗号边界);或 x => 后换行+缩进给出语句块体——显式 返回 返回值,无则落回假(与具名函数一致),体内可用全部语句(变量/常量/循环/尝试…)。参数上限 8 个。
• 捕获:箭头函数引用外层局部变量时默认按值绑定(创建那一刻的值);但被改写的捕获变量自动装箱为共享单元——该变量在闭包内或外层任一位置被赋值(含复合赋值)时,它存放在堆上单元里,外层与所有闭包读写同一单元:闭包里的改写外层可见,外层改写闭包也可见(按引用捕获;判定在编译期按「捕获 ∧ 被赋值」静态做出,与执行路径无关)。捕获容器(数组/字典)时拷贝的始终是引用——函数值与外层共享同一容器。循环中每次创建仍绑定当次的值:被改写的循环变量(区间/遍历)每轮换一个新单元。捕获上限 8 个(与参数合计 ≤ 8,超出 → 编译错)。
• 调用:间接调用在运行时检查——被调值不是函数 → 「调用了非函数值(收到 类型)」;参数个数不符 → 「函数「名」需要 N 个参数(实际 M 个)」(直接调用命名函数仍在编译期检查)。实参求值顺序不做保证。
• 相等与显示:==/!= 按身份比较(同一函数值相等;两次创建的箭头函数即使文本相同也不等);转字符串为 <函数 名>。
• 启动 仅支持命名函数(不能 启动 f(…) 其中 f 为函数值);箭头函数值可作为普通参数传入被启动的函数。

3. 语句与程序结构

3.1 BNF 文法

(* v2.23 修订:按自举版实现补齐裸名引入、跨模块类方法挂载、
   选择、切片、位运算与类体;模块文件的顶层限制见 §3.3。 *)

program   ::= { import | decl | stmt }
import    ::= "@" ("引入"|"import") (STRING | IDENT)
              [ "为" IDENT | "只" IDENT { "," IDENT } ]
              (* 必须写在其他顶层内容之前;裸名 ≡ "名字.zh";见 §3.3 *)

decl      ::= [ annotation ] ( funcdef | structdecl | classdecl )
annotation::= "@" ("私有"|"private")
            | "@" ("类方法"|"类函数") "(" [ IDENT "." ] IDENT ")"
              (* 一条声明至多一个注解;类方法/类函数只能修饰紧随其后的
                 顶层 函数,且不得与「函数 类名:方法」旧写法连用;见 §3.2 *)

funcdef   ::= ("函数"|"func") IDENT [ ":" IDENT ] "(" [ params ] ")" [ ":" ] block
              (* 旧写法「函数 类名:方法(…)」;普通函数参数无默认值,最多 8 个 *)
params    ::= IDENT { "," IDENT }

structdecl::= ("结构体"|"struct") IDENT
              ( structfields | "{" IDENT [ "," ] { IDENT [ "," ] } "}" )
structfields ::= 换行 缩进↑ { IDENT } 缩进↓                  (* 至少 1 个字段 *)
              (* 花括号体内字段以逗号或空白分隔,允许尾逗号;见 §2.4 *)

classdecl ::= "类" IDENT [ "(" IDENT ")" ] [ ":" ] classbody     (* 仅中文;class 未支持 *)
classbody ::= 换行 缩进↑ { classmember } 缩进↓               (* 至少 1 个字段 *)
classmember ::= "@" "私有"                                   (* 整个类仅本文件可用;
                                                              规范写法是类声明上一行 @私有;
                                                              类体内不接受英文 private *)
              | [ "属性" | "变量" | "常量" ] IDENT [ IDENT | "函数"|"func" ] [ "=" expr ]  (* 字段;第二个 IDENT 是类型标注 *)
              | ("函数"|"func") "初始化" "(" [ initparams ] ")" [ ":" ] block
              | ("函数"|"func") IDENT "(" [ params ] ")" [ ":" ] block
initparams::= IDENT [ "=" expr ] { "," IDENT [ "=" expr ] }  (* 仅初始化方法支持默认值 *)

stmt      ::= "@" ("断点调试"|"调试断点"|"breakpoint") [ "(" [ args ] ")" ]
              (* 调试指令;仅原生后端 --debug/-d 构建生效,见 §6.10 *)
            | ("变量"|"var"|"常量"|"const") IDENT [ IDENT | "函数"|"func" ] "=" expr
            | assign_target ( "=" | AUGOP ) expr
            | "*" expr "=" expr                               (* 指针写入;仅普通 = *)
            | ("启动"|"go") [ "@" ] [ IDENT "." ] IDENT "(" [ args ] ")"
              (* 带 @ 时必须写 模块.;只能启动自定义函数(含 模块.函数),
                 不能启动内置函数、函数值或类方法;见 §2.5 *)
            | ("如果"|"if") expr block
                { ("否则如果"|"elif") expr block }
                [ ("否则"|"else") block ]
            | ("循环"|"for") IDENT ("从"|"from"|"=") expr ("到"|"to") expr block
            | ("循环"|"for") IDENT ("在"|"in") expr block
            | ("当"|"while") expr block
            | ("尝试"|"try") block [ ("捕捉"|"catch") IDENT block ]
                  [ ("最终"|"finally") block ]                (* 捕捉/最终至少一个 *)
            | ("返回"|"return") [ expr ]
            | ("跳出"|"break") | ("继续"|"continue")
            | selectstmt
            | expr                                            (* 仅函数调用可作表达式语句 *)

selectstmt::= ("选择"|"select") 换行 缩进↑ { selectarm } 缩进↓
selectarm ::= "接收" expr [ "为" IDENT ] block
            | "发送" expr "," expr block
            | ("否则"|"else") block                          (* 必须最后;1..8 个臂 *)

assign_target ::= IDENT { "." IDENT | "[" expr "]" }
                  (* 变量/索引/字段写入,可复合赋值;切片不可作赋值目标;
                     指针写入是单独的「* expr = expr」形式,不支持复合赋值 *)
AUGOP     ::= "+=" | "-=" | "*=" | "/=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>="

block     ::= 换行 缩进↑ { stmt } 缩进↓
args      ::= expr { "," expr }
namedarg  ::= (IDENT | STRING) ":" expr

expr      ::= or
or        ::= and { ("或"|"or"|"||") and }
and       ::= bitor { ("与"|"and"|"&&") bitor }
bitor     ::= bitxor { "|" bitxor }
bitxor    ::= bitand { "^" bitand }
bitand    ::= eq { "&" eq }
eq        ::= rel { ("=="|"!=") rel }
rel       ::= shift { ("<"|"<="|">"|">=") shift }
shift     ::= add { ("<<"|">>") add }
add       ::= mul { ("+"|"-") mul }
mul       ::= unary { ("*"|"/"|"%") unary }
unary     ::= ("!"|"非"|"not") unary | "-" unary | "~" unary
            | "&" IDENT | "*" unary | postfix   (* & 只能对变量取地址 *)

postfix   ::= primary { "[" expr "]"                        (* 索引 *)
                     | "[" [ expr ] ":" [ expr ] "]"        (* 切片:至少一个冒号 *)
                     | "." IDENT                           (* 字段访问;点号后不接 ( *)
                     | "->" IDENT [ "(" [ args ] ")" ]     (* 指针/对象成员;方法可带调用 *)
                     | "(" [ args ] ")" }                  (* 间接调用 *)
primary   ::= INT | FLOAT | STRING | TEMPLATE
            | ("真"|"true") | ("假"|"false")
            | "[" [ args ] "]"                              (* 数组字面量 *)
            | "{" [ expr ":" expr { "," expr ":" expr } ] "}"  (* 字典字面量 *)
            | "(" expr ")"
            | IDENT
            | IDENT "(" [ args ] ")"                        (* 调用 *)
            | IDENT "{" [ namedarg { "," namedarg } ] "}"   (* 命名构造 *)
            | [ "@" ] IDENT "." IDENT "(" [ args ] ")"      (* 模块.函数 / 对象.方法 / @模块.函数 *)
            | [ "@" ] IDENT "." IDENT "." IDENT "(" [ args ] ")"  (* 模块.类.静态方法 *)
            | [ "@" ] IDENT "." IDENT                       (* @模块.名字 / 模块.类 值 *)
            | IDENT "=>" arrowbody                          (* 单参箭头函数 *)
            | "(" [ IDENT { "," IDENT } ] ")" "=>" arrowbody  (* 零参/多参箭头函数 *)

arrowbody ::= expr | block

3.2 语义细则

• 顶层语句即 main:全部顶层语句构成主协程体;顶层 返回 N(N 为整数)设置进程退出码;自然结束退出码 0;非整数返回值 → 运行时错误「退出码需为整数」。
• 可选入口函数 main/主函数:入口模块可定义一个无参函数 main 或 主函数(不能同时定义,否则编译错「入口函数「main」与「主函数」只能定义其一」)。若入口模块没有顶层可执行语句(导入、函数/结构体/类声明、顶层 变量/常量 声明与类方法挂载不算),程序初始化完成后自动调用该函数;若存在顶层可执行语句,则照常执行顶层语句,该函数不自动调用(仍可手动调用)。将被自动调用而函数带参数 → 编译错「入口函数「main」不能有参数」;入口函数返回整数时该值作进程退出码(非整数或无返回值按 0)。被引入模块中的同名函数不受此规则影响(普通函数)。
• 作用域:块级作用域,内层可遮蔽外层;同一作用域重复声明(变量/常量)报错;赋值给未声明变量报错(提示改用 变量 x = … / 常量 x = …)。函数参数在函数体最外层作用域。模块级全局变量(v2.31,原生后端):入口模块顶层声明的 变量/常量 对所有具名函数、类方法与闭包可见,并共享同一存储——读到的是当前值,闭包/类方法按地址捕获而非创建时快照;函数参数或局部变量同名时遮蔽全局。全局声明先扫描、后解析函数体,因此函数可以在声明语句之前引用全局(调用发生在初始化之后即可)。被引入模块只能包含函数/结构体/类与类方法挂载,不能声明模块级变量。
• 变量与常量:变量 x = 值 声明可变绑定;常量 x = 值 声明不可变绑定 —— 声明后对名字本身再赋值(含复合赋值)或 &x 取地址 → 编译错(「常量「x」不能再赋值」/「不能对常量「x」取地址」)。绑定不可变 ≠ 内容不可变:常量 名单 = [1] 之后 名单[0] = 9、名单.字段 = 值 均合法。常量性随闭包捕获传播:闭包体内对捕获常量的赋值同样编译错。
• 类型标注(可选):声明可写一个类型位 —— 十个内置:整数/浮点/字符串/布尔/通道/数组/字典/套接字/函数/指针;或结构体名(变量 p 点 = 点(3, 4),按原型链判实例)。校验在运行时:声明与每次赋值(含复合赋值)后检查,不符 → 运行时错误「类型标注不符:声明为 整数,得到的是 字符串」(带行号)。整数 与 浮点 不互通(标注即约束);不写类型 = 完全动态、零开销。
• 接口(v2.25,原生后端):顶层 接口 名字[(父接口, …)] 声明纯方法签名,如 接口 读: / 读(路径 字符串);方法行可省略 函数,@私有 写在接口声明上一行或接口体内表示仅本文件可用,父接口须先声明且方法集合并(同名子方法覆盖)。接口没有实现体,也不需要在类上写 implements——任何对象(字典,方法沿原型链查找)只要含有全部同名方法就满足接口(Go 式结构化):方法参数个数须等于签名个数,或等于签名个数 + 1(类方法带隐式 本)。检查发生在 变量 x 接口名 = 值 / 赋值与 是(值, 接口名) 处,不满足 → 运行时错误「类型标注不符:要求接口「X」…」或「…未实现接口「X」的方法「M」」。接口签名里的参数类型不参与匹配,由实现函数自己的参数标注在调用入口检查。接口方法按接口整体可见性处理(接口方法默认公开,不做逐方法可见性);跨模块用 @引入 … 只 接口名 引入,类型位只接受单个标识符(不支持 模块.接口 限定标注)。
• 参数类型标注(v2.25,原生后端):函数、类方法、接口方法的参数可写 名字 类型(类型名同变量标注:内置类型、结构体名或接口名);被调函数入口处检查,不符 → 运行时错误「类型标注不符:声明为 X,得到的是 Y」。参数类型只影响调用入口,函数值对象的元数据仍只有参数个数。
• 函数:先扫描全部函数签名再检查函数体,因此递归、互递归、先使用后定义均合法。参数按值传递(zhv_t 装箱值)。函数与内置函数重名、函数重名 → 编译错。调用时参数个数不符 → 编译错(间接调用经函数值的,在运行时检查,见 §2.5)。
• 启动:只能启动自定义函数,立即返回、并发执行(见 §5)。
• 循环:循环 i 从 A 到 B {} —— A、B 在进入循环时求值一次,须为整数(否则运行时错误「循环边界需要整数」);A ≤ B 时步长 +1、A > B 时步长 −1,两端均含(A=1,B=3 → 1,2,3);循环变量 i 在循环块作用域内,遮蔽外层同名。循环 x 在 容器 {} 见 §2.4。
• 跳出/继续只能在循环体内使用,否则编译错;继续 语义为「先步进,再进入下一轮」(计数循环先自增、遍历循环先前进——不会跳过步进)。
• 空语句(连续分隔符)允许。
• 函数自然结束(未执行到 返回)相当于 返回 假;顶层无值的 返回 等价于退出码 0。

3.3 模块系统(@引入)

• 引入语句:顶层 @引入 "路径.zh"(英文 @import;路径为字符串字面量)或裸名标准库引入 @引入 名字(名字为合法标识符,不带引号与 .zh,等价于 @引入 "名字.zh"),必须写在文件顶部、其他顶层内容之前;可出现于入口文件与模块文件。裸 引入 已退役:写出即编译错「引入」已改名:请写「@引入」。
• 路径解析:相对引入文件所在目录(绝对路径直接使用);文件不存在 → 编译错。裸名引入先按相对路径找同名 .zh;找不到再走标准库查找路径(见下),仍找不到报「无法打开」。
• 去重:按真实路径(realpath)去重——重复引入、菱形引入(两个模块引入同一个第三方)幂等;互相引入合法(模块顶层只有声明与类方法挂载;全部结构体/类模板先创建,挂载在模块初始化阶段执行)。
• 模块名 = 文件名去掉 .zh 的基名,须为合法标识符(否则编译错);不同文件同名模块 → 编译错。
• 模块文件的顶层内容只能 @引入、函数/结构体/类声明、类方法挂载(@类方法/@类函数 修饰的顶层函数);其余可执行顶层语句仅入口文件允许(入口顶层构成 main)。
• 可见性(默认公开):声明上一行写注解 @私有(@private)——被注解的函数/结构体/类仅本模块可见(类也可在类体内写 @私有,整个类生效);模块外限定访问(库.内部()/@库.内部())与选择性引入都会报编译错;未知注解报错。
• @ 限定简写:@模块.函数(…) ≡ 模块.函数(…),@模块.结构体/@模块.类 作模板值;启动 @模块.函数(…) 同义。模块名/别名不存在 → 编译错(不像 x.y() 那样回退为对象方法)。
• 别名:@引入 "路径.zh" 为 短名——本文件内用短名限定调用;别名不得与任何已加载模块同名、同文件内不得重复。
• 选择性引入:@引入 "路径.zh" 只 名字, 名字…——列出的函数/结构体/类在本文件内非限定可用(模块限定访问仍可);名字须存在且公开,不得与本模块声明重名;为 与 只 互斥。
• 调用:模块.函数(…) 限定调用(. 仅此用途;启动 模块.函数(…) 同样支持);非限定调用解析内置函数、本模块函数与选择性引入的名字——其余模块函数必须写限定名。
• 函数作值:模块.函数 与普通函数名一样可作一等值(绑定/传参/回调);模块.结构体 作模板值。
• 传递可见:经引入(含传递引入)加载的全部模块都可用限定名访问。
• 隐式标准库(v2.11):编译器隐式装载一批 zhlang 源模块(标准库/字符串.zh、编码.zh、容器.zh、数学.zh、摘要.zh),其公开函数在全部模块中非限定可用,语义与原内置完全等价:名字保留(不可重定义、不能当值、启动 拒绝、参数个数按内置式文案报错);§6 中实现于标准库的条目即由它们承接。标准库模块名不可被用户模块占用:撞名 → 编译错模块名「X」与内建标准库模块同名(该名字保留)(把 标准库/*.zh 自身当入口编译时跳过该项,供对拍/自测)。
• 标准库按需发射:隐式标准库模块整模块粒度按需生成——只有被引用的模块(非标准库模块直接引用,或沿已发射的标准库模块传递引用)才进入产物;未被引用的模块不生成任何函数/结构体。函数编号与用户代码段不受影响,产物行为不变(不调用任何迁移内置的程序,其产物与 ZHC_NO_STDLIB=1 逐字节相同)。
• 标准库模块查找路径(v2.11):标准库模块按相对路径装载(标准库/名字.zh),磁盘查找次序:ZHC_STDLIB 环境变量(目录;内嵌/0 = 强制内嵌)→ <编译器目录>/标准库/… → <编译器目录>/../share/zhlang/标准库/… → /usr/local/share/zhlang/标准库/… → 编译器内嵌文本(发行版把标准库文本内嵌,缺目录也能编译)。用户写裸文件名引入(如 @引入 "集合.zh",不含 /)且相对本文件打不开时,自动落到同一条查找路径(再退内嵌);仍找不到报原来的「无法打开」编译错。
• 标准库模块可以相互 @引入(2026-10-30):磁盘态按引入文件所在目录解析(如 标准库/数据库.zh 里的 @引入 "同步.zh" → 标准库/同步.zh);内嵌态(干净房)按模块名从内嵌清单解析,因此发布件拷到没有 标准库/ 的目录也能装载整条依赖链。tools/mkstd.sh 允许标准库文件含 @引入(仍禁止顶层可执行语句)。
• 网络命名空间(v2.23):可引入模块 标准库/网络.zh 提供 网络.取网页、网络.网页请求、网络.连接到、网络.套接字发送、网络.套接字接收、网络.关闭套接字、网络.监听、网络.接受连接 等同名包装(完整参数变体见模块内注释);包装体用英文别名调用内置。完整编译器/自举编译器可用;原生后端三端也已实现:Linux 纯 syscall(套接字为 fd 整数,DNS 内置,HTTPS 经 curl),Windows WinSock(套接字为 SOCKET 句柄,DNS 用 gethostbyname,HTTPS 经 WinHTTP)。v2.39 扩展:网络.zh 增加网址工具(解析网址/拼查询)、HTTP 客户端便利函数(取网页跟随/网页请求跟随[最多]/取JSON/提交表单[完整]/提交JSON[完整]/请求头/下载)、TCP 读取(读全部[最多])与 Cookie 文本工具(解析Cookie/Cookie头)。新可引入模块 标准库/网络增强.zh 封装 域名解析、UDP 三件套、套接字设超时、本端地址/对端地址、关闭写端 及 UDP请求[超时];这些内置只由原生后端实现,C 引导器/自举 编译主 不提供。
• 服务框架网络扩展(v2.39):标准库/服务.zh 请求字典带 连接(原始套接字)与 余(请求解析后剩余缓冲);处理函数置 请求["接管"] = 真 后框架不再写 HTTP 响应、直接结束该连接(供 WebSocket 等自行握手)。新增 multipart/form-data 解析(表单文件 → {"字段", "文件"},表单值/上传文件 便捷取值)与 SSE(事件流(渲染器),配合 发事件/发事件名/发事件编号/发注释)。
• 编译仍为单二进制:用户模块的函数全部生成,隐式标准库模块按需发射(见上);--emit-c 输出自包含单文件 C。

3.4 异常处理(尝试/捕捉)

• 语法:尝试 块 [捕捉 错误变量 块] [最终 块];捕捉 与 最终 至少有一个(不能只有尝试);错误变量在捕捉块作用域内,遮蔽外层同名。
• 可捕获的错误:全部运行时错误——越界、除零、键不存在、类型错误、文件读失败、向已关闭通道发送、循环边界非整数……;抛出(值) 主动抛出(非字符串自动转字符串,英文别名 raise)。
• 抛出对象(值)(英文 raiseobj)——主动抛出并保留原值;捕捉变量得到该值本身(例如字典/类实例),不做字符串转换。运行时错误与普通 抛出 仍产生字符串。
• 捕捉变量:普通错误/抛出 得到错误消息字符串(纯消息,不含「运行时错误(第 N 行):」前缀);抛出对象 得到原值。
• 未捕获:打印 运行时错误(第 N 行):消息(stderr)并退出码 1——与没有尝试时完全一致。
• 不可捕获的致命错误(直接终止,不经尝试):内存不足、协程栈溢出、死锁检测、退出码非整数。
• 最终 块:离开尝试语句的每条路径都会执行最终块——正常完成、异常被捕捉、异常未被捕捉(先执行最终块再按原行号重抛)、返回、跳出、继续。执行顺序是「尝试体/捕捉体 → 最终块」。最终块内的 返回/抛出/跳出/继续 会覆盖原先的退出路径。最终块不能访问捕捉变量(捕捉作用域在它之外)。
• 跨函数抛出 ✓;嵌套尝试 ✓(内层先接;捕捉体内再 抛出 传播到外层)。
• 协程语义(与 Go 的 panic 相同):每个协程有自己的尝试帧链;某协程内未捕获的抛出终止整个进程——主协程的尝试接不到其他协程的抛出。
• 后端:最终 在自举编译器与纯 zhlang 原生后端(x86_64 ELF/PE、aarch64 ELF)均可用(先弹处理者帧再执行最终块,最终块里的退出不会留下悬空帧;aarch64 自 v2.23 跨自举验证起支持)。
• 返回/跳出/继续 穿出尝试块时,尝试帧自动回退(弹帧)。
• 实现:跳转帧串在协程上;自管 zh_setjmp/zh_longjmp(裸函数汇编,与协程切换同款)——不用 CRT 的 setjmp/longjmp:真 Windows 上 msvcrt 的 longjmp 会走 SEH 栈展开(RtlUnwindEx),而协程栈自管、tcc 产物无 .pdata,展开会把进程打成 0xC00000FD/0xC0000028;含尝试的函数其局部变量生成 volatile(跳转跨越赋值点后按下标访问的语义要求,与 setjmp 同规)。

3.5 文档注释与 HTML 文档(v2.28 增补)

• 文档注释是 /** … */ 块注释;/* … */ 与 // 仍是普通注释,不进入文档。
• 位置:紧邻声明(函数/类/结构体/接口/类方法),中间只允许空行、// 注释与

@私有/@类方法/@类函数 注解。文件首个注释块(其后跟空行或非声明内容) 视为模块文档;紧跟声明的注释块归属该声明。

• 标签(中英等价):@作者/@author、@时间/@date、

@说明/@description、@参数/@param 名 说明、@返回/@return、 @示例/@example、@弃用/@deprecated。未加标签的行归入说明; @示例 之后到下一个标签之间的行原样作为代码块。

• 生成器:tools/文档生成.zh(纯 zhlang,依赖标准库 网页):

sh build/原生 tools/文档生成.zh 源1.zh [源2.zh …] -o 文档.html \ [--布局 自动|桌面|移动] [--含私有] [--仅文档]

输出自包含单文件 HTML(内联 CSS/JS、viewport、深色模式、侧栏导航、符号搜索, 锚点 #sN,sN 按文件/声明顺序全局编号)。布局:自动 窄屏折叠为单列, 桌面 固定双栏,移动 强制单列。默认跳过 @私有 声明与私有类的成员; --含私有 包含它们,--仅文档 只输出有文档注释的符号。

• 文档注释对编译器是普通注释,三端编译器均可编译含文档注释的源码;生成器本身

需要原生后端运行。生成器按行扫描:签名取声明首行,结构体字段与接口方法暂不 单独列卡片。

3.6 装饰器(原生后端,v2.34 增补)

仅原生后端(x86_64/aarch64/PE)支持;冻结的 C 版引导器与 自举/ 源码不可使用。

• 声明装饰器:@装饰器 修饰紧随其后的顶层函数声明。该函数第一个参数是「被装饰的函数值」,必须返回一个函数值:

zh @装饰器 函数 计时(f) 返回 (x) => 常量 起 = 当前时间() 常量 结果 = f(x) 打印("耗时", 当前时间() - 起) 返回 结果 可与 @私有 叠加;装饰器名不得与内置 @ 指令重名(如 私有/引入/类方法)。

• 使用:@名字、@模块.名字、@名字(实参) 紧邻顶层函数声明;可栈式,表达式自上而下求值、应用自下而上(f = 甲(乙(原f)),只求值一次)。
• 应用时机:模块初始化(结构体/类模板与类方法挂载之后、入口代码之前)。每个被装饰函数有隐藏函数值槽位;对公开名的直接调用、取函数值与递归都走槽位(即装饰后的函数)。
• 限制:不能装饰类方法/类/箭头函数;装饰器不改变「最多 8 个位置参数、无变参」约束;装饰器返回值不是函数 → 运行时错误 装饰器「名」没有返回函数;未知名字 → 编译错 未定义的装饰器「名」;普通函数直接放在 @ 位置 → 编译错(缺少 @装饰器 标记)。

4. 关键字全表(中英 → 同一 token)

以下按上下文识别的软关键字词法上仍是标识符,不占关键字 token:类(类声明)、类方法/类函数(方法挂载注解)、属性(类字段前缀)、初始化(构造方法名)、接收/发送(选择臂)、为(模块别名/选择绑定)、只(选择性引入)——以上均无英文别名。另有 私有 也是软关键字,英文别名 private 只在顶层注解位置可用(类体内只认 @私有)。

@ 不是关键字而是注解/限定前缀:@私有(声明上一行,仅本模块可见)、@引入(唯一导入写法;裸 引入 已退役)、@模块.名字(≡ 模块.名字,含 启动 @模块.函数(…))。

5. 并发模型(协程 + 通道)

5.1 协程

• 启动 f(参数):创建协程立即返回;参数值在启动时拷贝传入。
• 主协程返回即进程退出(退出码取主协程返回值),不等其他协程——与 Go 相同。
• 实现:M:N 调度(C 运行时与原生运行时都是:每 worker 一个 OS 线程、全局就绪队列、

协程可跨 worker 迁移;分点式抢占是 C 运行时的实现,原生运行时在分配点/循环回边 做 GC 安全点,不做节拍式抢占)。每个协程独立 mmap 栈(4MB;并行代码生成的递归帧所需); worker 线程数 = CPU 核数(2..8,ZHC_THREADS 可覆盖)。

• 分点式抢占(v2.2):编译器在循环回边插入分点,运行库在长循环(排序/映射/过滤/归约)里也插分点;

分点按节拍(每 256 次)做一次调度节拍——唤醒到期睡眠者,并在有其他协程在等 worker(就绪队列非空)时让出, 由当前 worker 把本协程重新入队(轮转到队尾)。因此忙协程占满全部 worker 时,睡眠协程与长运算协程仍能推进; 「一个协程、就绪队列为空」的常见形态只做一次加锁检查,不产生额外切换。 持运行库锁时绝不让出(打印的输出锁等),避免让出把别的 worker 锁死。留白:不含信号式异步抢占 ——单个分点之间不被打断(例如一次超大分配、一次超长正则回溯)。

• 协程结束后栈不再使用(C 运行时随即释放;原生后端当前保留栈块不复用——只是虚拟预留,堆统计 的 栈字节 可见,堆用量 不计入);函数序言检查协程栈限(协程结构 +408,= 栈基 + 256KB 余量)

→ 越限时报不可捕获的运行时错误「协程栈溢出」;三端同款,不依赖守护页/信号。 (协程栈 4MB;主协程 256MB——只是虚拟预留、 按需提交,普通程序只碰几页;留这么大是为了「用 zhlang 写编译器/解析器」这类深递归程序)。

5.2 通道

• 通道() 无缓冲;通道(n) 容量 n(n 为非负整数)。缓冲满/空分别阻塞发送/接收。
• 发送(ch, v) 阻塞发送,返回 v 本身;向已关闭通道发送 → 运行时错误「向已关闭的通道发送」。
• 接收(ch) 阻塞接收;通道已关闭且已空时返回 假(注意:这与合法值 假 无法区分——需要区分时用关闭方先发哨兵值的约定,已知设计取舍)。
• 关闭(ch):幂等;缓冲中未取走的值仍可继续 接收 直到取空。
• 通道值(含缓冲中的值)可跨协程共享;发送/接收/关闭本身有内部锁保证线程安全。

5.3 选择(多路通道等待)

选择
    接收 ch1 为 v
        …使用 v…
    接收 ch2
        …丢弃收到的值…
    发送 ch3, 值
        …
    否则
        …都未就绪时的分支(可省)…

• 臂形态:接收 通道 [为 变量](变量在臂块作用域)、发送 通道, 值、否则(必须是最后一个臂,可与任意臂共存);至少 1 个臂,至多 8 个。
• 语义:各臂按下标顺序检查就绪性,只执行其中一个;多个臂同时就绪时随机执行其一(Go 语义——已关闭的接收臂恒就绪,若固定取源码序首个会饿死其他臂;任一臂内可 跳出/继续 外层循环、返回、尝试);
  • 接收臂就绪:无缓冲有发送方/缓冲非空/通道已关闭(得 假);
  • 发送臂就绪:缓冲有空位/无缓冲有接收方;指向已关闭通道发送 → 运行时错误;
• 无臂就绪且无 否则 → 挂起等待,任一通道有动静即被唤醒重查(与普通收发同款);
• 无臂就绪且有 否则 → 立即执行否则臂(非阻塞语义);
• 全协程都阻塞在等待时同样触发死锁检测报错;
• 各臂的通道与值表达式先全部求值一次再进入等待。

5.4 内存管理(自动垃圾回收)

• 堆:字符串、通道、数组与字典为堆对象,由标记-清除 GC 自动回收:
  • 触发:堆用量超过预算(初始 32MB;每次回收后预算 = max(存活 × 2, 32MB));
  • 停止世界:安全点设在——每次堆分配、循环回边(编译器插入)、通道操作、休息;所有 worker 停稳后回收;
  • 根集合:各协程的活跃栈帧(保守扫描:自挂起点到栈顶——栈自顶向下生长,挂起点即活跃区最低端)+ 协程挂起时的 ucontext 保存寄存器 + GC 发起线程停世时的被调用者保存寄存器冲刷(x19–x30/d8–d15 或 rbx…r15)+ 调度器持有的通道等(精确);
  • 通道缓冲、数组元素、字典键值内的值按图精确扫描;循环引用可回收;
  • 保守扫描的已知局限:栈上恰好等于堆地址的整数值会被误保留一轮(安全方向的偏差);循环内反复 + 拼接字符串的时间复杂度仍是 O(n²)——GC 回收内存但不改变算法时间;文本累积请用 字符串构造()/字符串追加()/字符串取值()(总拷贝 O(n)),连接/重复/替换 已改为线性实现。
• 栈:协程栈随协程生灭;主协程亦同。指针指向栈上的变量槽,不参与 GC 追踪(见 §2.1 的悬垂警告)。
• 自举原生版(官网下载)GC 阶段 2(保守标记-清除 + 空闲复用):每次分配

仍登记到独立分配表(地址/大小/类别;表本身一次 192MB 匿名映射),并按阈值 在分配点触发回收:

• 根 = 全局区 + 各协程活跃栈区间(当前协程取 min(保存的 rsp, 原栈指针()))

+ 协程上下文寄存器 + 全局/栈保守扫描(每个 8 字节字凡落在已登记块内 即视为指针);协程栈整块置特殊类别,标记传播跳过、改按活跃区间扫描;

• 未标记块回收进按大小分级的空闲链表(16..4096B 共 256 类,大块单链),

后续分配优先复用(小块复用清零,保持「新分配为零」语义),堆字节随之回落;

• 触发:距上次回收的分配增量超过预算(初始 32MB;每次回收后预算 =

max(存活 × 2, 32MB),与本节上文一致);页索引按 4KB 页建立(页内平均块数 约 8;64KB 页实测 ~127,单字查找链过长);页节点/标记栈溢出时本轮不回收 (并翻倍预算退避),表满则永久停用 GC——失败方向都是「不回收」,不会错回收;

• 保守扫描的已知局限与阶段 1 相同:栈上恰好等于堆地址的整数会被多保留一轮。
• 观测:堆用量() 返回当前堆字节用量(整数);原生版 堆统计() 返回

{块数, 字节, 容量, 表基, GC次数, GC中止, GC存活, GC块数, GC页节点} (字节为当前存活登记字节;GC* 为诊断计数), 堆整理() 压缩地址为 0 的无效登记项并返回是否已建立分配表; 堆回收() 强制触发一次完整回收(调试/测试入口)。

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
    抛出("测试失败")

7. 错误信息约定

编译错(退出码 1):文件:行:列: 错误:消息 + 源码行 + ^ 指示(列按码点,指示按显示宽度对齐)。示例:

例子.zh:3:9: 错误:未定义的变量「名字」
    打印("你好," + 名字)
            ^

原生后端对语义/模块错误也按同一格式渲染(列优先取消息中第一个「…」名字在该行的位置,否则取首个非空白;跨模块错误指向定义该函数的模块文件,并回显该文件对应的源码行)。

运行时错误(生成的程序,stderr,退出码 1):运行时错误(第 N 行):消息。示例:

运行时错误(第 12 行):「+」不支持 布尔 与 字符串

未被 捕捉 接住的抛出与此格式完全一致(见 §3.4);普通抛出/运行时错误的捕捉消息是纯文本(无该前缀);抛出对象 的捕捉值是原对象,未捕获时优先打印其「消息」字段。

调用栈(v2.23 增补):未捕获错误在错误行之后打印由内向外的 zhlang 调用栈,每帧是 函数名(定义于第 N 行)(生成函数在入口压帧、返回前弹帧;行号是函数声明行)。每协程独立, 最多保留最内层 64 帧(更深时注明省略层数);被 捕捉 的错误不打印,捕捉后栈深度回到 尝试 入口,后续错误不会带出已展开的旧帧。示例:

运行时错误(第 3 行):下标越界:5(长度 1)
调用栈(由内向外):
  内(定义于第 1 行)
  外(定义于第 4 行)

行号与实现位置(v2.11):实现于标准库(§6 zhlang 实现)的内置,错误消息正文保持不变,行号指向标准库实现行(标准库/*.zh 内的行),不是调用处。其余情况行号一律指向调用处。

gcc 错误:透传 gcc 退出码与 stderr,并保留生成的 .c 文件供排查。

8. 实现形态

• 编译 源.zh [-o 输出] [--target 目标] [-d|--debug]:纯 zhlang 自举编译器,AST 直接生成机器码并写出 ELF/PE,不依赖任何外部工具链;省略 -o 时产物放在源文件旁。
• 三端目标内置:x86_64-linux-gnu / aarch64-linux-gnu / x86_64-windows-gnu;--target 接受三元组、短名或 Go 风格 系统/架构,环境变量 ZHC_TARGET(或 ZHC_GOOS+ZHC_GOARCH)提供默认值,--targets 列出目标与能力表。
• 生成代码特征:值模型为「类型标签 + 载荷」;字符串/数组/字典/闭包由内嵌的 zhlang 运行时提供;循环回边与函数调用插入协作调度安全点;产物为静态单文件。
• 编译器源码全部是 zhlang,由自己编译自己(stage1 == stage2 逐字节相同)。

8.1 交互式会话(编译 --repl)

语言本身无解释器(编译单元 = 整个程序),会话因此实现为整段重跑:每段可编译输入都触发一次 「累计源码 → 临时程序 → 运行」,只显示比上一轮新增的 stdout(前缀裁剪);编译错不计入会话, 运行失败(运行时错误/崩溃/非零退出)同样不计入,以保证后续轮次的输出基线能推进。 副作用(写文件、网络请求、打印)会随每轮重放——这是该设计的固有代价,已在会话内 :帮助 说明。 会话命令 :帮助、:会话、:清(:重置/:reset/:clear 同义)、:退出 在续行中同样生效; 续行中 :清 会放弃未完成输入。全角冒号 ： 与英文别名同义。会话临时目录按微秒时间戳 + 随机数命名, 同一秒启动的多个会话互不共用 会话.zh/会话.bin。

9. 完整示例

9.1 你好世界

打印("你好,zhlang!")

9.2 阶乘(递归)

函数 阶乘(n)
    如果 n <= 1
        返回 1
    返回 n * 阶乘(n - 1)

常量 汇报 = `5 的阶乘是 ${阶乘(5)}`
打印(汇报)

9.3 九九乘法表

循环 i 从 1 到 9
    循环 j 从 1 到 i
        打印(i, "*", j, "=", i * j)

9.4 模板字符串与字符串库

常量 名字 = "zhlang"
常量 版本 = 1.0
打印(`语言:${名字},版本:${版本},明年:${版本 + 1}`)
打印(长度("你好世界"))          // 4
打印(子串("你好世界", 1, 2))     // 好世
打印(查找("banana", "na"))       // 2
打印(替换("a-b-c", "-", "+"))    // a+b+c

9.5 猜数字(交互)

常量 答案 = 42
当 真
    打印("猜一个数:")
    常量 猜 = 转整数(读入())
    如果 猜 == 答案
        打印("猜对了!")
        跳出
    如果 猜 < 答案
        打印("小了")
    否则
        打印("大了")

9.6 生产者-消费者(并发)

函数 生产者(ch)
    循环 i 从 1 到 5
        发送(ch, i)
    关闭(ch)

函数 消费者(ch)
    当 真
        常量 v = 接收(ch)
        如果 v == 假
            跳出
        打印("收到", v)

常量 ch = 通道()
启动 生产者(ch)
消费者(ch)
打印("完成")

(多生产者共用一个通道时不要各自 关闭——向已关闭通道发送是运行时错误;确需结束信号时由唯一的关闭方发哨兵值。)

9.7 一万协程压测(并发 + GC)

函数 工人(id, ch)
    发送(ch, id * 2)

常量 ch = 通道(10000)
常量 开始 = 当前时间()
循环 i 从 1 到 10000
    启动 工人(i, ch)
变量 收 = 0
循环 i 从 1 到 10000
    常量 v = 接收(ch)
    收 = 收 + v
打印("合计", 收, "耗时", 转字符串(当前时间() - 开始) + " 秒")
打印("堆用量", 堆用量())

9.8 数组与字典(v1.2)

// 数组:排序与遍历
常量 分数 = [88, 92, 79, 95]
分数[2] = 80                    // 索引赋值
追加(分数, 90)
打印(分数, 分数[-1])            // [88, 92, 80, 95, 90] 90

// 字典:统计字频(保插入序)
常量 文本 = "床前明月光疑是地上霜举头望明月低头思故乡"
常量 频次 = {}
循环 字 在 文本                 // 字符串遍历得码点
    如果 包含(频次, 字)
        频次[字] = 频次[字] + 1
    否则
        频次[字] = 1
打印(频次)                     // {"床": 1, "前": 1, …, "明": 2, …}

// 遍历字典得键;键() 亦然
循环 k 在 频次
    如果 频次[k] > 1
        打印(`「${k}」出现 ${频次[k]} 次`)

9.9 一等函数与箭头函数(v1.6)

函数 双倍(x)
    返回 x * 2

常量 nums = [1, 2, 3, 4, 5]

打印(映射(nums, n => n * n))            // [1, 4, 9, 16, 25]
打印(过滤(nums, n => n % 2 == 1))        // [1, 3, 5]
打印(归约(nums, 0, (a, x) => a + x))     // 15

常量 f = 双倍                              // 函数名作值
打印(f(21))                              // 42

常量 加 = a => b => a + b                  // 柯里化:箭头函数返回箭头函数
打印(加(3)(4))                           // 7

常量 基数 = 100
常量 含基数 = x => 基数 + x                // 捕获(此后不赋值):按值绑定
打印(含基数(1))                          // 101

变量 计数 = 0
常量 加一 = () =>                          // 捕获且被改写 → 共享单元
    计数 = 计数 + 1
    返回 计数
常量 读计数 = () => 计数                   // 同一变量,同一单元
打印(加一(), 加一(), 读计数())           // 1 2 2
计数 = 100
打印(读计数())                           // 100(外层改写闭包可见)

9.10 正则(v2.0)

// 原始字符串:模式里的反斜杠原样书写
常量 行 = "2026-10-15 09:13:02 ERROR 登录失败 user=alice ip=10.0.0.7"

打印(正则分组(行, r"^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) (\w+)"))
// ["2026-10-15 09:13:02 ERROR", "2026", "10", "15", "09", "13", "02", "ERROR"]

打印(正则查找(行, r"user=(\w+)"), 正则分组(行, r"user=(\w+)")[1])   // user=alice alice
打印(正则全部(行, r"\d+"))                                        // ["2026", "10", "15", "09", "13", "02", "10", "0", "0", "7"]
打印(正则替换(行, r"(\d+)\.(\d+)\.(\d+)\.(\d+)", "$1.$2.*.*"))    // …ip=10.0.*.*
打印(正则分割("a, b;c", r"[,;]\s*"))                              // ["a", "b", "c"]

打印(正则匹配("HELLO", "hello", "i"))                             // 真(选项 i 忽略大小写)
打印(正则匹配("中文测试", r"[一-龥]+"))                            // 真
打印(正则匹配("abc", "(未闭合"))                                   // 运行时错误:正则模式错误:分组未闭合(缺少 ))

9.11 HTTPS(v2.1)

// 内置 TLS 客户端:证书链 + 主机名校验;CA 用系统包(或 ZHLANG_CA_FILE 指定)
常量 r = 网页请求("https://example.com/", "GET")
打印(r["状态"])                          // 200
打印(长度(r["体"]) > 0)                  // 真
打印(正则匹配(r["头"]["content-type"], "text/html"))   // 真

// 校验失败一定报错,不会静默放行:
// 取网页("https://127.0.0.1:8443/")     // CA 不匹配 → 运行时错误:TLS 握手失败(…):X509 - Certificate verification failed…

原生后端(M4):x86_64/aarch64 Linux 上同一 API 由 标准库/TLS.zh 的纯 zhlang TLS 1.3 实现(TLS_CHACHA20_POLY1305_SHA256 + x25519,证书链/主机名/SAN/有效期校验), 信任库见 §6.2 的原生后端说明;编译期按程序是否用到 取网页/网页请求 决定是否 发射 TLS 代码与内嵌 CA(不用 HTTP 的程序体积不变,PE 目标也不发射)。 ZHLANG_HTTPS=curl 显式回退系统 curl;证书校验失败不会自动回退。