分析声明，而不执行函数体¶
声明一个 Digital 程序块，绑定符号，再查看前端生成的语义表示。请先完成数字参数，使用安装好的环境。本课不进行数值模拟。
被装饰函数的函数体会把参数追加到 body_calls 列表，便于观察它是否被执行。先预测：声明和分析结束后，列表仍应为空。默认装饰器读取函数签名和声明的要求；调用装饰后的对象时，生成的是调用记录，不是执行原 Python 函数体。
从语法记录进入语义分析¶
"""把带源码位置的 Hybrid 声明从 Syntax AST 降低为 Semantic HIR。
这个示例只走编译前端，不执行量子程序。输出用于对照节点标识、符号绑定、
源码位置和诊断信息；数值计算不在本例范围内。
"""
from __future__ import annotations
import json
from cascaqit.syntax import (
ParameterSpec,
SymbolBinding,
SymbolRef,
analyze,
digital_block,
program_syntax,
)
body_calls: list[float] = []
@digital_block(
qubits=("q0",),
parameters={"theta": ParameterSpec(unit="rad")},
capabilities=("gate.rx",),
)
def rotate(theta: float) -> None:
"""声明一个 typed Digital block，但不执行它的函数体。"""
body_calls.append(theta)
def main() -> None:
"""构建 Syntax AST、绑定符号并检查 Semantic HIR。"""
syntax = program_syntax(
"lesson.compiler.beginner",
blocks=(rotate,),
invocations=(rotate(SymbolRef("theta"), mapping={"q0": "logical.0"}),),
)
analysis = analyze(
syntax,
symbols={
"theta": SymbolBinding(name="theta", dtype="float", unit="rad", value=0.25)
},
available_capabilities=("gate.rx",),
)
if analysis.hir is None:
raise RuntimeError([item.to_dict() for item in analysis.diagnostics])
payload = {
"track": "compiler_engineer",
"level": "beginner",
"lesson": "syntax_hir",
"facts": {
"syntax_block_count": len(syntax.blocks),
"hir_block_kinds": [block.block_kind for block in analysis.hir.blocks],
"diagnostic_codes": [item.code for item in analysis.diagnostics],
"syntax_hash_present": len(syntax.stable_hash()) == 64,
"hir_hash_present": len(analysis.hir.stable_hash()) == 64,
"function_body_executed": bool(body_calls),
},
"boundaries": {
"hardware_execution": False,
"cloud_execution": False,
"network_accessed": False,
"credentials_loaded": False,
},
}
print(json.dumps(payload, sort_keys=True))
if __name__ == "__main__":
main()
python3 examples/user/tracks/compiler_engineer/01_beginner_syntax_hir_zh.py
| 表示 | 本例记录的信息 |
|---|---|
| 语法 AST | 名为 rotate 的程序块、一次调用、符号参数和逻辑映射。 |
| 语义 HIR | 已解析的参数类型、单位、数值、所需能力和带来源信息的程序块。 |
| 可执行程序 | 本例只声明签名，尚未产生。 |
SymbolRef('theta') 指向待解析的值；SymbolBinding 提供类型为浮点数、单位为 rad、数值为 0.25 的绑定。映射把程序块内部的 q0 连接到外部逻辑身份 logical.0。能力列表说明当前分析环境允许 gate.rx。
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"diagnostic_codes": [],
"function_body_executed": false,
"hir_block_kinds": [
"digital"
],
"hir_hash_present": true,
"syntax_block_count": 1,
"syntax_hash_present": true
},
"lesson": "syntax_hir",
"level": "beginner",
"track": "compiler_engineer"
}
成功后，HIR 中有一个 Digital 程序块，诊断代码列表为空。function_body_executed 根据前述列表实际计算，预期为 false。哈希标识生成的表示，不表示已经模拟了旋转。
函数名 rotate 和能力声明 gate.rx 本身不会实现 RX。本例函数体是用于观察执行的记录操作，没有量子门声明，而且不会被调用。编写编辑器或转换工具时，需要区分声明信息与可执行程序。
每次破坏一项语义条件¶
- 从传给
analyze的symbols映射中移除theta。 - 恢复该项，但把绑定单位改为
us，参数声明仍要求rad。 - 恢复单位，再将
available_capabilities改为空元组。
三种诊断依次为 SEMANTIC_SYMBOL_UNBOUND、SEMANTIC_PARAMETER_UNIT_MISMATCH 和 SEMANTIC_CAPABILITY_UNSUPPORTED。分析失败时不会返回 HIR，不应自行补猜一份部分表示继续处理。三种情况下函数体记录列表都为空。接入编辑器时，可将诊断代码、对象路径和可用的源码位置一起展示，帮助定位声明。
另一个选项 lower_body=True 可以静态解析受限的门和控制声明语言，仍不会执行任意 Python。本例的列表追加不属于支持的声明，不能打开这个选项来执行记录操作。Hybrid 语法指南列出了支持的声明及源码捕获限制。下一课介绍依赖图和执行计划。