XML 命令定义格式
==================

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

- ``Script/source/CmdSource/``
- ``Sta/CmdSource/``

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

根元素：Module
--------------

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

.. list-table::
   :header-rows: 1

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

示例：

.. code-block:: xml

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

子元素：Command
---------------

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

.. list-table::
   :header-rows: 1

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

示例：

.. code-block:: xml

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

孙子元素：Option
----------------

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

.. list-table::
   :header-rows: 1

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

支持的类型：

.. list-table::
   :header-rows: 1

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

选项 validation 规则
~~~~~~~~~~~~~~~~~~~~

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

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

示例：

.. code-block:: xml

   <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>`` 元素定义选项之间的约束关系（互斥、依赖、同时出现等）：

.. list-table::
   :header-rows: 1

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

支持的五种约束类型：

.. list-table::
   :header-rows: 1

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

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

.. code-block:: xml

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

完整 XML 示例
-------------

.. code-block:: 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>