Emacs Completion Showcase with VOMPECCC

Emacs Completion Showcase with VOMPECCC (video)

VOMPECCC Emacs 补全工作流展示（视频）

1. About emacs completion workflows

1. 关于 Emacs 补全工作流

This is the fifth post in my series on Emacs completion. The first, Incremental Completing Read (ICR), explains what modern completion actually is, and how Emacs exposes it as a programmable substrate rather than a closed UI. The second introduced the VOMPECCC stack of eight packages covering the six orthogonal concerns of a complete completion system. The third toured spot, a Spotify client built as a thin shim on top of those packages. And the fourth built a produce picker from scratch, demonstrating the specific features that each VOMPECCC package provides.

这是我关于 Emacs 补全系列文章的第五篇。第一篇《增量补全读取 (ICR)》解释了现代补全的本质，以及 Emacs 如何将其作为一种可编程的底层架构而非封闭的 UI 来呈现。第二篇介绍了 VOMPECCC 技术栈，它包含八个包，涵盖了完整补全系统的六个正交关注点。第三篇介绍了 spot，一个构建在这些包之上的轻量级 Spotify 客户端。第四篇从零开始构建了一个农产品选择器，演示了每个 VOMPECCC 包提供的具体功能。

This post is the practical complement to all the other posts. Here, we showcase over a dozen workflows I use every day. Most are powered entirely by features that ship in the box with the VOMPECCC packages, and there are ‘Bonuses’ which demonstrate workflows enable by 3rd party packages that build on top of VOMPECCC. The prose is deliberately thin, and you will find most of the demonstration is in the video below.

本文是其他所有文章的实践补充。在这里，我将展示我每天使用的十几种工作流。其中大多数完全由 VOMPECCC 包自带的功能驱动，此外还有一些“额外内容”，展示了由构建在 VOMPECCC 之上的第三方包所实现的工作流。本文文字部分刻意从简，大部分演示内容请见下方的视频。

2. The Video demo

2. 视频演示

As in the previous posts in this series, the upper-right of my Emacs (in the tab-bar) shows the keybindings and command names I am invoking, so you can map what you see onto your own configuration.

与本系列之前的文章一样，我的 Emacs 右上角（在标签栏中）会显示我正在调用的快捷键和命令名称，以便你可以将所见内容映射到你自己的配置中。

3. A Note on My Configuration setup

3. 关于我的配置设置说明

Two configuration choices show up repeatedly and are worth naming once upfront so the keystrokes are intelligible.

有两个配置选项反复出现，值得提前说明，以便理解后续的按键操作。

Async split character. My consult-async-split-style is comma, not the default #. In Consult commands like consult-ripgrep, everything before the first , is sent to the external tool as the search pattern, and everything after is filtered locally with my completion style.

异步分割字符。 我的 consult-async-split-style 设置为逗号（,），而不是默认的 #。在像 consult-ripgrep 这样的 Consult 命令中，第一个逗号之前的所有内容都会作为搜索模式发送给外部工具，而逗号之后的所有内容则会使用我的补全样式在本地进行过滤。

Orderless dispatchers. My orderless-style-dispatchers bind affix characters to matching styles: @ for Marginalia-annotation matching, ~ for flex, ` for initialism, ! for negation. Each can be a prefix or suffix on a component. My orderless-component-separator is also ,, so a single comma serves double duty depending on context.

Orderless 调度器。 我的 orderless-style-dispatchers 将特定的前缀字符绑定到匹配样式：@ 用于 Marginalia 注解匹配，~ 用于模糊匹配，` 用于首字母缩写匹配，! 用于否定匹配。每个字符都可以作为组件的前缀或后缀。我的 orderless-component-separator 也设置为逗号，因此根据上下文，同一个逗号可以承担双重功能。

4. Multi-File Refactor

4. 多文件重构

consult-ripgrep → input your search term → embark-export → wgrep-change-to-wgrep-mode → edit as you like → C-<return>

consult-ripgrep → 输入搜索词 → embark-export → wgrep-change-to-wgrep-mode → 按需编辑 → C-<return>

5. Async + Local Two-Stage Search

5. 异步 + 本地两阶段搜索

consult-ripgrep with , splitting external (ripgrep) from local (Orderless): for example, error,handler,~retry,!test.

使用逗号分割外部（ripgrep）和本地（Orderless）的 consult-ripgrep：例如 error,handler,~retry,!test。

6. Unified Buffer / File / Bookmark Switcher

6. 统一的缓冲区 / 文件 / 书签切换器

consult-buffer with narrowing keys: b SPC for buffers, f SPC for recent files, m SPC for bookmarks, p SPC for project items.

使用缩小范围键的 consult-buffer：b SPC 用于缓冲区，f SPC 用于最近文件，m SPC 用于书签，p SPC 用于项目条目。

7. Buffer and Project-Wide Line Search

7. 缓冲区及项目范围内的行搜索

consult-line within the current buffer; consult-line-multi across all buffers (or the project, with a prefix argument).

当前缓冲区内的 consult-line；跨所有缓冲区（或通过前缀参数在整个项目内）的 consult-line-multi。

8. 代码符号导航

consult-imenu within the current buffer; consult-imenu-multi across every buffer of the same major mode.

当前缓冲区内的 consult-imenu；跨所有相同主模式缓冲区的 consult-imenu-multi。

9. Documentation Search

9. 文档搜索

consult-info for Info manuals (Emacs, Elisp, Org, plus every package that ships its own .info file); consult-man for system man pages.

用于 Info 手册的 consult-info（包括 Emacs、Elisp、Org 以及每个自带 .info 文件的包）；用于系统 man 手册页的 consult-man。

10. Find Commands by Docstring

10. 通过文档字符串查找命令

M-x window @frame. The @ dispatcher routes a component through orderless-annotation to match against Marginalia’s docstring text rather than the candidate name. This lets you query for commands by what they do rather than what they are called.

M-x 窗口 @frame。@ 调度器通过 orderless-annotation 路由组件，以匹配 Marginalia 的文档字符串文本，而不是候选名称。这让你能够通过命令的功能而非名称来查询命令。

11. Mass Action Across Candidates

11. 候选列表批量操作

C-> (embark-act-all) runs a single Embark action on every candidate currently surviving in the prompt. You can also embark-select to create a subset of displayed candidates and use embark-act-all to act on only those selected candidates.

C-> (embark-act-all) 对当前提示符中存留的所有候选对象执行单个 Embark 操作。你也可以使用 embark-select 创建显示候选对象的子集，并使用 embark-act-all 仅对这些选定的候选对象进行操作。

12. Pivot Mid-Prompt

12. 提示符中途切换

embark-become switches the active command (e.g. find-file → switch-to-buffer) without losing the input I have already typed.

embark-become 可以在不丢失已输入内容的情况下切换当前活动的命令（例如从 find-file 切换到 switch-to-buffer）。

13. Symbol-Aware Multi-File Refactor

13. 符号感知的多文件重构

xref-find-references (M-?, with xref-show-xrefs-function set to consult-xref) → embark-export → wgrep-change-to-wgrep-mode → edit → C-<return> to write your changes. This is very similar to the ripgrep version above but driven by the language server, so foo the variable and foo the unrelated comment stay separate.

xref-find-references (M-?，需将 xref-show-xrefs-function 设置为 consult-xref) → embark-export → wgrep-change-to-wgrep-mode → 编辑 → C-<return> 保存更改。这与上面的 ripgrep 版本非常相似，但由语言服务器驱动，因此变量 foo 和无关注释中的 foo 会被区分开来。

14. Recent Files as a Filesystem

14. 将最近文件视为文件系统

consult-recent-file → embark-export produces a Dired buffer, putting every Dired operation (mark, copy, rename, chmod, batch shell command) on the recent-files set.

consult-recent-file → embark-export 生成一个 Dired 缓冲区，将所有 Dired 操作（标记、复制、重命名、修改权限、批量 shell 命令）应用于最近文件集合。

15. Avy-Style Jump Then Act

15. Avy 风格跳转并执行

In any Vertico session, C-' jumps to a labeled candidate (Avy-style); C-" does the same jump and hands the candidate to Embark.

在任何 Vertico 会话中，C-' 跳转到带标签的候选对象（Avy 风格）；C-" 执行相同的跳转并将候选对象传递给 Embark。

16. Resume the Last Session

16. 恢复上一次会话

s-V (vertico-repeat) reopens the last completion session with its prompt, input, and selected candidate intact.

s-V (vertico-repeat) 重新打开上一次的补全会话，并保留其提示符、输入内容和选定的候选对象。

Emacs Completion Showcase with VOMPECCC