Documentation
¶
Overview ¶
本文件补充官方 scope 的父作用域链(bindScopeParent / scopeParentOf / scopeChainOf)。
作用域除了"层栈叠加",还可以显式声明自己的外层(父)作用域,从而在解析时沿 祖先链向上回溯。父关系是一张有向无环图:任何绑定都会做环检测,沿父链若能走回 起点,说明会成环,立即拒绝——因为所有链消费者都要沿父走到根。
Package scope 提供分层作用域注册表(ScopedLayers)原语。
对齐上游:packages/core/scope
设计动机:
- omnix 的 Tools / Skills / Commands / Credentials 等注册表都存在"宿主级(host)定义 + 会话级 / 用户级 / 项目级覆盖"的需求, 例如:预设定义了一批工具,会话级可以隐藏其中某个;宿主级 deny 的凭据,作用域级可以 exempt;
- 本包用一套通用的「分层 + 合并 + 解析」实现复用于所有注册表,避免每个注册表各写一套作用域叠加逻辑。
解析规则(与上游一致):
- nearest-scope-wins:从最近的作用域层向 host 层逐层查找,先命中的层决定值;
- rank:同一层内同 key 存在多个注册时,rank 大者胜;
- 后注册覆盖先注册:rank 相同时,注册时间靠后者胜;
- 匿名 entry(未命名)与 named entry(具名)互不冲突:匿名条目不参与具名查找, 仅在整体遍历时按注册顺序出现。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyBound = errors.New("scope: key already bound to a parent")
ErrAlreadyBound 表示某 key 已绑定父,重复绑定被拒。
var ErrCycle = errors.New("scope: parent link would form a cycle")
ErrCycle 表示该父绑定会形成环。
Functions ¶
This section is empty.
Types ¶
type Layer ¶
type Layer[V any] struct { // contains filtered or unexported fields }
Layer 是单层作用域(同一 ScopeKey 下的条目集合)。 内部使用切片保留注册顺序,保证后注册覆盖先注册的确定性。
func (*Layer[V]) Register ¶
Register 向本层注册一条记录。
- name 为空表示匿名 entry;
- rank 越大优先级越高(同一层内同 key 冲突时);
- 返回注册序号(供调用方构造依赖顺序时使用)。
func (*Layer[V]) Unregister ¶
Unregister 从本层移除所有匹配该 name 的具名条目(匿名条目不受影响)。
type ParentTree ¶
type ParentTree struct {
// contains filtered or unexported fields
}
ParentTree 是作用域父关系注册表,并发安全。
func (*ParentTree) Bind ¶
func (t *ParentTree) Bind(key, parent Key) error
Bind 把 parent 绑定为 key 的父作用域(一次性)。
- key 已有父 → ErrAlreadyBound;
- 沿 parent 向上若遇到 key(会成环)→ ErrCycle。
func (*ParentTree) ChainOf ¶
func (t *ParentTree) ChainOf(key Key) []Key
ChainOf 返回 key → 根祖先的链(nearest-first:[key, parent, grandparent, …])。
func (*ParentTree) ParentOf ¶
func (t *ParentTree) ParentOf(key Key) (Key, bool)
ParentOf 返回 key 的父;根作用域返回 false。
func (*ParentTree) Rebind ¶
func (t *ParentTree) Rebind(key, parent Key) error
Rebind 重新链接 key 的父(同样做环检测),不要求 key 已绑定。
type ResolvedEntry ¶
ResolvedEntry 是 Merge 后的单条解析结果。
type ScopedLayers ¶
type ScopedLayers[V any] struct { // contains filtered or unexported fields }
ScopedLayers 是「host → 最近作用域」按顺序叠加的多层注册表。 层顺序:索引 0 为 host(最外层),索引越靠后作用域越近(越优先)。
func (*ScopedLayers[V]) Get ¶
func (sl *ScopedLayers[V]) Get(name string) (V, bool)
Get 按 nearest-scope-wins 规则解析具名 key 的值。 从最近层向 host 层逐层查找,任一命中即返回;全部未命中返回 false。
func (*ScopedLayers[V]) Merge ¶
func (sl *ScopedLayers[V]) Merge() []ResolvedEntry[V]
Merge 将所有层合并为一个确定性视图:
- 具名条目:按 nearest-scope-wins 解析,同层内 rank/注册序决胜,输出唯一一份;
- 匿名条目:全部保留(来自不同层、按注册顺序)。
返回值按名称字典序 + 匿名条目在前的规则排序,保证多次调用输出逐字节一致。
func (*ScopedLayers[V]) Push ¶
func (sl *ScopedLayers[V]) Push(layer *Layer[V]) *ScopedLayers[V]
Push 追加一层作用域(追加后成为"最近的"作用域,优先于之前所有层)。 host 层应最先 Push。