Module mhchem 

mhchem 化学公式转译器（\ce/\pu → LaTeX，server-only）。 mhchem 化学公式转译器：把 \ce{...} / \pu{...} 预转译为标准 LaTeX， 再交给 katex 渲染。

这是 mhchemParser 4.2.2（Apache-2.0） 的机械移植：状态机 + texify 输出。mhchemParser 是纯字符串→字符串转译器， ce("H2O") → \mathrm{H}\sb{2}\mathrm{O} 之类，无需嵌入 katex 内部解析树。

移植要点（TS→Rust）：

• 动态 buffer 对象 → Buffer 结构体（Option 字段 + clear）。
• 动态 Parsed = string | object → Parsed 枚举；节点字段用 Field（字符串或节点向量）。
• 正则模式（含 lookahead (?=)/(?!)，Rust regex 不支持）→ fancy-regex（已被 syntect 间接引入，此处显式声明）。
• findObserveGroups 花括号配对扫描 → find_observe_groups。
• 状态机转移表 → build_transitions 展开（对应 _mhchemCreateTransitions）。

公开 API：ce / pu。任意内部异常都回退为原样输出（绝不 panic，与 katex.rs 的容错哲学一致）。

---

Copyright 2015-2023 Martin Hensel（mhchemParser 原作者）。Apache-2.0。

Macros

re 🔒

惰性编译字面量正则，编译失败降级为 CompiledPat（None）。

Structs

ActionRef 🔒

Buffer 🔒

状态机缓冲区（对应 TS 的动态 buffer 对象）。

CompiledPat 🔒

编译产物：把「坏正则降级为不匹配」的语义封装在一处。

MMatch 🔒

模式匹配结果。

NodeData 🔒

RawEntry 🔒

原始转移条目（对应 TS 字面量，patterns/states 均为 | 分隔的合并名）。

Span 🔒

Task 🔒

Transition 🔒

Enums

Field 🔒

解析中间表示的字段值：字符串或子表达式节点向量。

MVal 🔒

模式匹配值：单字符串或捕获组数组（正则 >1 个捕获组时为数组）。

Out 🔒

Parsed 🔒

解析中间表示：字面字符串或节点。

Pat 🔒

字面量或正则模式（findObserveGroups 的参数）。

Statics

A 🔒

BD 🔒

CE 🔒

GREEK_NAMES 🔒

希腊字母宏集合（letters / \greek 等模式用到）。

GREEK_RE 🔒

LETTERS_RE 🔒

NUM99 🔒

O 🔒

ONE_GREEK_RE 🔒

OXIDATION 🔒

PQ 🔒

PU 🔒

PU2 🔒

PU99 🔒

TEXT 🔒

TEX_MATH 🔒

TEX_MATH_TIGHT 🔒

Functions

append_field 🔒

append_str 🔒

arrow_sub 🔒

bd_action 🔒

build_transitions 🔒

展开 {pattern: {state: task}} 为 {state => [(pattern, task)]}。 对应 _mhchemCreateTransitions：拆分 |、'*' 插入所有状态。

ce

把 \ce{...} 内容转译为 LaTeX。

ce_action 🔒

compile_or_log 🔒

编译正则，失败时记日志并返回 None（绝不 panic）。

concat 🔒

exec_action 🔒

fancy_match 🔒

把 fancy-regex 的捕获结果转为 MMatch（锚定 ^，whole 从 0 起）。

fg 🔒

find_observe_groups 的简写封装。

field_str 🔒

find_observe_end 🔒

从 rest0 的 start 位置扫描，跟踪花括号深度，在深度 0 遇到 end_chars 时返回其区间。

find_observe_groups 🔒

findObserveGroups：花括号感知的定界符配对扫描。

generic_action 🔒

get_arrow 🔒

get_bond 🔒

get_operator 🔒

go 🔒

主解析循环。

gof 🔒

is_empty_pat 🔒

machine_action 🔒

match_pattern 🔒

按名匹配模式（对应 _mhchemParser.patterns.match_）。

mval_pair 🔒

mval_str 🔒

mval_to_out 🔒

num99_action 🔒

oxidation_action 🔒

pat_amount 🔒

amount 模式。

pat_enumber 🔒

(-)(9.,9)(e)(99) 模式。

pat_formula 🔒

formula$ 模式。

pat_match_head 🔒

在 input 起始处匹配 pat，返回匹配到的文本（不含 remainder）。

pat_state_of_aggregation 🔒

state of aggregation $ 模式。

pq_action 🔒

pu

把 \pu{...} 内容转译为 LaTeX（容错同 ce）。

pu2_action 🔒

pu99_action 🔒

pu_action 🔒

raw 🔒

task 🔒

texify_go 🔒

texify_go2 🔒

texmath_action 🔒

text_action 🔒

thousands_split 🔒

千分位拆分（pu-9,9 的 output-0 / output-o）。

to_tex 🔒

transitions_for 🔒