WHATWG Encoding Standard 的 MoonBit 实现:label 解析、流式解码与一次性编码 API,覆盖规范定义的全部 40 种编码(含 GBK、Big5、Shift_JIS、ISO-2022-JP)
| 分组 | 编码 | 状态 |
|---|---|---|
| 单字节(28 种) | windows-1252(含 latin1 / ascii 等别名)、ISO-8859-2/3/4/5/6/7/8/8-I/10/13/14/15/16、windows-874/1250..1258、KOI8-R/U、IBM866、macintosh、x-mac-cyrillic | ✅ 已实现 |
| 中文 | GBK(含 gb2312 / chinese 等别名)、gb18030(含 4 字节) | ✅ 已实现 |
| 日文 | Shift_JIS、ISO-2022-JP(7 状态转义状态机 + 跨块状态) | ✅ 已实现 |
| 日文 / 韩文 | EUC-JP(含 SS2/SS3)、EUC-KR | ✅ 已实现 |
| 中文(繁体) | Big5 | ✅ 已实现 |
| Unicode | UTF-8、UTF-16BE、UTF-16LE(后两者仅解码,见下) | ✅ 已实现 |
| 其他 | replacement(至多一个 U+FFFD)、x-user-defined(算法定义,无索引表) | ✅ 已实现 |
| 维度 | f4ah6o/encoding_sjis | 本库 moon_encoding |
|---|---|---|
| 编码范围 | 仅 Shift_JIS 一种 | 40 种编码 / 228 个 label 全部接线(编解码;规范未定义编码器的三种除外) |
| 方向 | 仅解码(无编码端) | 解码 + 编码(fatal 模式),含 Shift_JIS / ISO-2022-JP 编码器 |
| 流式解码 | ✅ new_decoder / decode_to_string | ✅ Decoder::new / consume / finish,统一覆盖全部已接线编码(含 ISO-2022-JP 的转义与双字节跨块) |
| 合规基准 | encoding_rs-compliant(自述) | WHATWG encoding.bs 逐条实现 |
| 附加能力 | — | 28 种单字节编码、GBK/gb18030、Big5、EUC-JP/EUC-KR、ISO-2022-JP、replacement/x-user-defined、UTF-8/UTF-16、CLI 转码、CPython 差分测试 |
moon add LL728/moon_encoding// moon.pkg
import {
"LL728/moon_encoding",
"moonbitlang/core/debug",
}pub fn example(bytes : Bytes) -> Unit {
// 字节 -> 文本(解码错误按规范替换为 U+FFFD)
match @moon_encoding.decode(bytes, "windows-1252") {
Ok(text) => println(text)
Err(e) => println("解码失败: " + @debug.to_string(e))
}
// 文本 -> 字节(fatal 模式:不可映射字符直接报错)
match @moon_encoding.encode("Héllo €", "windows-1252") {
Ok(out) => println("\{out.length()} 字节")
Err(e) => println("编码失败: " + @debug.to_string(e))
}
}// chunk : Bytes —— 逐块到达的字节
match @moon_encoding.Decoder::new("windows-1252") {
Ok(decoder) => {
let mut text = ""
text = text + decoder.consume(chunk) // 跨块状态在解码器内维护,任意切分结果一致
text = text + decoder.finish()
}
Err(e) => println("创建解码器失败: " + @debug.to_string(e))
}pub fn bom_and_modes(bytes : Bytes, text : String) -> Unit {
// 1) 只看前 3 字节:命中返回规范名,否则 None。不消费、不改写输入。
match @moon_encoding.bom_sniff(bytes) {
Some(name) => println("发现 BOM: " + name)
None => println("无 BOM")
}
// 2) 规范 decode 钩子:BOM 优先于 fallback label,并吞掉 BOM 字节。
// 只有 BOM 时返回空串;fallback label 本身仍须合法。
match @moon_encoding.decode_auto(bytes, "windows-1252") {
Ok(decoded) => println(decoded)
Err(e) => println("解码失败: " + @debug.to_string(e))
}
// 3) html 错误模式:不可映射码点写成 &#十进制; 而非报错。
// 规范原文警告该序列无法与合法输入区分、可能静默丢数据,故必须显式选择。
match @moon_encoding.encode_with_mode(
text,
"iso-2022-jp",
@moon_encoding.encode_error_mode_html(),
) {
Ok(out) => println("\{out.length()} 字节")
Err(e) => println("编码失败: " + @debug.to_string(e))
}
}// chunk : Bytes —— 逐块到达的字节
match @moon_encoding.Decoder::new_auto("gbk") {
Ok(decoder) => {
let mut text = ""
text = text + decoder.consume(chunk)
text = text + decoder.finish()
}
Err(e) => println("创建解码器失败: " + @debug.to_string(e))
}#derive(Eq, @debug.Debug)
pub enum EncodingError {
UnknownLabel(String) // label 不在标准定义的 228 个之内
UnsupportedEncoding(String) // label 合法但规范未定义编码器(replacement / UTF-16BE / UTF-16LE)
Unmappable(Int, Int) // 编码遇不可映射字符:码点 + 字符位置
}# 字节 -> UTF-8 文本
moon run cmd/main -- decode <label> <input> <output>
# UTF-8 文本 -> 目标编码字节
moon run cmd/main -- encode <label> <input> <output>
# 列出本构建支持的全部编码(WHATWG 规范名)
moon run cmd/main -- list
# 零门槛复现:仓库自带两个样例,解码再编码应与原文件逐字节一致
# demo/sample-cp1252.bin = 63 61 66 E9 → windows-1252 的「café」
# demo/sample-iso2022jp.bin = 1B 24 42 46 7C 4B 5C 38 6C 1B 28 42 → ISO-2022-JP 的「日本語」
moon run cmd/main -- decode windows-1252 demo/sample-cp1252.bin cafe.txt
moon run cmd/main -- encode windows-1252 cafe.txt cafe.bin
cmp demo/sample-cp1252.bin cafe.bin # 无输出即逐字节一致;cafe.txt 内容为 café
moon run cmd/main -- decode iso-2022-jp demo/sample-iso2022jp.bin ja.txt
moon run cmd/main -- encode iso-2022-jp ja.txt ja.bin
cmp demo/sample-iso2022jp.bin ja.bin # ja.txt 内容为 日本語(样本含 ESC $ B / ESC ( B)$ moon run cmd/main -- encode replacement in.txt out.bin
编码失败: UnsupportedEncoding("replacement")
$ echo $?
1
| 项 | 值 |
|---|---|
| 已验证版本 | moon 0.1.20261104 (940aa18 2026-11-04) / moonc v0.10.20+65efd5b93 (2026-11-05) |
| 最低要求 | 必须 ≥ 0.1.20261104 |
| 为什么 | 源码使用 #derive(...) 前缀属性写法,这是新版格式化器(moon fmt)的规范输出;0.1.20261012 及更早的编译器不认这种写法(报 syntax error in attribute,随后表现为 Type ... does not implement trait Eq/Debug),用旧版工具链会编译失败 |
| 安装/更新 | https://www.moonbitlang.com/download/ |
| CI 侧 | CI 每次装官方 latest,所以 CI 始终在最新工具链上验证;本地若落后于 CI,请先更新工具链再跑门禁 |
历史注记:本仓库在 2026-11 的工具链更新中做了唯一一处源码适配 —— codec.mbt / iso2022.mbt 的 } derive(...) 后置写法被新格式化器规范化为 #derive(...) 前缀写法 (纯格式,语义不变,共 2 文件 4 行)。
python tools/generate_tables.py # 由 vendored 规范数据生成 label/编码表/dispatch
python tools/gen_vectors.py # 由 CPython codecs 生成差分向量
moon fmt && moon check --deny-warn && moon test| 文件 | 职责 |
|---|---|
| label.mbt | label 解析入口(ASCII 大小写不敏感匹配) |
| single_byte.mbt | 28 种单字节编码共用的表驱动编解码引擎 |
| codec.mbt | 公共 API:EncodingError、流式 Decoder、decode / encode / encode_with_mode(EncodeErrorMode) |
| bom.mbt | 规范 §6.1 的 BOM 钩子:bom_sniff / decode_auto / Decoder::new_auto(AutoDecoder,支持 BOM 跨块) |
| gbk.mbt | GBK/gb18030 状态机与编码器(规范 §gb18030-decoder/encoder 逐条实现) |
| utf.mbt | UTF-8 / 共享 UTF-16 状态机与 UTF-8 编码器(规范 §utf-8 / §14.2.1 shared UTF-16 decoder 逐条实现) |
| euc.mbt | EUC-JP / EUC-KR 状态机与编码器(规范 §euc-jp / §euc-kr 逐条实现) |
| multibyte.mbt | Big5 与 Shift_JIS 状态机与编码器(规范 §big5 / §shift_jis 逐条实现) |
| iso2022.mbt | ISO-2022-JP 的 7 状态解码器(4 个关联变量)与编码器(规范 §iso-2022-jp-decoder / encoder 逐条实现) |
| misc.mbt | replacement 解码器(至多一次 error)与 x-user-defined 的算法合成表 |
| gen_label.mbt / gen_single_byte.mbt / gen_chinese.mbt / gen_big5_sjis.mbt / gen_euc.mbt / gen_iso2022.mbt | 生成物:label 表、单字节表、gb18030 与 Big5/jis0208/EUC/ISO-2022-JP katakana 各索引与编码反向表(勿手改) |
| gen_w1252_vectors_wbtest.mbt | 生成物:CPython 差分黄金向量(勿手改) |
| cmd/main/ | 文件转码 CLI |
| demo/ | 命令行示例用的极小样例(windows-1252 与 ISO-2022-JP 各一个,共 16 字节) |
| docs/ | 演示 GIF 与同步生成的文字实录 |
| tools/ | 规范数据 vendor、表与差分向量生成器、规范参考实现(chinese_ref.py、multibyte_ref.py、utf_ref.py,encode-map 规则单一来源) |
pub struct AutoDecoder {
// private fields
}pub struct Decoder {
// private fields
}type DecoderStatepub enum EncodeErrorMode {
Fatal
Html
}fn bom_sniff(bytes : Bytes) -> String?fn encode_with_mode(text : String, label : String, mode : EncodeErrorMode) -> Result[Bytes, EncodingError]Install
Download zipWHATWG Encoding Standard 的 MoonBit 实现:label 解析、流式解码与一次性编码 API,覆盖规范定义的全部 40 种编码(含 GBK、Big5、Shift_JIS、ISO-2022-JP)