Files
endorphin-tessera-gui/src/bridge/ui_bridge/signatures.rs
T

293 lines
16 KiB
Rust

//! 声明宿主方法在 Endor 类型系统中的参数和返回契约。
//! 签名用于构造/调用检查,应与 calls 和各 NativeCallable 实现保持一致;这里不执行实际业务操作。
//!
//! bootstrap 在类型安装的第二阶段调用这两个函数,把完整签名写入 TypeMethod、Function 和 NativeFactory。
//! ui_bridge::bind 也会为状态对象的绑定函数调用 operation_signature。
//! VM 随后在调用边界读取这些签名,验证数量、类型及调用效果;业务实现位于 calls/scene3d 等模块。
//! 参数注解并不决定是否必填:Operation::arity 给出实参数量,注解表则检查实际出现的每一个参数。
use super::*;
/// bootstrap 安装实例方法时调用,构造包含 receiver 的 VM 方法契约。
/// receiver 是方法声明所在类型,不是某次调用的实例;实际接收者可以是该类型的合法子类。
pub(super) fn method_signature(
store: &endor_core::ObjectStore,
desktop: ObjectRef,
receiver: ObjectRef,
operation: Operation,
) -> Result<CallSignature, VmError> {
use AnnotationType::{Any, Function, Nominal, Number, String as TextType, Unit};
use Operation::*;
// 闭包把宿主约定的名字解析成当前 desktop 的真实 Type;查找失败中止安装,不能降级为 Any。
let nominal = |name| desktop_type(store, name, desktop).map(Nominal);
// 先描述显式实参,不含隐式 receiver;后面统一在 parameters 首部补接收者。
// ReadOnly/Mutating/External 是 VM 调用效果契约,不是线程调度策略。
let (arguments, returns, effect) = match operation {
// 三个数分别供位置/旋转操作使用;方法修改现有三维对象,没有额外返回值。
Translate3D | Rotate3D => (vec![Number, Number, Number], Unit, CallEffect::Mutating),
// 控制器处理被控对象和相机手势;手势是类型化协议值,不能接任意文本或标量。
CameraControl => (
vec![nominal("Object")?, nominal("CameraGesture")?],
Unit,
CallEffect::Mutating,
),
// 绑定创建可取消 Subscription,并改写目标连接关系,因此属于 Mutating。
Bind => (
vec![TextType, Function],
nominal("Subscription")?,
CallEffect::Mutating,
),
// 查询已有出现位置,返回托管列表;不修改对象或展示关系。
Mounts => (vec![], nominal("ObjectList")?, CallEffect::ReadOnly),
// Children 的实际值仍由容器实现解释;这里的 Any 不改变只读效果约束。
Children => (vec![], Any, CallEffect::ReadOnly),
// 可选文本用于标记失效类别;是否可省略由 arity 决定,非此处的 vec 长度决定。
Invalidate => (vec![TextType], Unit, CallEffect::Mutating),
// 修改既有文本/颜色,内容合法性(如颜色格式)由调用实现进一步校验。
SetText | SetColor => (vec![TextType], Unit, CallEffect::Mutating),
// append/insert 返回稳定 slot 数值;remove/replace/move 返回 Unit,调用方不能把它们当返回孩子对象的集合方法。
Append => (vec![nominal("Block")?], Number, CallEffect::Mutating),
Insert => (
vec![Number, nominal("Block")?],
Number,
CallEffect::Mutating,
),
// 数字注解只验证 Number;非负整数、稳定槽位是否存在等语义由 calls 检查。
Remove => (vec![Number], Unit, CallEffect::Mutating),
Replace => (vec![Number, nominal("Block")?], Unit, CallEffect::Mutating),
Move => (vec![Number, Number], Unit, CallEffect::Mutating),
// 页面内容替换/导航接受可视 Block,并改写待展示状态;此处不提前执行布局。
Render | Navigate => (vec![nominal("Block")?], Unit, CallEffect::Mutating),
// 链式 API 返回声明 receiver 的名义类型;源子类实例也满足此基类契约,不承诺精确动态子类。
OnClick => (vec![Function], Nominal(receiver), CallEffect::Mutating),
// 事件和生命周期方法可能执行任意用户回调,使用 External,不能冒充只读视觉查询。
OnEvent => (vec![nominal("Event")?], Unit, CallEffect::External),
// Mount 标识一次具体出现位置;同一 Block 的多次展示不能共用一个隐式上下文。
OnMount | OnUnmount => (vec![nominal("Mount")?], Unit, CallEffect::External),
// click/dispatch 返回实际事件,便于调用者观察传播状态;Mount 可选性由 arity 给出。
Click => (
vec![nominal("Mount")?],
nominal("Event")?,
CallEffect::External,
),
Dispatch => (
vec![nominal("Event")?, nominal("Mount")?],
nominal("Event")?,
CallEffect::External,
),
// 迁移要求真实 Window 实例并返回页面,窗口是否关闭、是否属于当前运行时由实现继续检查。
MoveWindow => (
vec![nominal("Window")?],
Nominal(receiver),
CallEffect::Mutating,
),
// 标签位置是数值,Activate 无显式实参;二者都改变展示选择并允许链式使用。
MoveTab => (vec![Number], Nominal(receiver), CallEffect::Mutating),
Activate => (vec![], Nominal(receiver), CallEffect::Mutating),
// detach 新建目标窗口,返回 Window 而非当前页面;资源创建属于修改操作。
Detach => (vec![], nominal("Window")?, CallEffect::Mutating),
// 这些操作只修改生命周期或历史状态,均没有业务返回值。
Unmount | Close | CloseWindow | Back | Forward => (vec![], Unit, CallEffect::Mutating),
// 先以 Any 占位,后面用 nullable(Window) 收窄,允许省略/显式 nil 选择默认归属。
Open => (vec![Any], Nominal(receiver), CallEffect::Mutating),
// 页面尚未打开时无所属窗口,稍后把返回 Any 改为 Window | nil。
PageWindow => (vec![], Any, CallEffect::ReadOnly),
// 事件名、回调和可选捕获选项;返回 Subscription 令牌供取消,不直接返回 receiver。
On => (
vec![TextType, Function, Any],
nominal("Subscription")?,
CallEffect::Mutating,
),
// 自由工厂 Operation 不应误装成实例方法;缺少明确契约就拒绝安装,防止默认放宽检查。
_ => return Err(invalid("unsupported native method signature")),
};
// Operation 维护显式参数的必需/最大个数;方法签名整体加一,将 receiver 纳入调用约定。
let arity = operation.arity();
// parameters[0] 固定为 receiver,因此后面细化显式参数时都必须把索引加一。
let mut parameters = vec![Nominal(receiver)];
parameters.extend(arguments);
// 先把简单 AnnotationType 升格为 CallType;下面再改写少数联合/可空位置。
let mut signature = CallSignature {
arity: endor_core::CallArity::range(arity.required + 1, arity.maximum + 1),
parameters: parameters.into_iter().map(CallType::from).collect(),
variadic: None,
returns: returns.into(),
effect,
};
// 少数参数/返回需要联合或可空类型,先用占位 Any 建基础签名,再按下标细化。
// On 第三个显式选项位于 parameters[3],可接受 Bool 或字符串。
match operation {
// 参数允许 nil,但非空值必须是本 desktop 注册的 Window 实例。
Open => signature.parameters[1] = CallType::nullable(nominal("Window")?),
// 没有归属是正常查询结果,与错误窗口对象的类型失败不同。
PageWindow => signature.returns = CallType::nullable(nominal("Window")?),
// 兼容布尔捕获标记和命名阶段字符串;具体字符串语义在事件连接操作中检查。
On => signature.parameters[3] = CallType::Union(vec![AnnotationType::Bool, TextType]),
// 其余操作已经完整表达,不应额外增加可空或联合类型。
_ => {}
}
Ok(signature)
}
/// bootstrap 和 ui_bridge::bind 调用,描述不含 receiver 的自由函数/状态绑定函数原生参数。
/// NativeFactory 复用本结果作为 options 窄签名,再在外部包上 Type 首参和源子类字段。
pub(super) fn operation_signature(
store: &endor_core::ObjectStore,
desktop: ObjectRef,
operation: Operation,
) -> Result<CallSignature, VmError> {
use AnnotationType::{Any, Bool, Number, String as TextType, Trait, Type, Unit};
use Operation::*;
// 注册表来自所属 VM 的 desktop;同名但不同身份的外部 Type 不能满足当前名义契约。
let nominal = |name| desktop_type(store, name, desktop).map(AnnotationType::Nominal);
// 自由 UI 操作没有隐式 receiver;同时声明固定参数、可变尾参、返回名义类型和调用效果。
let (parameters, variadic, returns, effect) = match operation {
// 类型关系查询不改变类型表;IsInstance 签名首参为 Any,但 calls 当前仍要求实际值为对象。
IsInstance => (vec![Any, Type], None, Bool, CallEffect::ReadOnly),
IsSubtype => (vec![Type, Type], None, Bool, CallEffect::ReadOnly),
// 注册能力实现会修改类型关系;implements/supports 只查询已有关系。
Implement => (vec![Type, Trait], None, Unit, CallEffect::Mutating),
Implements => (vec![Type, Trait], None, Bool, CallEffect::ReadOnly),
Supports => (vec![Any, Trait], None, Bool, CallEffect::ReadOnly),
// open 可把普通值包装成视觉/Page 并安排展示,返回供继续操作的 Page。
OpenValue => (vec![Any], None, nominal("Page")?, CallEffect::Mutating),
// present 可能转交用户展示协议,效果交由被委托调用确定,不能声明成固定 ReadOnly。
Present => (vec![Any], None, nominal("Block")?, CallEffect::Delegated),
// state 可分配新的状态对象;ReadOnly 允许新对象初始化,不授权修改原有对象。
State => (vec![Any], None, Any, CallEffect::ReadOnly),
// set/increment 的 receiver 已存在 Function.owner 中,不计入本处参数表。
StateSet => (vec![Any], None, Unit, CallEffect::Mutating),
Increment => (vec![], None, Unit, CallEffect::Mutating),
// stats 读取宿主计数而非纯托管属性依赖,按 External 描述,不作为只读布局计算接口。
Stats => (vec![], None, Any, CallEffect::External),
// viewport 返回尺寸协议值;窗口尺寸尚缺失等情形仍由实际实现处理。
Viewport => (
vec![],
None,
nominal("MeasureResult")?,
CallEffect::ReadOnly,
),
// ui.window 查询现有窗口,Window 类型构造则创建新资源,二者不能共享调用效果。
Window => (vec![], None, nominal("Window")?, CallEffect::ReadOnly),
NewWindow => (vec![], None, nominal("Window")?, CallEffect::Mutating),
// 这些构造操作返回新对象,ReadOnly 允许分配并初始化新值,但不允许因此修改已有业务对象。
TextOf => (
vec![Any, TextType, Number, TextType],
None,
nominal("TextBlock")?,
CallEffect::ReadOnly,
),
// TextOf 前两个参数表示对象/属性名;Text 直接接收字符串,其后字号和颜色可选。
Text => (
vec![TextType, Number, TextType],
None,
nominal("TextBlock")?,
CallEffect::ReadOnly,
),
// 矩形宽高为必填,后续数值/颜色的缺省规则由 Operation::arity 与构造实现共同约束。
Rect => (
vec![Number, Number, Number, TextType],
None,
nominal("RectBlock")?,
CallEffect::ReadOnly,
),
// 空白块只需要长度;滚动块额外要求宽高和一个 Block 内容。
Spacer => (vec![Number], None, nominal("Spacer")?, CallEffect::ReadOnly),
Scroll => (
vec![Number, Number, nominal("Block")?],
None,
nominal("ScrollBlock")?,
CallEffect::ReadOnly,
),
// 布局容器前两个固定参数是 Number,其后每个尾参都必须是 Block,返回类型按具体构造器选取。
Row | Column | Overlay => (
vec![Number, Number],
Some(nominal("Block")?),
// 共享参数规则,但返回值必须保留具体容器名义类型;matches 只选择类型名,不执行排版。
nominal(if matches!(operation, Row) {
// 主轴水平排列的容器。
"Row"
} else if matches!(operation, Overlay) {
// 多个孩子叠放在同一内容区域的容器。
"Overlay"
} else {
// 此分支入口只有 Row/Column/Overlay,前两者排除后剩 Column。
"Column"
})?,
CallEffect::ReadOnly,
),
// 按钮接收初始文本,Page 无显式参数;两者都只创建值,不自动打开窗口。
Button => (
vec![TextType],
None,
nominal("Button")?,
CallEffect::ReadOnly,
),
Page => (vec![], None, nominal("Page")?, CallEffect::ReadOnly),
// 三维视口的宽高和 Scene3D 在调用边界检查;摄像机、场景元素等由场景模块继续验证。
Viewport3D => (
vec![Number, Number, nominal("Scene3D")?],
None,
nominal("Viewport3D")?,
CallEffect::ReadOnly,
),
// 3D 构造器参数来自 Kind 元数据:Number/String 映成基础注解,其余名称从本 desktop 注册表查名义类型。
SceneObject(kind) => {
// 元数据与真实构造器共用一份参数定义,避免桥接手工重复参数表后与 3D 实现漂移。
let parameters = kind
.parameters()
.iter()
.map(|name| match *name {
// 基础数值/字符串是语言原生注解,不需要到宿主类型字典查询。
"Number" => Ok(Number),
"String" => Ok(TextType),
// Vec3/Geometry3D 等名称必须解析为本会话真实 Type;未知名让整个签名安装失败。
name => nominal(name),
})
.collect::<Result<Vec<_>, VmError>>()?;
(
parameters,
// 3D 集合尾参使用 Object 名义约束;各具体构造操作仍需在实现中检查允许的场景对象类别。
if kind.variadic() {
// 允许额外对象参数的场景组等构造器用 Object 作尾参上界。
Some(nominal("Object")?)
} else {
// 固定参数构造器禁止多余实参,不能统一使用 Any 尾参放开上界。
None
},
nominal(kind.name())?,
CallEffect::ReadOnly,
)
}
// 二维场景可接受零到多个 Block;场景视口固定接宽、高、Scene2D,不把孩子直接当场景。
Scene2D => (
vec![],
Some(nominal("Block")?),
nominal("Scene2D")?,
CallEffect::ReadOnly,
),
CanvasViewport => (
vec![Number, Number, nominal("Scene2D")?],
None,
nominal("CanvasViewport")?,
CallEffect::ReadOnly,
),
// x/y/zoom 都声明为 Number,但可缺省;缩放范围等数值约束由 new_camera2d 校验。
Camera2D => (
vec![Number, Number, Number],
None,
nominal("Camera2D")?,
CallEffect::ReadOnly,
),
// 实例方法专用 Operation 不在自由函数表内,误用在这里应立即暴露安装错误。
_ => return Err(invalid("unsupported UI function signature")),
};
// 最终 arity 直接沿用 Operation,参数注解与可变尾参分开保存;不在此处执行操作或分配业务对象。
Ok(CallSignature {
arity: operation.arity(),
parameters: parameters.into_iter().map(CallType::from).collect(),
variadic: variadic.map(CallType::from),
returns: returns.into(),
effect,
})
}