该设计已于 2026-08-02 实现。ErLando 内置实例已全部迁移到
-erlando_instance(...);rebar3_erlando 0.3.0 优先消费 schema 1
的 erlando_instance_meta,并兼容旧属性协议。以下“当前编译链”描述的是迁移前的 legacy 路径,保留用于解释兼容设计。
统一 capability 注册、Erlang behaviour、capability Adapter 生成和跨 Transformer 函数分派,同时保留当前模块划分:
typeclass Interface
→ typeclass_trans 动态派发
→ Transformer 本体 Implementation
→ monad_*_instance 跨层 Implementation
本设计不合并类型类模块、Transformer 模块或跨层实例模块。目标是让每个 {Type, Typeclass} mapping 只声明一次,并在编译期发现注册、callback、Adapter 和 dispatch 不一致。
当前 rebar3_erlando 从 BEAM attributes 读取:
-superclass(...):识别 typeclass Interface;superclass 列表当前不参与继承展开。-erlando_type(...):识别 type/tag 及typeclass:type/1所需 pattern。-behaviour(...):声明 Implementation 支持的 capability。
插件将同一 Module 的 types 和 behaviours 做笛卡尔积,生成:
{Type, Typeclass} → Implementation Module
最终写出生成的 typeclass.beam:
typeclass:type/1typeclass:is_typeclass/1typeclass:module/2
gen_fun 是 Adapter 生成器。它从 behaviour_info(callbacks) 读取 callback,根据 inner_type、remote、patterns 和 arity mode 生成转发函数。它还用于 map/run/with 等非 capability helper,因此不能直接成为实例注册 Interface。
跨层实例 Module 使用 -erlando_type([...]) + -behaviour(...) 注册多个 Transformer,而实际语义由 lift_callCC/lift_local/lift_listen/... 等函数分支提供。当前编译链无法证明注册列表中的每个 type 都有实现分支。
新增窄语义宏:
-erlando_instance(...).该宏是 capability mapping 的单一声明来源。它不接管 Transformer 的语义 Implementation,也不取代用于普通 helper 的 gen_fun。
新宏应生成或保留:
erlando_typemetadata- Erlang behaviour attributes
- capability callback exports
- 必要的
gen_funAdapter forms - 规范化、带版本的
erlando_instance_metaBEAM metadata - 特殊实例所需的公开 callback dispatch clauses
erlando_instance 是 Astranaut attribute macro。as_attr 只负责让:
-erlando_instance(Spec).被识别为宏调用;展开完成后,原 attribute 会被生成 forms 替换,不会自动保留在 BEAM 中。因此宏必须显式生成真正的普通 metadata attribute。
宏声明建议为:
-export_macro([
{erlando_instance/2,
[{inject_attrs, [module]},
{as_attr, erlando_instance}]}
]).宏展开结果必须包含:
-erlando_instance_meta({1, NormalizedInstance}).对应 abstract form:
{attribute, Line, erlando_instance_meta,
{1, NormalizedInstance}}不能重新生成同名 erlando_instance attribute,否则 Astranaut scanner 会再次把它识别为宏并递归展开。
metadata 使用独立名称和显式版本号:
erlando_instance:源码层宏 Interface。erlando_instance_meta:BEAM 层稳定消费 Interface。1:metadata schema 版本。
NormalizedInstance 不能直接保存未经处理的用户输入。宏必须先:
- 展开
?MODULE等编译期信息。 - 补齐默认值。
- 将 capability 列表展开成确定的 mapping。
- 将 generic/dispatch/adapter 策略转成规范形式。
- 排序所有 map/list 中不具语义的顺序,保证构建结果稳定。
建议规范化结构表达为普通 Erlang literal,例如:
#{
module => state_t,
types => [state_t],
instances => [
#{type => state_t,
typeclass => functor,
implementation => local,
adapter => #{adapter => source, requires => functor}},
#{type => state_t,
typeclass => monad,
implementation => local,
adapter => #{adapter => source, requires => monad}}
]
}为了兼容一个 Module 中的多次宏调用,插件应使用:
proplists:get_all_values(erlando_instance_meta, Attributes)读取全部 metadata,而不是只取第一个值。插件必须拒绝未知 schema 版本,错误中包含 Module 和版本号。
以 StateT 为例:
-erlando_instance(#{
type => {?MODULE, [state_t/3]},
adapters => [
#{
mode => source,
requires => functor,
capabilities => [functor]
},
#{
mode => source,
requires => monad,
capabilities =>
[applicative, monad, monad_trans, monad_state]
},
#{
mode => source,
requires => monad_plus,
capabilities => [alternative, monad_plus]
}
],
manual => [monad_runner]
}).字段含义:
type:生成现有erlando_typemetadata,供类型识别和实例注册使用。adapters:按相同生成策略分组的 Adapter map 列表。capabilities:该 Adapter 分组覆盖的 typeclass Interface。requires:生成 convenience Adapter 时要求的底层 capability;使用固定args的 source Adapter 可以省略。mode => source:根据 typeclass callback 生成面向调用者的低 arity Adapter。mode => target:为核心实现补充 type/descriptor 参数。manual:Module 自己实现并导出 callback、不生成 convenience Adapter 的 capability 列表。
旧的逐 capability capabilities tuple 列表继续作为兼容输入。宏会先把两种源码语法规范化成相同的逐 capability schema 1 metadata;两种语法重复声明同一 capability 时编译失败。
map/run/with 等非 capability helper 继续显式使用 gen_fun:
-gen_fun(#{args => monad, functions => [map/2, with/2]}).如果 callback 对所有已声明 Transformer 使用同一套完全通用逻辑,可声明:
-erlando_instance(#{
types => [reader_t, writer_t, cont_t, maybe_t,
error_t, except_t, list_t],
capability => monad_state,
implementation => generic
}).generic 表示 callback Implementation 不依赖 type-specific 分支。宏生成注册 metadata 和 behaviour,但保留 Module 中的通用 callback Implementation。
如果不同 Transformer 需要不同语义,必须显式提供每个 callback 的本地 Adapter:
-erlando_instance(#{
types => [reader_t, writer_t, state_t, maybe_t,
error_t, except_t, list_t],
capability => monad_cont,
implementation => {dispatch, #{
reader_t => #{callCC => {reader_t_call_cc, 2}},
writer_t => #{callCC => {writer_t_call_cc, 2}},
state_t => #{callCC => {state_t_call_cc, 2}},
maybe_t => #{callCC => {maybe_t_call_cc, 2}},
error_t => #{callCC => {error_t_call_cc, 2}},
except_t => #{callCC => {except_t_call_cc, 2}},
list_t => #{callCC => {list_t_call_cc, 2}}
}}
}).宏根据 typeclass callbacks 生成公开 dispatch:
callCC(F, {reader_t, _} = T) -> reader_t_call_cc(F, T);
callCC(F, {writer_t, _} = T) -> writer_t_call_cc(F, T);
%% ...
callCC(F, Type) when is_atom(Type) ->
callCC(F, {Type, monad_cont}).本地 Adapter 函数保留实际 CPS/状态/日志语义。这样 registration 与 dispatch 来自同一个 map,而编译器可以检查被引用的本地函数是否存在。
对于拥有多个 callback 的 typeclass,dispatch map 必须覆盖每个已注册 type 的全部 required callbacks。可以支持 default Adapter 减少真正通用 callback 的重复,但展开后的规范化 metadata 必须是完整的 {Type, Typeclass, Callback} → Adapter mapping。
新增宏之前,先增强 rebar3_erlando validator。
必须检查:
- 同一个
{Type, Typeclass}不能由不同 Module 静默覆盖。 - Implementation Module 必须导出 typeclass 的全部 required callbacks。
gen_fun引用的 capability 必须存在于 Module 的 instance/behaviour 声明中。- dispatch 模式必须覆盖所有
{Type, Callback}组合。 - dispatch 引用的本地 Adapter 函数必须存在且 arity 正确。
- 重复声明如果完全相同可以去重;不一致必须编译失败。
- optional callbacks 不能被当作 required callback。
当前 maps:merge 对冲突 mapping 的静默覆盖必须改成显式错误。
不能依赖函数名自动反推 capability。helper、default Implementation、不同 arity Adapter 和宏生成函数会造成歧义;capability 是语义声明,必须显式存在。
也不能仅靠 AST 静态证明跨层语义正确。编译期 validator 负责结构完整性,行为矩阵测试负责运行语义。
第一阶段,新宏展开为现有标准 attributes 和 forms:
erlando_typebehaviourgen_fun生成结果
因此 rebar3_erlando 初期仍可以按旧协议消费 BEAM,无需立即切换 registry 格式。
同时由宏显式生成带版本的 erlando_instance_meta attribute,为后续插件直接读取新格式做准备。不能依赖宏调用本身被保留。
兼容周期内:
- 外部项目仍可使用旧
-erlando_type/-behaviour/-gen_fun写法。 - 新宏和旧写法同时存在时必须验证结果一致。
- 新宏完成全量迁移后,再对 capability 相关的旧组合写法发出 deprecated warning。
- 非 capability helper 的
gen_fun不废弃。
在 rebar3_erlando 中增加:
- 当前 mapping 生成的 characterization tests。
- callback export 验证。
- mapping 冲突检测。
gen_fun/behaviour capability 一致性验证。- 缺失 callback 和冲突 mapping 的失败型 fixture。
该阶段不改变 ErLando 源码声明。
从 gen_fun_macro 抽取纯生成 Implementation,使以下两个 Interface 共用同一逻辑:
- 旧
gen_fun - 新
erlando_instance
旧 gen_fun 的现有输出必须保持兼容。
新增建议文件:
src/erlando_instance_macro.erl
include/erlando_instance.hrl
宏负责规范化声明、显式生成 erlando_instance_meta、生成兼容 attributes、behaviours、capability Adapter 和可选 dispatch。
该阶段必须增加一个 BEAM-level 测试:编译 fixture 后通过 beam_lib:chunks(Beam, [attributes]) 读取并断言 erlando_instance_meta 的版本和规范化内容。只检查宏返回 forms 不足以证明 metadata 真正进入 BEAM。
先迁移三类 Adapter:
identity或list_instance:直接实例、target arity Adapter。state_t:带底层约束的 Transformer、source arity Adapter。monad_cont_instance:逐 type 特殊 dispatch。
三类迁移通过后再冻结宏 Interface。
- 枚举规范化
{Type, Typeclass}mapping。 - 为通用跨层实例增加代表性调用测试。
- 为特殊 dispatch 验证每个 registered type。
- 迁移其余直接实例和跨层实例。
- 更新 README 和 review。
兼容验证稳定后,允许 rebar3_erlando 优先读取 erlando_instance_meta metadata,并回退到旧 attributes。
只有经过一个外部兼容周期后,才考虑停止通过 erlando_type × behaviour 推导 capability mapping。
- 普通实例展开结果。
- source/target arity Adapter。
- manual capability。
- generic 跨层 Implementation。
- dispatch 跨层 Implementation。
- callback exports 和 original function 合并。
- optional callbacks。
- 规范化 mapping 生成正确。
- legacy attributes 保持兼容。
- 相同 mapping 去重。
- 冲突 mapping 编译失败。
- 缺失 callback 编译失败。
- 缺失 dispatch Adapter 编译失败。
gen_funcapability 漂移编译失败。
- ErLando Common Test 全部通过。
- xref 通过。
- Dialyzer 通过。
- Cover 无生成模块警报。
- async Common Test 和 xref 通过。
- OTP 21 与 OTP 29 的 docker CI 通过。
- 生成的
typeclass:module/2mapping 与迁移前一致。
不采用。gen_fun 同时服务 capability Adapter 和普通 helper forwarding,把 registration 塞入其中会扩大 Interface,并让没有 gen_fun 的跨层实例无法统一。
不采用。函数名和 arity 不能可靠表达语义,default/helper/remote forwarding 会造成歧义。
不采用。它会产生大量浅层 Adapter Module,降低 Locality,并把同一 effect 的提升规则分散到多个文件。
不采用。宏只生成声明、Adapter 和 dispatch boilerplate;lift_local/lift_listen/callCC 等真实语义必须留在对应 Implementation Module。
应当新增 -erlando_instance(...) 宏,但必须遵循以下顺序:
- 先增加编译期 validator。
- 再抽取并复用
gen_funAdapter 生成核心。 - 然后实现兼容型 instance 宏。
- 最后迁移特殊 dispatch 和其余实例。
新宏解决 capability mapping 的单一声明问题;插件 validator 和行为矩阵共同保证结构与语义正确。仅把旧三个属性包装进一个宏,不能解决函数分支漂移问题。