XML 命令定义格式

命令定义 XML 文件目前存放在如下两个目录下，该目录由研发自行定义，以下为当前节点示例：

Script/source/CmdSource/
Sta/CmdSource/

每个 XML 文件定义一个**模块**（Module），模块下包含若干**命令**（Command）。

根元素：Module

XML 文件的根元素是 <Module>，包含以下属性：

属性	类型	必填	说明
`name`	string	是	模块名称，用于生成 RST 文件名和页面标题
`description`	string	否	模块描述文本。若为空，生成文档时会填充默认文本

示例：

<Module name="read_verilog" description="读取 Verilog 网表文件">
    <!-- commands here -->
</Module>

子元素：Command

<Command> 元素定义模块下的一个命令，包含以下属性：

属性	类型	必填	说明
`name`	string	是	命令名称，同一文档中不可重复
`description`	string	是	命令描述
`internal`	bool (true/false)	否	是否为内部命令。内部命令不在 usage 中展示
`alias`	string	否	命令别名

示例：

<Command name="read_verilog" description="读取 Verilog 文件" internal="false" alias="rv">
    <!-- options and groups here -->
</Command>

孙子元素：Option

<Option> 元素定义命令的一个选项参数：

属性	类型	必填	说明
`name`	string	是	选项名称（不带前缀 `-`，生成时自动添加）
`description`	string	是	选项描述
`type`	string	否	选项类型，默认为 `BOOL`
`default`	string	否	默认值
`positional`	bool (true/false)	否	是否为位置参数
`internal`	bool (true/false)	否	是否为内部选项（不显示在 usage 中）

支持的类型：

类型	说明	默认值约束
`BOOL`	布尔型，默认值只能为 `true` 或 `false`	必须为 true/false
`INT`	整数型	必须为合法数字
`LONG`	长整型	必须为合法数字
`FLOAT`	浮点型	必须为合法数字
`LIST`	列表型	不支持默认值
`GROUP`	组类型	不支持默认值

选项 validation 规则

Option.process_default() 方法会在解析时对默认值进行类型校验：

BOOL 类型：默认值必须是 true 或 false （大小写敏感）。
INT / LONG / FLOAT 类型：默认值必须能通过 float() 转换。
LIST / GROUP 类型：不允许设置默认值，否则抛出 ValueError。

示例：

<Option name="top" description="顶层模块名称" type="STRING" default="" positional="true" internal="false"/>
<Option name="verbose" description="详细输出模式" type="BOOL" default="false" positional="false" internal="false"/>

孙子元素：Group

<Group> 元素定义选项之间的约束关系（互斥、依赖、同时出现等）：

属性	类型	必填	说明
`name`	string	是	组名称
`type`	string	否	约束类型，默认为 `TYPE_NONE`
`target`	string	否	目标选项名

支持的五种约束类型：

type 值	枚举	含义
（空）	`TYPE_NONE`	无约束
`conflict`	`TYPE_CONFLICT`	组内选项互斥
`dependent`	`TYPE_DEPENDENT`	组内选项有依赖关系
`least`	`TYPE_LEAST`	组内选项至少选择一个
`together`	`TYPE_TOGETHER`	组内选项必须同时出现

Group 通过子元素 <Option> 指定组内成员选项：

<Group name="output_group" type="conflict" target="">
    <Option name="output"/>
    <Option name="write"/>
</Group>

完整 XML 示例

<?xml version="1.0" encoding="UTF-8"?>
<Module name="read_verilog" description="读取和分析 Verilog 网表">

    <Command name="read_verilog" description="读取 Verilog 设计文件" internal="false">
        <Option name="top" description="指定顶层模块名称" type="STRING" default="" positional="true" internal="false"/>
        <Option name="verbose" description="输出详细信息" type="BOOL" default="false" positional="false" internal="false"/>
        <Option name="library" description="指定搜索库路径" type="LIST" default="" positional="false" internal="false"/>

        <Group name="output_mode" type="conflict" target="">
            <Option name="output"/>
            <Option name="write"/>
        </Group>
    </Command>

</Module>