[分享] block-ref 和 block-embed 的区别 及 在 emacs 中的实现

Block-ref 和 block-embed 是 roam research 中的关于块操作的两个概念。根据字面意思,block-ref 叫“块引用”,block-embed 叫“块嵌入”。这篇文本主要介绍如何在 emacs 中实现这两个功能。

如果你熟悉 roam research, 应该知道 block-ref 可以在其他块中插入一个块的引用,该块的引用会显示为“源块”的内容,因此 block-ref 本质是一个引用链接。而 block-embed 是在另一个块中直接插入“源块”的内容,因此 block-embed 本质上还是一段字符文本。

Block-ref 实现原理

在 emacs 中,为每一个 block 分配一个 uuid 属性 (overlay),并将块的 uuid, 块的内容以及其他属性存储在数据库中。=roam-block-ref-store= 命令存储该块的 uuid 引用,=roam-block-ref-insert= 命令插入该引用, 格式形如 “((89641396-6cff-4bd1-9d7d-08877ffb7177))”。根据引用中的 uuid 在数据库中查找该块对应的内容,然后将该引用的 display 属性设置为查询到的块的内容。

块引用是只读的,可以通过修改“源块”的内容,更新所有该块引用的显示。这个过程不难理解。修改源块的内容后,保存buffer时更新数据库。然后从数据库中获取修改后的内容,修改 display 属性值,实现 所有 block-ref 和 源块的内容同步。由于块引用同步的时机是保存buffer,因此建议设置 emacs 自动保存。

Block-embed 实现原理

每一个 block 除了存储了唯一的 uuid, 在数据库还存储了一个可以重复的 embed-id。我们将使用这个 embed-id 字段来实现 block-embed。

Embed-id 的值也用 uuid 表示,默认 uuid 等于 embed-id。使用 =roam-block-embed-store= 命令存储 embed block 的内容,=roam-block-embed-insert= 命令插入与源块相同的文本内容,同时将该块的 embed-id 设置为源块的 uuid。这样,每一个 embed block 都会有一个与源块的 uuid 值相等的 embed-id 字段。

前面提到,embed block 本质还是一块文本,因此可以修改。Block-embed 的强大之处就在于修改任意一个 embed block 或者 source block (源块),所有相关块的内容都会同步更新。

如何实现:根据当前修改的块的 uuid,在数据库中查找所有与该块的 embed-id 相同的块,获取到的这些块就是所有需要同步的。然后通过添加 =post-command-hook=, 实时更新所有块的内容。为什么这里需要实时更新,而不是像 block-ref 那样在保存时更新?因为每次保存会在数据库中更新所有块的内容,这意味着所有派生于同一个块的 embed block 的内容会被更新为最后一个缓存的 embed block,而这最后一个 embed block 很有可能不是当前修改的块,导致无法更新。实时更新可以保证所有 embed blocks 在保存时内容始终是同步的。

恢复 uuid 属性

可以预见,一个为所有块设置了 uuid 属性的文件在被 kill buffer 后,重新打开时,所有的 uuid 属性都会丢失,这会导致先前设置的所有 block-ref 和 block-embed 都将无法正常工作。因此我们需要在重新打开文件时恢复所有的 uuid 属性。使用 overlay 很容易实现。只需在每次保存时缓存所有 overlay 的范围及对应的 uuid,在打开文件时,根据缓存重新设置所有 uuid overlay 即可。

以上就是在 emacs 中实现 block-ref 和 block-embed 的主要原理。我将这些功能组织成了 emacs 插件: roam-block。详细的介绍及安装、用法请看 Github 文档。

效果演示

在使用之前先来看一看在 emacs 中的实现效果:

block-ref

block-embed

优化思路

Block-ref 需要保存 buffer 才能更新内容,可以实现像 block-embed 那样实时更新吗?可以。我已经有了大致的思路,借鉴 web 应用“前后端”的概念。每次修改 source block 内容后,先修改前端的显示,在保存时,再将后端和前端同步。

后记

从思路验证,到代码实现,花费了大约 1个月的时间。目前支持 org-mode, 后续会尝试支持 markdown。可以结合 emacs 中的 roam 插件使用,也可以单独使用。

分享整个 package 的实现思路的目的是:希望对其他 package 能够有所启发,后续我也会把这些功能集成到我的 gkroam 里。任何建议想法,欢迎留言!

最后放一下 github 仓库:

6赞