pattern

Builder 的关联元数据事务

ID 为 Builder 实例局部的槽位/代际；不同 Builder 可产生相同数字，调用方 必须同时保存实例身份。代际或版本耗尽时拒绝相应结构修改并报 StateError， 不回绕、不使旧 ID 复活。xrtPatternBuilderContains 查询活动 ID；无效或 陈旧 ID 为 false，不设置错误（NULL Builder 仍报 ArgumentError）。

当模式表与语言对象 tag 等关联元数据必须一起更新时，使用 xpatternedit：

1. xrtPatternBuilderPrepareAdd(builder, specs, count) 准备整批追加； PrepareSet(builder, id, spec)、PrepareRemove(builder, id)、 PrepareClear(builder) 准备替换、删除、清空。Set/Remove 的无效 ID 报 StateError，不采用原有非报错 false 的查找语义。 2. xrtPatternEditReady/Count/Id 查询独占编辑及确定的 ID。准备不改变活动 条目、版本、Dirty 或缓存；可能增长物理容量。失败或取消不消费 ID。 3. 调用方完成关联元数据的可能失败部分，再调用 xrtPatternEditCommit。 有效且串行的提交不分配、不失败；空 Add/Clear 不增加版本。 4. xrtPatternEditFree 释放编辑。未提交时即取消；已提交时只释放元数据。 Commit 不自动释放编辑，提交后仍可读取其 Count/Id，但不能再次提交。

Pending 期间其他结构修改（包含 Reserve）报 StateError；读取与 Compile 仍使用提交前的完整状态。Builder Free 自动使 edit 失效，但不代替调用方 EditFree。Builder/edit 须串行且不得重入修改；元数据及用户析构/回调等 外部副作用不由原生事务自动回滚。事务/代际白盒、实际 OOM 及无分配提交 回归在 tests/pattern/test_pattern_edit.c；OOM 子集仅在 MEMORY_DEBUG 开启时执行。

模式语法

• 字面字段按字节精确匹配。
• {name} 捕获一个非空字段，不能跨越配置中的分隔字节。
• prefix{name}、{name}suffix 与 prefix{name}suffix 捕获同一字段中

前后缀之间的非空字节；前后缀按字节精确匹配。

• {*name} 捕获剩余文本，只能位于模式末尾，并允许空值。
• {{ 和 }} 在字面字段中分别表示 { 和 }。
• 捕获名必须是 ASCII 标识符，同一模式内不能重名。
• 一个字段至多包含一个普通捕获；{a}-{b} 当前是编译错误，尾捕获不能

与任何字面量混合。

• 匹配始终锚定完整输入，不执行路径规范化、URL 解码或大小写折叠。

默认分隔符为 /。xpatternconfig.Separators 是分隔字节集合；模式中的 分隔符仍要求精确匹配。设置为 /. 后，/file/{name}.{ext} 可以分别捕获 文件名和扩展名，但 / 与 . 不会互相替代。

一次性提取

xrtPatternExtract 在模式、参数和捕获容量有效时不分配内存，适合偶发 匹配；错误报告本身仍可能创建 xerror。同一模式被重复使用时，应通过 xrtPatternCompile 编译一次。

批量编译与匹配

xrtPatternCompileMany 将多条模式编译成不可变对象。xrtPatternLookup 只返回获胜模式；xrtPatternMatch 还按出现顺序写入捕获视图。编译对象没有 可变 matcher 缓存，可由多个线程同时查询。

模式按第一个不同字段决定特异度：字面字段优先于混合捕获，混合捕获优先于 整字段捕获，整字段捕获优先于尾捕获。多个混合捕获同时命中时，固定字节 总数更多者优先；总数相同时，前缀更长者优先。结构无法区分且优先级相同的模式会产生 XPATTERN_ERROR_CONFLICT；不同优先级可以显式替换这种同结构模式。优先级 不会令参数模式反超可同时命中的字面模式。

动态模式

xpatternbuilder 复制并缓存模式解析结果。Add、Set、Remove 只修改 Builder；xrtPatternBuilderCompile 生成新的不可变快照。旧快照不会观察到 后续修改，因而可以由上层使用 generation 或 RCU 风格生命周期安全发布。

Builder 不保证并发安全。未修改的 Builder 再次编译会返回缓存快照的新 引用；批量追加具有事务性。