236 lines
13 KiB
Markdown
236 lines
13 KiB
Markdown
# TP
|
||
|
||
TP 2.0 是一个可独立使用的 Emacs retained/reactive text runtime。它把声明式属性、响应式数据和稳定文本对象投影到 string 与 buffer，并拥有文本属性 contribution 合成、精确依赖追踪、保留式身份、marker-backed mount、diff、事务、回滚和最终 Buffer publication。
|
||
|
||
TP 不依赖 Ebox 或 ECSS，也不实现 CSS selector、stylesheet、specificity、cascade winner、Box、Flex、Grid、测量或布局。需要 CSS 的调用者可以先用 ECSS 算出最终 declarations，再交给 TP 发布；TP 自身只理解 Emacs 文本属性和通用 retained text surface。
|
||
|
||
英文文档：[README.md](README.md)。
|
||
|
||
完整公共 API 参考：[API-REFERENCE.md](docs/API-REFERENCE.md)。本文负责概念
|
||
和快速开始；API 参考按当前 TP 2.0 源码列出入口、参数语义、返回值和用法。
|
||
|
||
## 运行要求
|
||
|
||
- Emacs 28.1 或更高版本。
|
||
- 没有第三方运行时依赖。
|
||
|
||
```elisp
|
||
(add-to-list 'load-path "/path/to/tp")
|
||
(require 'tp)
|
||
```
|
||
|
||
## 选择最小的公共入口
|
||
|
||
| 需求 | API | 是否建立 live runtime |
|
||
| --- | --- | --- |
|
||
| 返回带属性的字符串 | `tp-propertize` | 否 |
|
||
| 一次性装饰已有 buffer 范围 | `tp-apply` | 否 |
|
||
| 响应式装饰 host-owned 文本 | `tp-watch` | 是，`properties` capability |
|
||
| 管理 retained text content | `tp-surface-mount` / `tp-surface-update` | 是，`content` capability |
|
||
| 检查或卸载 retained publication | `tp-surface-report` / `tp-surface-inspect` / `tp-surface-unmount` | 是 |
|
||
|
||
一次性 API 和 retained API 使用相同的 property policy 与 projection 语义。一次性调用不会创建 object、binding、marker、subscription 或 surface state。
|
||
|
||
## 静态文本属性
|
||
|
||
```elisp
|
||
(let* ((callback (lambda (_window _object _position) "Open"))
|
||
(text
|
||
(tp-propertize
|
||
"Hello"
|
||
(list 'face '(:foreground "white" :background "navy")
|
||
'help-echo callback
|
||
'keymap nil))))
|
||
text)
|
||
```
|
||
|
||
显式 `nil` 和属性不存在是两种状态。上例中的 `keymap` 存在且值为 `nil`。函数对象始终是 literal data，因此 TP 会保留 `callback`，不会调用它。
|
||
|
||
一次性修改已有范围而不改变文字：
|
||
|
||
```elisp
|
||
(with-current-buffer (get-buffer-create "*tp-demo*")
|
||
(erase-buffer)
|
||
(insert "abcdef")
|
||
(tp-apply (current-buffer) 2 5 '(face italic)))
|
||
```
|
||
|
||
原有的 `tp-set`、`tp-reset`、`tp-add`、`tp-remove`、`tp-clear`、`tp-get`、`tp-at`、`tp-member`、match、regexp、search、navigation、interval 和 native query API 继续作为普通文本属性操作的直接 façade。
|
||
|
||
## 可复用声明配方
|
||
|
||
`define-tp` 和 `define-tps` 定义可以展开为直接 Emacs 属性的复用配方。它们只是 definition-time convenience，不是 live mounted layer，也不会把 identity 或 provenance 写入显示文本。
|
||
|
||
```elisp
|
||
(define-tp link-style (foreground)
|
||
`(face (:foreground ,foreground :weight bold)
|
||
mouse-face highlight
|
||
help-echo "Open item"))
|
||
|
||
(tp-set "Project" '(link-style "#58a6ff"))
|
||
```
|
||
|
||
属性值需要求值时使用 `tp-computed`；任何普通函数对象仍然按 literal 保存。
|
||
|
||
```elisp
|
||
(defvar my-height 1.2)
|
||
|
||
(define-tp sized-label ()
|
||
`(face ,(tp-computed (lambda () (list :height my-height)))))
|
||
```
|
||
|
||
computed function 在当前 binding/prepare context 中执行，因此其中的 `tp-signal-read` 和 `tp-binding-read` 会建立精确依赖。返回值只 normalize/project 一次，然后作为 literal data 使用。
|
||
|
||
## 响应式已有文本
|
||
|
||
`tp-watch` 装饰 marker-backed host range，但不拥有或替换其中的文字：
|
||
|
||
```elisp
|
||
(let ((online (tp-signal-create nil)))
|
||
(with-current-buffer (get-buffer-create "*tp-status*")
|
||
(erase-buffer)
|
||
(insert "offline")
|
||
(tp-watch
|
||
(current-buffer) 1 8
|
||
(lambda ()
|
||
(list 'face
|
||
(list :foreground
|
||
(if (tp-signal-read online) "green" "red")))))))
|
||
```
|
||
|
||
signal 在被读取时记录真正依赖它的 binding。修改一个 signal 只会使它的订阅者失效；条件分支改变后，不再读取的 source 会自动取消订阅。相等写入是 no-op，`tp-with-transaction` 内的重复写入会让每个受影响 binding 最多重算一次。
|
||
|
||
`tp-watch` 返回底层 surface handle，可以交给 `tp-surface-inspect`、`tp-surface-report` 或 `tp-surface-unmount`。
|
||
|
||
## Retained content
|
||
|
||
retained producer 接收 prepare context，在生成输出前取得稳定 object、安装 object-local binding，并返回纯 surface plan：
|
||
|
||
```elisp
|
||
(let* ((status (tp-signal-create "ready"))
|
||
(producer
|
||
(lambda (context)
|
||
(let* ((object (tp-object-ensure context nil 'status 'text))
|
||
(binding
|
||
(tp-bind object '(demo . status)
|
||
(lambda () (tp-signal-read status)))))
|
||
(tp-surface-plan-create
|
||
:key 'status
|
||
:kind 'text
|
||
:text (tp-binding-read binding)
|
||
:props '(face bold)
|
||
:capability 'content))))
|
||
(buffer (get-buffer-create "*tp-retained*"))
|
||
(surface
|
||
(tp-surface-mount buffer producer '(:capability content))))
|
||
(tp-signal-set status "done")
|
||
(tp-surface-report surface))
|
||
```
|
||
|
||
plan 字段只有 `key`、`kind`、`text`、`props`、`children`、`tags` 和 `capability`，不包含 marker、buffer position、patch operation、producer closure 或 client continuation。普通 constructor 会防御性复制调用者持有的 string 和 property data；candidate-local producer 只有在转移所有嵌套值且不再暴露它们时，才能使用显式的 `-owned` plan/result constructor。Owned result 必须绑定当前 active prepare context，并且只消费一次。
|
||
|
||
稳定身份只在一个 surface 内有效。`tp-object-ensure` 按 parent、sibling key 和 kind reconcile；`tp-object-resolve` 按 key path 返回 live opaque handle。`tp-surface-update-scoped` 接收完整 candidate，但只授权一个或多个 retained object 当前 mount 范围内的输出变化；除非调用者显式选择 root fallback，否则越界变化会直接失败。
|
||
|
||
`tp-surface-materialize-string` 使用相同 producer/plan 语义生成一次性 string，但不建立 live surface。返回前会释放 ephemeral object、binding、subscription 和 anchor。
|
||
|
||
## Host range 与属性所有权
|
||
|
||
`properties` capability 使用 opaque range anchor。producer 通过 `tp-range-anchor-create` 创建 anchor，再用 `tp-object-attach-range` 挂到 object 上。marker 跟随 host edit，而 plan 仍然不携带位置。
|
||
|
||
TP 为每个 property interval 保存 host baseline 和各个 TP contribution。重叠 contribution 通过已注册的 property policy 合成。如果外部代码在 TP publication 后修改同名属性，下一次更新会报告 `tp-property-conflict`，不会覆盖外部值。`tp-range-rebase` 显式接受当前 host 值作为新 baseline。unmount 只恢复仍由 TP 拥有的值，并保留冲突的 host edit。
|
||
|
||
## 事务与失败语义
|
||
|
||
`tp-with-transaction` 批量处理 signal writes 和所有实际受影响的 surfaces。TP 先 prepare 所有 candidate，再按稳定顺序 publish。compute、validation、buffer write、marker/index publication 或 transaction participant 任一步失败，signal values、binding values/dependencies、文本、属性、marker、index、plan、client state、revision 和 previous report 都会一起恢复。
|
||
|
||
observer 只在成功提交之后运行，observer failure 只记录，不回滚已完成的 transaction。publication 过程中被 kill 的 buffer 保持死亡，rollback 不会把它重新创建。
|
||
|
||
TP 2.0 从 transaction-scoped batch 的 exact entries、同一个冻结 participant
|
||
vector 和 candidate-bound final accept 驱动唯一 live publication；journal、
|
||
surface snapshot 与 change group 仍只保留一份。transaction participant 统一通过
|
||
`tp-transaction-participate-v2` 注册，不再提供备用 transaction writer 或 runtime
|
||
route switch。generic opaque authority marker 在 final accept 前
|
||
完成固定上界与 whitelist 校验；partial apply 或 accept failure 时先逆序恢复
|
||
marker，再执行普通 rollback。`tp-with-transaction` 仍返回 body result，内部
|
||
outcome 仅作为只读 side-channel evidence。
|
||
|
||
ETAF 集成复用同一事务边界，只注册一个 opaque transaction participant。ETAF
|
||
先准备 immutable generation 和 Ebox candidate，再由 TP 按固定顺序完成
|
||
participant publish、TP final accept 和 post-accept cleanup。participant failure
|
||
会恢复旧 generation 与 client state；accept 之后的 observer failure 只保留为
|
||
diagnostic。ETAF 的 Runtime fixed-point guard 会在一次 flush 中记录每个
|
||
effect 的 input/version tuple，重复或超过图规模上限时停止循环，不会静默自旋。
|
||
|
||
## Property policy
|
||
|
||
`tp-define-property-policy` 为一个最终 Emacs text property 注册通用语义：
|
||
|
||
- normalization 与 validation；
|
||
- no-op 判断使用的 equality；
|
||
- contribution merge；
|
||
- 到最终 property value 的 projection；
|
||
- 包括 present `nil` 在内的显式 presence。
|
||
|
||
`tp-register-text-property` 为原生 property 建立默认 policy。`face` contribution 使用 merge 语义，其他属性使用各自注册的 policy。`tp-merge-declarations`、`tp-define-style` 和 `tp-style-declarations` 只处理 direct declarations，不实现 CSS cascade。
|
||
|
||
## 公共 runtime API 家族
|
||
|
||
| 家族 | 主要公共 API |
|
||
| --- | --- |
|
||
| Core inspection 与 debug | `tp-debug-*`、`tp-intervals`、`tp-intervals-map`、`tp-plist`、`tp-text-snapshot`、`tp-empty-p` |
|
||
| Property policy 与 declaration | `tp-define-property-policy`、`tp-register-text-property`、`tp-text-declarations`、`tp-computed`、`tp-resolve-value`、`tp-merge-declarations`、`tp-define-style`、`tp-style-declarations` |
|
||
| 静态 recipe | `define-tp`/`tp-define-layer`、`define-tps`/`define-tp-group`/`tp-define-group`、layer/group 查询、undefine/reset/describe |
|
||
| Signal 与 binding | signal create/read/peek/set/dispose、binding install/read/dispose、`tp-variable-signal`、`tp-with-transaction`、`tp-transaction-participate-v2`、只读 `tp-transaction-active-p`、`tp-runtime-manifest`、counter/reset |
|
||
| Object 与 plan | plan/result constructor、`tp-object-ensure`、retain/reuse、fragment/content-range attach、resolve、mounted/mounts |
|
||
| Host range | `tp-range-anchor-create`、`tp-range-anchor-live-p`、`tp-object-attach-range`、`tp-range-rebase` |
|
||
| Surface | mount/update/scoped update、materialize、live/revision/client-state、at-point、report/report-summary/inspect、unmount |
|
||
| Direct façade | `tp-propertize`、`tp-apply`、`tp-watch`、`tp-set`、`tp-reset`、`tp-add`、`tp-remove`、`tp-clear`、`tp-get`、`tp-at`、`tp-member` |
|
||
| Search 与 navigation | `tp-match-*`、`tp-regexp-*`、`tp-search`、`tp-search-map`、`tp-forward*`、`tp-backward*` |
|
||
| Native query 与 mutation | `tp-lookup`、`tp-property-change`、`tp-property-any`、`tp-property-not-all`、`tp-with-mutation-policy` |
|
||
| Palette 与 display helper | palette definition/lookup、built-in recipe、`tp-palette-show`、`tp-pop-to-buffer`、`tp-switch-to-buffer`、`tp-display-buffer-mode` |
|
||
|
||
完整签名、返回值、示例和模块索引见 [API 参考](docs/API-REFERENCE.md)；
|
||
ownership、生命周期、错误和返回值合同见 [API semantics](docs/API-SEMANTICS.md)，
|
||
模块边界和完整事务流程见 [architecture](docs/ARCHITECTURE.md)。
|
||
|
||
## TP 1.0 迁移
|
||
|
||
TP 1.0 直接删除 0.3 的 managed stack/renderer runtime，不使用隐藏兼容分支。删除的行为包括 `tp-render.el`、`tp-stack.el`、stack mutation APIs、`tp-text`、`$variable` declarations、layer-to-buffer registry、scan-driven refresh、managed attach/detach/diagnostics，以及以 `tp-name`/`tp-layers`/`tp-meta` 作为权威 runtime storage 的机制。
|
||
|
||
## TP 2.0 transaction 迁移
|
||
|
||
TP 2.0 删除 v1 transaction participant facade 和 legacy execution route。把
|
||
`(tp-transaction-participate KEY PUBLISH ROLLBACK)` 精确替换为
|
||
`(tp-transaction-participate-v2 :key KEY :stage PUBLISH :rollback ROLLBACK)`。
|
||
检查 `tp-runtime-manifest` 的调用方必须要求 `tp-transaction-protocol-v2`；manifest
|
||
不再发布 route-selection 和 v1-adapter 字段。
|
||
|
||
可复用静态声明使用 direct recipe；已有文本的响应式属性使用 `tp-watch`；响应式文字或结构化 UI 使用 retained content surface。TP 不会自动扫描历史 propertized text 来重建 runtime identity。
|
||
|
||
## 示例
|
||
|
||
- [静态属性](examples/static-properties.el)
|
||
- [响应式状态](examples/reactive-status.el)
|
||
- [Retained dashboard](examples/retained-dashboard.el)
|
||
- [诊断装饰](examples/diagnostic-decoration.el)
|
||
|
||
这些示例只调用 TP public API，并在没有 Ebox 或 ECSS load-path 的环境中测试。
|
||
|
||
## 验证
|
||
|
||
```sh
|
||
make test
|
||
make test-shuffled SHUFFLE_SEED=20260806
|
||
make doctest
|
||
make compile-all WERROR=t
|
||
make checkdoc
|
||
make package-lint
|
||
make diff-check
|
||
```
|
||
|
||
结构测试还会证明：正常 signal/surface update 不扫描 `buffer-list`，不从显示文本搜索 identity；相等结果不会发布新 revision；unmount/kill cleanup 会释放 subscriptions 和 marker-backed runtime state。
|
||
|
||
## 许可证
|
||
|
||
GPL-3.0-or-later，详见 [LICENSE](LICENSE)。
|