293 lines
16 KiB
Rust
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,
|
|
})
|
|
}
|