cli

将参数数组解析为旗标、选项和位置参数，使用同一份声明提供默认值。

版本 1.0.0 · C / xlang · 无扩展库依赖

当前未签收：公开语言导入受 os.args 缺符号 M7 阻断；独立调用真实 C 解析器的语言字面量另有 M1 容器投影错误。C 解析成功不代表 XLang 已可运行，修复其中一项也不能自动关闭另一项。

2026-10-30 冻结工具链：两平台默认各39阶段、29符合要求，10条语言路径仍失败，整体返回1。 C原边界、36组合/882故障、两份C范例的GCC/直接TCC/独立EXE及真实ABI通过；Linux C含ASan/UBSan/泄漏检查。

快速开始

import cli

var spec = {"flags": ["verbose"], "options": {"output": "o"},
    "positional": ["src"]}
var result = cli.parse(["--verbose", "--output=out.txt", "in.txt"], spec)
assert result["ok"] == true

接口与边界

入口	用途
`parse(args, spec)`	解析传入的参数数组，不读取进程环境。
`parseOs(spec)`	显式读取当前进程参数。
`usage(program, spec)`	生成简短的用法文本。
`xcli_parse(args, spec)`	C 入口；结果由调用方以 `xrtValueRelease` 释放。

声明顶层只接受 flags、options、shorts、defaults 和 positional；拼错字段名会报声明错误。defaults 的键必须是 options 中已声明的选项，值必须是无内嵌 NUL 的字符串，使有无命令行输入时的选项类型一致；flags 和 positional 各自不允许重复名称。长选项名和位置参数名可使用有效 UTF-8，但不得包含 Unicode 空白、C0/C1 控制字符、常见零宽格式字符、双向文本控制字符或 BOM；短别名限可打印单字节 ASCII，排除 - 和 =。短选项输入中的非 ASCII 或控制字符返回固定的可打印错误文本；-o中文.txt 的 UTF-8 附加值仍可正常使用。重复别名、未声明的旗标目标及旗标/长选项同名均拒绝。同一选项多次出现时最后一次生效；--name= 是覆盖默认值的有效空值，-- 后的文本不再按选项解析。用户参数错误返回 ok=false，在第一条错误处停止，后续参数不再生效；无效声明或含 NUL 的参数报错。长值、名称及错误说明不使用固定长度缓冲；--verbose=yes 不会被误作普通旗标。

验证状态

release/extlibs/cli/test/check_c.ps1
bash release/extlibs/cli/test/check_c.sh

C 边界和范例可独立验证；extlibs/cli/examples/basic_c.c 可直接 xl run 或 xl build。C 解析只借用输入字符串视图，不修改输入或逐参数分配临时副本；返回结果仍独立持有字符串。C/XL 范例采用不同文件名，避免 XLang 运行时自动引入同名 C 伴随源。当前发布版的 XLang 运行因主线缺少 xl6_xrt_os_args 而链接失败；双语运行与 AOT 尚未签收，不能将 C 侧通过视为整包发布验收。

默认值已限制为无 NUL 字符串，结果通过 XRT 标量复制持有不可变文本，不需要图深拷贝。旧图入口也不复制标量正文；此优化移除图路径与 VALUE_GRAPH 依赖，不宣称减少分配。 36 组空串、中文、8KiB 默认值的 882 个分配故障在修改前后均检查立即恢复、输入不变、旧结果寿命和存活内存。

同一basic C消费者在同平台GCC -O2/分段/gc-sections下，GNU size text在Windows减少11196字节、 Linux减少13472字节；含默认值的解析不再进入旧图入口的3184/3168字节静态栈帧，basic消费者也不再携带该实现。这不是文件大小、总栈上限或XLang端到端性能。分配次数没有减少，不将标量本已共享的正文描述成新消除的副本。

新增 options.xl/options_c.c：显式短别名、组合旗标、中文附加值、默认覆盖、终止选项和首错停止，共用 options.expected.txt 六行输出。C 可直接 xl run/build；XL 当前仍受上述共享层阻断，不宣称已双语通过。

默认门禁除严格 C 与 sanitizer 外，也保留中央/公开语言正例和两项无包最小边界。命令有界，保存原始退出码和双流、输入哈希；失败不删现场，聚合失败仍逐项要求 0，不绕过 parseOs 或私有容器表示。