MoonBit Phonetic Encoding Library

一个使用 MoonBit 实现的确定性语音编码库，用于对 ASCII 英文姓名和单词生成可比较的语音键。

功能

• American Soundex：固定四字符编码。
• Refined Soundex：使用细化映射生成变长编码。
• NYSIIS：生成不截断的 NYSIIS 编码。
• 统一的算法选择、匹配和批量编码 API。
• 对大小写、空白、标点和不受支持字符采用一致的预处理规则。

安装

使用 Mooncakes 发布版本时，可在 MoonBit 项目中执行：

moon add zbhzs1/moonbit-phonetic

在调用方的 moon.pkg 中导入：

import {
  "zbhzs1/moonbit-phonetic" @phonetic,
}

使用

let soundex_key = @phonetic.soundex("Robert")
let refined_key = @phonetic.refined_soundex("testing")
let nysiis_key = @phonetic.nysiis("Schmidt")

let same = @phonetic.is_match(
  "Robert",
  "Rupert",
  @phonetic.Soundex,
)

let keys = @phonetic.encode_all(
  ["Brian", "Brown", "Brun"],
  @phonetic.Nysiis,
)

上述值分别为 R163、T6036084、SNAD、true 和三个 BRAN。

可运行示例

moon run examples/basic

预期输出：

R163
T6036084
SNAD
true

输入规则

1. 仅处理 ASCII 字母 A-Z 和 a-z。
2. 小写 ASCII 字母转换为大写。
3. 数字、标点、空白和非 ASCII 字符会被忽略。
4. 如果过滤后没有 ASCII 字母，编码结果为空字符串。
5. is_match 在任一编码结果为空时返回 false。

这些是本库统一采用的预处理规则，不代表历史算法可以处理任意 Unicode 语言。

API

soundex(String) -> String
refined_soundex(String) -> String
nysiis(String) -> String
encode(String, Algorithm) -> String
is_match(String, String, Algorithm) -> Bool
encode_all(Array[String], Algorithm) -> Array[String]

Algorithm 提供 Soundex、RefinedSoundex 和 Nysiis 三个选项。

本地验证

在仓库根目录执行：

moon fmt --check
moon check
moon build
moon test
moon run examples/basic

CI 执行相同的检查、构建、测试和示例命令。

功能边界

本项目不处理音频，不提供语音识别、语音合成、中文拼音或通用多语言匹配；不实现 Metaphone、Double Metaphone 或 Metaphone 3；不提供编辑距离、概率评分或真实发音相同的保证。NYSIIS 使用不截断输出，不等同于限制为六字符的 strict 变体。

来源与许可证

算法规则和兼容性测试向量的来源见 docs/references.md。MoonBit 实现代码为本项目编写，没有逐行移植第三方实现。

项目采用 Apache License 2.0。