cider 中文文档

CIDER 最初的灵感来源于强大的 Common Lisp 交互式开发环境 SLIME. 最初我们开始将 SLIME 的核心功能应用于 Clojure, 但随着时间的推移, CIDER 在许多方面变得与 SLIME 大相径庭.

想了解更多关于 CIDER 早期历史的信息, 请查看此演示文稿.

程序员被期望以一种非常动态和增量的方式进行编程, 不断地重新求值现有的 Clojure 定义, 并向他们正在运行的应用程序中添加新的定义.

在使用 CIDER 时, 永远不会停止/启动一个 Clojure 应用程序 —— 会不断地与它互动并改变它, 这种方法被称为“交互式编程/开发”或“REPL 驱动编程”.

我们更喜欢前一个术语, 并将在 CIDER 的整个文档中使用它.

可以在“交互式编程”部分找到有关典型 CIDER 工作流程的更多详细信息.

CIDER 构建于 nREPL (Clojure 的网络化 REPL 服务器) 之上.

CIDER 的基本架构如下所示:

Clojure 代码由 nREPL 服务器执行. CIDER 向服务器发送请求并处理其响应. 服务器的功能由额外的 nREPL middleware 增强, 这些 middleware 专为满足像 CIDER 这样的交互式开发环境的需求而设计.

需要安装 Emacs, 最好是其最新的稳定版. Emacs 新手就先过一遍 Emacs 导览 和内置教程 (只需按 C-h t).

CIDER 官方支持 Emacs 27.1+, Java 8+, 和 Clojure(Script) 1.10+. 如果需要使用早期版本, 请查看兼容性矩阵.

还需要最新版本的构建工具 (Clojure CLI, Leiningen, 或 Gradle) 才能通过 cider-jack-in 启动 CIDER. 建议使用最新的稳定版本.

CIDER 在所有主要的 package.el 社区维护的仓库中都可用 - NonGNU ELPA, MELPA Stable 和 MELPA.

NonGNU ELPA 是 Emacs 的标准仓库之一, 在 Emacs 28+ 上默认启用. 如果想使用 MELPA 和 MELPA Stable, 需要自己设置.

可以使用以下命令安装 CIDER:

M-x package-install <RET> cider <RET>

或者通过将这段 Emacs Lisp 代码添加到 Emacs 初始化文件 (.emacs 或 init.el) 中:

(unless (package-installed-p 'cider)
  (package-install 'cider))

如果安装失败, 尝试刷新包列表:

M-x package-refresh-contents <RET>

需要注意的是, MELPA 包是从 master 分支自动构建的, 这意味着处于开发的最前沿. 这有利有弊; 能尝鲜新功能, 也可能不时遇到一些 bug. 尽管如此, 从 MELPA 安装是获取 CIDER 的一种合理方式.

master 分支通常非常稳定, 其中的严重回归问题通常会很快得到修复.

如果不想 (或不能) 等待 MELPA 重建 CIDER, 可以在本地自己构建和安装最新的 MELPA 包. 请查看这篇文章以获取有关该主题的详细信息.

如果对处于 CIDER 开发的最前沿感到担忧, 可以随时将 CIDER 固定到使用 NonGNU ELPA 或 MELPA Stable, 如下所示:

;; 固定到 NonGNU ELPA
(add-to-list 'package-pinned-packages '(cider . "nongnu") t)

;; 固定到 MELPA Stable
(add-to-list 'package-pinned-packages '(cider . "melpa-stable") t)

CIDER 有一些依赖项 (例如 queue & seq) 仅在 GNU ELPA 仓库中可用. 这是 Emacs 中唯一默认启用的包仓库, 不应该禁用它!

use-package 可以用于通过 package.el 的仓库 NonGNU ELPA, MELPA Stable 和 MELPA 来安装 CIDER.

如果想安装 master 分支中的 CIDER 版本, 在 Emacs 初始化文件 (.emacs 或 init.el) 中声明以下内容:

(use-package cider
  :ensure t)

然而, 如果想更保守一些, 只使用 CIDER 的稳定版本, 可以这样声明:

(use-package cider
  :ensure t
  :pin melpa-stable)

放置上述 s-expression 之一后, 通过输入 C-x C-e 来求值它, 使其生效.

有关 use-package 的更多配置选项, 请查阅官方的 use-package 仓库.

不鼓励手动安装 CIDER. 手动安装相对复杂,因为它需要手动安装依赖项. 请查看 Hacking on CIDER 部分了解更多详情.

对Clojure 项目, 使用 CIDER 为其启动一个 nREPL 会话, 只需访问该项目的一个文件, 然后输入 M-x cider-jack-in RET. CIDER 将启动一个 nREPL 服务器并自动连接到它.

在 Clojure(Script) 缓冲区中, cider-jack-in 命令绑定到 C-c C-x (C-)j (C-)j.

jacking-in 的过程非常简单:

• CIDER 确定项目的构建系统 (例如 Leiningen) 并选择必要的命令来启动 nREPL 服务器.
• CIDER 调用 shell 并运行像 lein repl :headless 这样的命令来启动 nREPL 服务器.
• CIDER 等待 nREPL 服务器启动. CIDER 通过解析命令的输出来确定这一点, 等待出现类似 nREPL server started on port 53005 on host localhost - nrepl://localhost:53005 的行.
• CIDER 从前面的消息中提取 nREPL 的端口.
• 它连接到正在运行的 nREPL 服务器.

在等待 nREPL 启动时, 可以在 minibuffer 中看到 cider-jack-in 调用的确切命令. 也可以在 Emacs 的 *Messages* 缓冲区中找到这个命令.

在某些情况下, 一个项目可能包含多个项目标记, 例如 project.clj 和 deps.edn. 发生这种情况时, CIDER 会提示选择要使用的构建工具.

可以通过设置变量 cider-preferred-build-tool 来覆盖此行为. 虽然可以在 Emacs 配置中全局设置它, 但大多数情况下, 在 .dir-locals.el 中为其设置一个项目特定的配置更佳:

((clojure-mode
  (cider-preferred-build-tool . lein)))

cider-jack-in 主要为本地开发设计 (文件在本地机器上, nREPL 进程也在同一台机器上运行). 它确实支持各种常见的远程/容器场景, 如本节后面所述.

由于远程场景的多样性, 它无法支持所有情况, 因此在某些情况下, 更好的选择是手动启动 nREPL 并使用 cider-connect 连接到它.

虽然 CIDER 的核心功能只需要一个 nREPL 服务器, 但许多高级功能依赖于额外的 nREPL middleware 的存在. 而使用 cider-jack-in, 这一切都是自动处理的.

如果项目使用 lein 或 tools.deps (deps.edn), CIDER 在启动服务器时会自动注入所有必要的 nREPL 依赖 (例如 cider-nrepl 或 piggieback).

注入过程非常简单 - CIDER 在运行启动 nREPL 服务器的命令时, 将额外的依赖和 nREPL 配置传递给构建工具. 对于 tools.deps, 它看起来像这样:

$ clojure -Sdeps '{:deps {nrepl {:mvn/version "1.5.1"} cider/cider-nrepl {:mvn/version "0.58.0"}}}' -m nrepl.cmdline --middleware '["cider.nrepl/cider-middleware"]'

如果不希望 cider-jack-in 自动注入依赖, 请将 cider-inject-dependencies-at-jack-in 设置为 nil. 请注意, 就自己设置依赖 (参见 nREPL Middleware Setup).

通常, cider-jack-in 只会注入 cider-nrepl, 而 cider-jack-in-cljs 还会添加 piggieback. 注入机制是可配置的, 可以轻松地在那里添加更多库. 一些 CIDER 扩展会使用此机制自动注入它们自己的依赖.

以下是如何为 cider-jack-in-clj 修改注入的依赖:

;; 自动注入 1.0 版本的库 foo/bar
(cider-add-to-alist 'cider-jack-in-dependencies
                    "foo/bar" "1.0")
;; 如果想完全控制坐标描述, 将其设置为 alist
;; 为库 org.clojure/tools.deps 自动注入 {:git/sha "6ae2b6f71773de7549d7f22759e8b09fec27f0d9"
;;              :git/url "https://github.com/clojure/tools.deps/"}
(cider-add-to-alist 'cider-jack-in-dependencies
                    "org.clojure/tools.deps"
                    '(("git/sha" . "6ae2b6f71773de7549d7f22759e8b09fec27f0d9")
                      ("git/url" . "https://github.com/clojure/tools.deps/")))

在这些依赖中始终使用完整的 group/artifact (例如 re-frame/re-frame), 因为只有 Leiningen 支持裸 re-frame 语法.

CIDER 还会注入它支持的最新版本的 nREPL. 这是一个简单的技巧, 用于覆盖构建工具 (例如 Leiningen) 捆绑的 nREPL 版本, 以使用最新的 nREPL 功能.

可以通过自定义 cider-injected-middleware-version 和 cider-injected-nrepl-version 来覆盖注入的 cider-nrepl 和 nREPL 版本.

通常应该避免这样做, 但如果想尝试新版本或遇到一些回归问题必须退回旧版本, 这可能会很有用.

CIDER 还可以将 Clojure 依赖注入到项目中, 这在项目默认使用比 CIDER middleware 支持的更旧版本的 Clojure 时非常有用. 适当地设置 cider-jack-in-auto-inject-clojure 来启用此功能.

从 1.2.0 版本开始, nREPL 包含一个原生的 JVMTI agent, 它使得 eval 中断在 Java 21 及更高版本上能够正常工作. 要启用该 agent, Java 进程应以 -Djdk.attach.allowAttachSelf 启动.

如果 cider-enable-nrepl-jvmti-agent 变量设置为 t, CIDER 将在 jack-in 期间自动执行此操作.

cider-enable-nrepl-jvmti-agent 在 Emacs 外部启动 REPL 进程并使用 cider-connect 连接时无效. 在那种情况下, 必须通过构建工具的方式手动添加 -Djdk.attach.allowAttachSelf Java 属性.

在 Leiningen 中, 将此添加到 project.clj:

:jvm-opts ["-Djdk.attach.allowAttachSelf"]

在 tools.deps 中, 将此添加到 REPL 启用的某个别名中:

:aliases {:dev
          {:jvm-opts ["-Djdk.attach.allowAttachSelf"]
           ...}}

如果尝试在项目目录之外运行 cider-jack-in, CIDER 会警告并要求确认是否真的要这样做; 多数情况下, 这是一个意外.

如果决定继续, CIDER 将调用在 cider-jack-in-default 中配置的命令 (默认为 clj, Clojure 的基本启动命令).

禁用在项目外 jacking-in 时显示的警告, 可以将 cider-allow-jack-in-without-project 设置为 t.

cider-jack-in-universal C-c C-x j u 是另一种在没有项目的情况下快速 jack-in 的方法, 从预配置的 Clojure 构建工具列表中选择.

当此命令在项目外部调用时, 用户可以选择使用其中一个预配置的工具进行 jack-in, 并确认用作基础的根目录. 如果该命令在项目目录内调用, 其行为与 c cider-jack-in 完全相同.

它利用 Emacs 的数字前缀参数来快速使用特定的构建工具进行 jack-in. 数字前缀参数可以通过 Meta 键后跟一个数字来设置.

目前支持以下 Clojure 构建工具:

• M-1 C-c C-x j u 使用 clojure-cli 进行 jack-in.
• M-2 C-c C-x j u 使用 leiningen 进行 jack-in.
• M-3 C-c C-x j u 使用 babashka 进行 jack-in.
• M-4 C-c C-x j u 使用 nbb 进行 jack-in.
• M-5 C-c C-x j u 使用 basilisp 进行 jack-in.

这是一个如何绑定 F12 以快速启动 babashka REPL 的示例:

(global-set-key (kbd "<f12>") (lambda ()
                                (interactive)
                                (cider-jack-in-universal 3)))

可供考虑的构建工具列表配置在 cider-jack-in-universal-options 中. 列表中的每个元素都包含工具名称及其设置选项. 以列表中的 nbb 为例:

(nbb         (:prefix-arg 4 :cmd (:jack-in-type cljs :project-type nbb :cljs-repl-type nbb :edit-project-dir t)))

其中:

1. :prefix-arg 将 nbb 工具名称分配给数字参数前缀 4.
2. :cmd 如何调用该命令.
   1. :jack-in-type 使用 cljs repl.
   2. :project-type 使用 nbb (参见 jack-in-command) 来启动 nREPL 服务器.
   3. :cljs-repl-type 客户端使用 nbb cljs repl 类型 (参见 cider-cljs-repl-types) 来初始化服务器.
   4. :edit-project-dir 要求用户确认用作基础的根目录.

可以使用 C-u M-x cider-jack-in RET 来指定 cider-jack-in 将运行的确切命令. 想指定额外的 Leiningen profiles 或 deps.edn aliases, 这个选项非常有用.

或者使用 C-u C-u M-x cider-jack-in RET, 这是前一个命令的变体. 这个命令会首先提示在哪个项目中启动 cider-jack-in, 在其他目录中, 这非常方便.

如果项目包含 project.clj 和 deps.edn 的某种组合, 想为其中一个启动 REPL, 这个选项也很有用.

这些示例仅使用 cider-jack-in, 但此行为对于所有 cider-jack-in-* 命令都是一致的.

可以通过修改一些选项来进一步自定义 CIDER 用于 cider-jack-in 的命令行. 这些选项在不同的工具之间略有不同, 所以我们将逐个工具地检查它们.

使用哪个 Jack-In 命令是基于项目类型的. 可以在项目范围内或作为 Lisp 中的参数来覆盖 Jack-In 命令. 这允许对 CIDER 如何启动 nrepl-server 进行细粒度控制.

确定 Jack-In 命令的优先顺序是: 1. 如果作为参数提供了 :jack-in-cmd, 2. 如果 cider-jack-in-command 设置为目录本地变量, 以及 3. 从项目类型推断 (默认).

在某些情况下, 只启动一个 nREPL 服务器进程而不连接它可能会很有用. 这可以支持复杂的设置, CIDER 无法可靠地检测到要连接到哪个服务器/端口, 因此会失败. 这假设用户之后会手动执行 cider-connect 命令, 指定主机/端口.

对于这种情况, 提供了 cider-start-nrepl-server (C-c C-x (C-)j (C-)n) 命令, 它接受与 cider-jack-in 相同的参数.

一个已经运行的 nREPL 服务器, CIDER 可以连接到它. 一个基于 Leiningen 的项目, 在终端会话中进入项目目录并输入:

$ lein repl :headless

这将启动项目的 nREPL 服务器.

对于普通的 clj 也是可能的, 尽管命令有点长:

$ clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.58.0"}}}' -m nrepl.cmdline --middleware "[cider.nrepl/cider-middleware]"

或者, 可以手动启动 nREPL 或使用项目构建工具 (Gradle, Maven 等) 提供的设施.

在 nREPL 服务器运行后, 返回 Emacs 并连接到它: M-x cider-connect RET. CIDER 会提示输入主机和端口信息, 这些信息应该在前面的命令启动项目中的 nREPL 服务器时打印出来了.

在 Clojure(Script) 缓冲区中, cider-connect 命令绑定到 C-c C-x c s.

如果经常连接到相同的主机和端口, 可以告诉 CIDER 关于它们的信息, 当调用 cider-connect 时, 它将使用这些信息为主机和端口提示进行补全读取. 可以用一个可选的标签来识别每个主机.

(setq cider-known-endpoints
  '(("host-a" "10.10.10.1" "7888")
    ("host-b" "7888")))

全绕过提示, 可以在每个项目的基础上使用 .dir-locals.el 配置变量 cider-connect-default-params 和 cider-connect-default-cljs-params.

以下配置允许输入 M-x cider-connect-clj&cljs RET 并立即连接到 JVM 和 shadow-cljs REPLs, 无需回答任何提示 - 这在项目总是为其 nREPL 服务器使用相同的固定端点时很有用.

((clojure-mode
  . ((cider-connect-default-params . (:host "localhost" :port 1234))
     (cider-connect-default-cljs-params . (:host "localhost" :port 5678))
     (cider-default-cljs-repl . shadow))))

通用参数 C-u 可以在命令前使用, 以覆盖这些设置并强制显示提示.

虽然大多数时候连接到本地运行的 nREPL 服务器, 无论是手动启动还是通过 cider-jack-in-* 启动, 也有连接到远程 nREPL 主机的选项.

为了安全起见, CIDER 在这种情况下能够通过 SSH 隧道建立连接. 此行为由 nrepl-use-ssh-fallback-for-remote-hosts 控制: 当为 true 时, CIDER 在无法直接连接时会尝试通过 ssh 连接到远程主机. 默认为 nil.

还有一个 nrepl-force-ssh-for-remote-hosts, 它将无条件地强制对远程连接使用 ssh.

由于 nREPL 连接默认是不安全的, 建议在连接到网络外部的服务器时仅使用 SSH 隧道.

还有另一种情况, CIDER 可以选择性地利用 ssh 命令 - 当执行 cider-connect-* 时试图找出潜在的目标主机和端口.

如果 cider-infer-remote-nrepl-ports 为 true, CIDER 将使用 ssh 尝试推断远程主机上的 nREPL 端口 (用于直接连接). 该选项默认也设置为 nil.

启用这些选项中的任何一个都会导致 CIDER 对某些 SSH 操作使用 TRAMP, TRAMP 会解析 ~/.ssh/config 和 ~/.ssh/known_hosts 等配置文件. 这已知会与复杂或非标准的 ssh 配置产生问题.

可以在通过 TRAMP 处理远程文件时运行 cider-jack-in-*. CIDER 将重用现有的 SSH 连接参数 (如端口和用户名) 来建立 SSH 隧道. 如果尝试 cider-connect-* 到与当前连接的主机匹配的主机, 也会发生同样的情况.

对于 Docker 容器, 通过 TRAMP 运行 cider-jack-in-* 可能在技术上可行, 但可能会产生混合结果. 请查看下一节以了解推荐的方法.

我们所说的“容器”是指 Docker 容器或类似技术, 用于运行将承载我们 nREPL 服务器的 JVM. 我们编辑的文件可能/可能不使用 TRAMP 进行编辑. 它们也可以挂载在容器内部, 从而显示为本地文件.

因为 CIDER 并不总能检测到它是否在处理远程文件, 所以建议不要依赖上面描述的 cider-jack-in 及其远程支持, 而是从容器内部通过命令行启动 nREPL 服务器, 然后 cider-connect 到它.

这需要首先在运行的容器内获得一个 shell, 然后手动启动 nREPL 服务器, 或者配置容器在启动时自动启动 nREPL.

为了将 Emacs 连接到 nREPL, 我们需要确保 nREPL 的端口对我们的本地 Emacs 是可达的, 这样我们才能 cider-connect 到它. 根据具体情况, 有几种解决方案.

Unix 套接字支持是在 nREPL 0.9 中引入的. 目前 CIDER 对 Unix 套接字的支持被认为是实验性的, 其接口可能会在未来的 CIDER 版本中改变.

在本地运行 nREPL 服务器时, 可以选择在套接字文件上监听, 而不是打开网络端口. 只要对套接字父目录的访问得到充分保护, 这比网络端口安全得多, 因为任何本地用户都可以访问端口提供的 REPL.

在其他情况下, 例如在使用虚拟网络 (容器) 时, 共享文件套接字可能比管理桥接网络和防火墙设置要简单得多.

在文件套接字上启动 nREPL 服务器后, 例如使用 clj 命令 (有关其他示例, 请参见 https://nrepl.org/nrepl/usage/server.html),

$ clj -R:nREPL -m nrepl.cmdline --socket nrepl.sock

可以通过使用 local-unix-domain-socket 特殊主机名与 cider-connect 来连接 CIDER: M-x cider-connect RET local-unix-domain-socket RET nrepl.sock RET.

目前只有 Leiningen, cider-jack-in 等命令会检测并使用通过 :socket 参数请求的 unix domain socket. 这可以通过为 cider-jack-in 指定前缀参数 (例如 C-u M-x cider-jack-in) 或调整 cider-lein-parameters 来安排.

那么, 现在 CIDER 已经准备就绪, 接下来该做什么呢? 这里有一些想法:

• 熟悉交互式编程和 cider-mode
• 根据喜好配置 CIDER
• 探索更高效的其他包

是的, 这是对 "Neuromancer" 的引用.

nREPL 本身不支持 ClojureScript 求值, 需要一个额外的 middleware. 对于大多数 REPL (除了 shadow-cljs 和 nbb 这两个显著的例外), CIDER 依赖 Piggieback middleware 来提供其 ClojureScript 支持.

Piggieback 的工作方式如下:

• 启动一个常规的 Clojure REPL
• 在其中运行一些 Clojure 代码, 将其转换为 ClojureScript REPL

这意味着对于 ClojureScript, jacking-in 是一个双重过程, 与 Clojure 相比, 因为现在我们有了额外的 REPL"升级"步骤.

好的一面是可以在单个 nREPL 连接中并存 Clojure 和 ClojureScript REPL! 这开启了各种有趣的可能, 我们稍后会讨论.

shadow-cljs 的 REPL 以非常相似的方式实现, 但其机制由其自己的 nREPL middleware 提供 - 而不是 Piggieback.

虽然由 Piggieback 驱动的 ClojureScript REPL 的行为或多或少与标准 ClojureScript REPL 相同, 但有一些微妙的差异是每个人都需要注意的.

当你执行 cider-jack-in-cljs 时, CIDER 不会自动处理 ClojureScript REPL 的依赖关系. 你需要按照本手册后续章节的说明手动配置这些依赖.

实际上, CIDER 会自动处理最重要的依赖 - 即 Piggieback. 然而, 其他依赖的问题在于, 你可能需要安装一些外部工具 (例如, node, shadow-cljs), 并且像 Figwheel 和 shadow-cljs 这样的 ClojureScript 开发工具也需要一些设置才能使用.

在尝试将 Clojure REPL 升级为 ClojureScript REPL 之前, CIDER 会通过运行检查来帮助你识别缺失的需求. 这种检查的性质因不同的 REPL 类型而异:

• 对于 node REPL, 我们检查 node 二进制文件是否在你的 exec-path (Emacs 版本的 PATH) 中
• 对于像 figwheel 这样的工具, 我们检查它们是否在 classpath 上可用 (通过尝试 require 它们的一些命名空间)

我们将在接下来的章节中进一步讨论这些检查.

CIDER 目前不支持自托管的 ClojureScript 实现. 原因在于目前还没有可用的自托管版本的 nREPL (用 ClojureScript 实现).

另一个不支持的 REPL 是 Rhino. 在 Piggieback 中支持它需要很多丑陋的 hack, 最终决定我们最好不要使用 Rhino. 鉴于今天有大量更好的解决方案, 我怀疑没有人会怀念 Rhino.

此外, 正如本页前面提到的 - CIDER 的许多高级功能目前不适用于 ClojureScript.

在下一节中, 我们将向你展示如何使用 CIDER 启动 ClojureScript REPL.

ClojureScript 支持依赖于 piggieback nREPL middleware 存在于你的 REPL 会话中. 不过, 有一个例外: shadow-cljs. 它有自己的 nREPL middleware, 完全不依赖 piggieback.

如果 cider-inject-dependencies-at-jack-in 被启用 (默认是这样), 那么在执行 cider-jack-in-cljs 时, piggieback 将被自动添加并为你的项目配置好.

如果 cider-inject-dependencies-at-jack-in 被禁用, 或者你打算使用 cider-connect-cljs 连接到一个已经运行的 nREPL 服务器, 请使用下一节中的配置.

要设置 piggieback, 请将以下依赖项添加到你的项目 (project.clj 或 deps.edn) 中:

;; 这里使用最新的版本
[cider/piggieback "0.6.1"]
[org.clojure/clojure "1.12.0"]

以及 piggieback nREPL middleware:

在 project.clj 中:

:repl-options {:nrepl-middleware [cider.piggieback/wrap-cljs-repl]}

或者在 deps.edn 中:

{:aliases { :cider-cljs { :main-opts
  ["-m" "nrepl.cmdline" "--middleware"
   "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}}}

或者在 build.gradle 中:

dependencies {
  devImplementation 'nrepl:nrepl:1.5.1'
  devImplementation 'cider:cider-nrepl:0.58.0'
  devImplementation 'cider:cider-piggieback:0.6.1'
}

tasks.named('clojureRepl') {
  middleware = ['cider.nrepl/cider-middleware', 'cider.piggieback/wrap-cljs-repl']
}

在你的项目中打开一个 ClojureScript 文件, 然后输入 M-x cider-jack-in-cljs RET. 在正确的配置下并回答几个提示后, 这将启动 nREPL 服务器并创建一个 ClojureScript REPL 缓冲区.

在 CIDER 0.18 之前, cider-jack-in-cljs 会同时创建一个 Clojure 和一个 ClojureScript REPL. 在 CIDER 0.18+ 中, 如果你想同时创建两个 REPL, 你需要使用 cider-jack-in-clj&cljs.

当你同时拥有 Clojure 和 ClojureScript REPL 时, CIDER 会根据你当前访问的是 .clj 还是 .cljs 文件, 自动将所有常规 CIDER 命令定向到相应的 REPL.

cider-jack-in-cljs 会提示你想要启动的 ClojureScript REPL 类型. 请记住, 某些 REPL 需要你配置额外的设置. 例如, 你需要安装 Node.js 才能启动 Node REPL.

唯一不需要任何额外设置的 ClojureScript REPL 类型是浏览器 REPL. 要使用 Node.js REPL, 你需要安装 Node.js.

CIDER 会自动尝试检查启动某个 ClojureScript REPL 所需的依赖项 (例如 Clojure 库和/或额外的工具如 Node.js) 是否存在. 如果你遇到错误的依赖项检查, 你可以像这样禁用它们:

(setq cider-check-cljs-repl-requirements nil)

通常情况下, CIDER 会将来自 clj 文件的代码分派到 Clojure REPL, 将来自 cljs 文件的代码分派到 ClojureScript REPL. 但是 cljc 文件有两个可能的连接目标, 两者都是有效的. 因此, 默认情况下, 如果存在匹配的 clj 和 cljs 连接缓冲区, CIDER 会尝试在所有这些缓冲区中求值 cljc 文件.

因此, 如果你在一个 cljc 文件中求值代码 (+ 2 2), 并且你同时有一个活动的 Clojure 和 ClojureScript REPL, 那么这段代码将被求值两次, 每个 REPL 一次. 实际上, 你可以在一个 CIDER 会话中创建多个 clj 和 cljs 兄弟连接 (C-c C-x C-s C-s/j), 求值将被同时定向到所有的 REPL. 更多细节请参见管理连接.

如果你希望只在匹配的 REPL 中的一个里面求值 cljc 文件, 你可以自定义变量 cider-clojurec-eval-destination 为 clj 或 cljs. 例如, 要只在 ClojureScript REPL 中求值 cljc 文件, 请将以下内容添加到你的 Emacs 配置中:

(setq cider-clojurec-eval-destination 'cljs)

注意: 这个变量也可以通过 setq-local 在每个缓冲区的基础上设置, 或者在 dir-locals.el 中项目范围内设置.

开箱即用, CIDER 会向 ClojureScript REPL 注入一个依赖——即 piggieback. 如果你想注入更多的依赖, 你需要修改 cider-jack-in-cljs-dependencies 变量. 这里有一个例子:

;; 让我们在 jack-in 时添加 Weasel
(cider-add-to-alist 'cider-jack-in-cljs-dependencies "weasel/weasel" "0.7.1")

在这些依赖项中始终使用完整的 group/artifact (例如 re-frame/re-frame), 因为只有 Leiningen 支持裸 re-frame 语法.

通常情况下, 不需要修改这个变量, 因为 ClojureScript 依赖项大多数时候都在你的项目配置中明确声明了.

修改此变量将影响所有 ClojureScript REPL 类型.

如果你经常使用相同的 ClojureScript REPL, 你可以设置 cider-default-cljs-repl, CIDER 将跳过提示并使用这个设置. 例如, 以下代码将使 Node.js 成为默认设置:

(setq cider-default-cljs-repl 'node)

所有支持的 ClojureScript REPL都存储在 cider-cljs-repl-types 中. 如果你需要扩展它, 你应该在你的 Emacs 配置中使用 cider-register-cljs-repl-type.

(cider-register-cljs-repl-type 'super-cljs "(do (...))" optional-requirements-function)

如果你正在注册一个自托管 (原生) 的 ClojureScript REPL (例如, scittle), "升级" 表单应为 nil.

你也可以使用 .dir-locals.el 在每个项目的基础上修改已知的 ClojureScript REPL:

;; 替换 REPL 类型列表并设置一些默认值
((nil
  (cider-default-cljs-repl . super-cljs)
  (cider-cljs-repl-types . ((super-cljs "(do (foo) (bar))")))))
;; 修改已知 REPL 列表并设置一些默认值
((nil
  (eval . (cider-register-cljs-repl-type 'super-cljs "(do (foo) (bar))"))
  (cider-default-cljs-repl . super-cljs)))

对于一次性的 REPL, 你也可以像这样使用自定义的 REPL 初始化表单:

;; 修改已知 REPL 列表并设置一些默认值
((nil
  (cider-custom-cljs-repl-init-form . "(do (foo) (bar))"
  (cider-default-cljs-repl . custom)))

如果你已经有一个正在运行的 Clojure REPL 并想添加一个 ClojureScript REPL, 你可以调用 cider-jack-in-sibling-clojurescript 来添加它.

默认情况下, CIDER 会使用合适的库来丰富 ClojureScript 的补全结果. 如果你遇到任何与 suitable 相关的问题, 你可以像这样禁用增强补全:

(setq cider-enhanced-cljs-completion-p nil)

接下来的设置说明重点在于让你能用 CIDER 运行 Figwheel 所需的最低限度操作. 更多细节, 你应该查阅 Figwheel 出色的文档.

这已被弃用, 以支持使用 figwheel-main. 请查看下一节中的说明.

你也可以将 Figwheel 与 CIDER 一起使用.

1. 正常设置 Figwheel, 但要确保 :cljsbuild 和 :figwheel 设置位于你的 Leiningen 项目定义的根部.
2. 将这些添加到你的 dev :dependencies 中:

[cider/piggieback "0.6.1"] ; 对于 cider-jack-in-cljs 不是必需的
[figwheel-sidecar "0.5.19"] ; 这里使用 figwheel 的当前版本

请记住, CIDER 不支持早于 0.4 版本的 Piggieback. 请确保你使用的是兼容版本的 Figwheel.

1. 将此添加到你的 dev :repl-options (对于 cider-jack-in-cljs 不是必需的):

:nrepl-middleware [cider.piggieback/wrap-cljs-repl]

1. 使用 cider-jack-in-cljs (C-c C-x (C-)j (C-)s) 启动 REPL. 当提示 ClojureScript REPL 类型时, 选择 figwheel.
2. 打开浏览器到 Figwheel URL, 以便它可以连接到你的应用程序.

你也应该查看 Figwheel 的 wiki.

官方 Figwheel 文档

• 安装
• 将 Figwheel 与 CIDER 一起使用.

教程

• tools.deps, figwheel-main, Devcards, 和 Emacs
• 将 Figwheel 与 CIDER 一起使用

本节假设已经安装了 node.js.

安装 shadow-cljs 非常直接. 可以通过 npm 或 yarn 来安装:

$ npm install -g shadow-cljs
$ yarn global add shadow-cljs

虽然不是必须进行全局安装, 但这通常是推荐的方法.

你可以通过以下配置变量调整 cider-jack-in-cljs 用于启动 shadow-cljs 服务器的命令:

• cider-shadow-cljs-command (其默认值为 npx shadow-cljs)
• cider-shadow-cljs-parameters (其默认值为 server)

所有这些导致了以下默认命令来启动 shadow-cljs 服务器:

$ npx shadow-cljs server

当你执行 cider-jack-in-cljs 时, 该命令在 minibuffer 中可见.

如前所述, 你也可以通过 cider-shadow-default-options 设置一个默认的 build:

(setq cider-shadow-default-options "app")

官方 shadow-cljs 文档

这里是 shadow-cljs 自身文档中的一些有用部分:

• 安装
• nREPL 设置
• 与 CIDER 集成

确保 node.js 已安装, 并且 node 二进制文件在 Emacs 的 exec-path 中.

ClojureScript 的 Node.js REPL 设置起来非常简单, 因为它不需要你修改项目的依赖项. 你需要做的就是:

1. 在你的项目中打开某个文件.
2. 输入 M-x cider-jack-in-cljs RET.
3. 当提示你想要使用的 ClojureScript REPL 类型时, 选择 node 选项.

使用 Weasel, 你可以有一个连接到浏览器的 REPL.

1. 将 [weasel "0.7.1"] 添加到你项目的 :dependencies.
2. 输入 M-x cider-jack-in-cljs RET 并在提示你想要使用的 ClojureScript REPL 类型时选择 Weasel 选项.
3. 将此添加到你的 ClojureScript 代码中:

(ns my.cljs.core
  (:require [weasel.repl :as repl]))
(repl/connect "ws://localhost:9001")

1. 连接后, 你可以开始在 REPL 中求值代码, 你将在浏览器中看到结果.

cljs.user> (js/alert "Hello world!")

只要在你的 REPL 会话中有一个启用了 Piggieback 的 ClojureScript 环境, 代码加载和求值将无缝工作, 无论是否存在 cider-nrepl middleware. 如果 middleware 存在, 那么 CIDER 的大多数其他功能也将被启用 (包括代码补全, 文档查找, 命名空间浏览器和宏展开).

有关 Weasel 的更多信息, 你应查阅其文档.

CIDER 内置了对 nbb 的支持. 你可以使用 M-x clojure-jack-in-cljs 来 jack in到一个 nbb 项目.

或者启动其捆绑的 nREPL 服务器:

$ nbb nrepl-server

然后使用 M-x cider-connect-cljs 连接到它.

更多详情请参见专用页面.

对于所有其他自托管 REPL, 你可以按照此处的说明进行操作. 这将与任何行为良好的 nREPL 实现正常工作, 例如:

• nbb
• scittle
• joyride

支持多种编程语言的最大问题是 CIDER 假设它与 Clojure 一起使用. 在实践中, 这意味着 CIDER 在某些情况下会求值 Clojure 代码以支持其功能.

一个简单的例子是切换 REPL 的命名空间 - CIDER 只是在幕后求值 in-ns 来实现这一点.

你还必须记住, 许多高级功能 (例如, 与调试相关的所有功能) 不属于核心 nREPL 协议, 而是由 cider-nrepl middleware 提供. 其他平台需要提供该功能的兼容实现, 以便 CIDER 能够与之协作.

另一个问题是, 某些功能是 Clojure 特有的, 在其他语言中没有多大意义, 但这些功能在不适用时可以简单地忽略. 还存在一些与 clojure-mode 的耦合, 但这并不难克服.

一些例子是 REPL (它使用 clojure-mode 的语法表和缩进规则), 查找当前命名空间的逻辑 (它使用 clojure-find-ns), 等等.

所有这些实例最终都需要被更通用的版本所取代, 这些版本会根据 nREPL 连接的类型 (例如, Clojure, Racket, Fennel 等) 进行分派.

目前 CIDER 在某种程度上支持以下平台:

• Babashka
• nbb
• ClojureCLR
• scittle, joyride & friends
• Basilisp

所有这些都源于 Clojure, 因此支持它们并不需要太多工作.

尽管优先级不是很高, 但使 CIDER 能够与任何 nREPL 服务器一起使用肯定是该项目的路线图之一. 在这里, 你可以找到关于让 CIDER 与 Fennel 协作所需的更改的讨论, 以及一些说明这些更改的提交.

在这方面的任何帮助都将不胜感激!

Babashka 与 Clojure 高度兼容, 因此它与 CIDER 开箱即用.

你所需要做的就是启动它捆绑的 nREPL 服务器:

$ bb --nrepl-server

然后使用 C-c C-x c j (cider-connect-clj) 连接到它.

Babashka 的 nREPL 服务器支持所有核心 nREPL 操作, 加上代码补全, 所以你将通过它获得 CIDER 的所有基本功能.

根据你的 CIDER 版本, 你可能会收到一些关于缺少 Clojure/nREPL 版本的警告. 你可以安全地忽略这些.

从 CIDER 1.2 开始, cider-jack-in-clj 可以与使用 bb.edn 的 Babashka 项目一起工作.

Babashka 和 Clojure 之间有一些你应该记住的差异:

• 内置的 vars (例如 clojure.core/map) 没有定义位置元数据. 在实践中, 这意味着你不能在 CIDER 中导航到它们的定义.
• javadoc (clojure.java.javadoc/javadoc) REPL 实用函数目前在 Babashka 中不可用.

• Babashka 的 nREPL 文档
• babashka.nrepl

Nbb 的主要目标是让在 Node.js 上进行临时的 ClojureScript 脚本编写变得容易.

它与 ClojureScript 高度兼容, 因此可以与 CIDER 开箱即用.

你可以使用 M-x clojure-jack-in-cljs 来 jack in 到一个 nbb 项目.

或者启动其捆绑的 nREPL 服务器:

$ nbb nrepl-server

然后使用 M-x cider-connect-cljs 连接到它.

cider-jack-in-cljs 与使用 nbb.edn 的 nbb 项目一起工作.

jack-in 命令可以通过几个 defcustoms 进行配置:

• cider-nbb-command (默认为 nbb)
• cider-nbb-parameters (默认为 nrepl-server)

Basilisp 支持是在 CIDER 1.14 中添加的.

Basilisp 旨在实现在 Python 上编写具有完全互操作性的 Clojure 程序. 它与 Clojure 高度兼容.

要安装 Basilisp, 运行:

$ pip install basilisp

有几种方法可以连接到 Basilisp.

jack-in 命令可以通过以下 defcustoms 进行配置:

cider-basilisp-command

(默认为 basilisp)

如果 Basilisp 安装在虚拟环境中, 请将其更新为该虚拟环境中 basilisp 可执行文件的完整路径.

cider-basilisp-parameters

(默认为 nrepl-server)

在 Emacs 中有几种设置 (自定义) 变量的方法

1. 检查和设置变量
   • C-h v cider-basilisp-command, 和
   • C-h v cider-basilisp-parameters

2. Per-Diretory Local Variables 使用 .dir-locals.el 来设置每个模式的变量. 这个文件通常存储在项目的根目录.

   例如, 设置虚拟环境中 basilisp 可执行文件的路径

   • M-x add-dir-local-variable
   • Mode or subdirectory: clojure-mode
   • Add directory-local variable: cider-basilisp-command
   • Add cider-basilisp-command with value: "c:/dev/venvs/312/Scripts/basilisp"

   这应该会导致更新或创建一个如下所示的 .dir-local.el 文件

;;; Directory Local Variables            -*- no-byte-compile: t -*-
;;; For more information see (info "(emacs) Directory Variables")

((clojure-mode . ((cider-basilisp-command . "c:/dev/venvs/312/Scripts/basilisp"))))

1. 指定文件变量 最好将此放在你项目的 basilisp.edn 文件的顶部, 并始终从那里进行 jack-in.

   例如, 将 cider-basilisp-command 设置为从虚拟环境中启动 basilisp:

   • M-x add-dir-local-variable
   • Add file-local variable: cider-basilisp-command
   • Add cider-basilisp-command with value: "c:/dev/venvs/312/Scripts/basilisp"

   这将导致在 basilisp.edn 中出现以下内容

;; Local Variables:
;; cider-basilisp-command: "c:/dev/venvs/312/Scripts/basilisp"
;; End:
{}

这里的“其他平台”基本上指的是任何未在文档的专用部分中特别提到的 (Clojure) 平台.

如文档前面所述, CIDER 将来可能会支持非 Clojure 平台. 然而, 就目前情况而言, 这在我们的优先事项列表中并不特别高.

从 CIDER 1.6 开始, 默认的 CIDER 连接命令 cider-connect-clj 能够连接到任何实现了核心 nREPL 协议接口的 nREPL 服务器. 所以, 你需要做的就是以下几步:

• 启动一个 nREPL 服务器 (项目的 README 通常有一个关于启动 nREPL 服务器的部分).
• M-x cider-connect-clj <RET>

就是这样! 你将获得你正在使用的 nREPL 服务器所实现的每一个功能.

这里是一个不完整的 Clojure 平台列表, 你可以如上所述使用它们.

• nbb
• scittle

• joyride

  对于 nbb, 你也可以通过 cider-connect-cljs 连接, 参见 nbb.

• 无论底层平台是什么, 所有东西都将被视为 Clojure 连接.
• 错误将只作为 overlays 显示. (默认的 CIDER 错误缓冲区目前未实现).
• 你获得的功能数量将取决于你正在使用的 nREPL 服务器实现核心 nREPL 协议的程度.

传统的编程语言和开发环境通常使用一个“编辑, 编译, 运行”的循环. 在这种环境中, 程序员修改代码, 编译它, 然后运行它看它是否做了她想做的事. 然后程序终止, 程序员回到编辑程序.

这个循环一遍又一遍地重复, 直到程序行为符合程序员的期望. 虽然现代 IDE 已经优化了这个过程, 使其快速且相对无痛, 但这仍然是一种缓慢的工作方式.

Clojure 和 CIDER 提供了一种更好的工作方式, 称为交互式编程. 事实上, 这个想法是 CIDER 的核心.

使用 CIDER 的交互式编程环境, 程序员以一种非常动态和增量的方式工作. 程序员不是反复地编辑, 编译和重启应用程序, 而是启动应用程序一次, 然后在程序继续运行时添加和更新单个 Clojure 定义.

使用 CIDER REPL, 程序员可以访问不同定义的值, 并用测试数据调用程序函数, 立即看到结果. 这种方法比典型的“编辑, 编译, 运行”循环效率高得多, 因为程序在程序员与之交互时继续运行并保持其状态完整.

事实上, 有些 Clojure 程序员会保持一个 CIDER 会话运行数周甚至数月, 同时继续编写代码.

CIDER 的交互式编程环境部分地是使用一个名为 cider-mode 的 Emacs minor mode 实现的. cider-mode 补充了 clojure-mode, 允许你从源文件缓冲区求值 Clojure 代码, 并通过 CIDER REPL 将其直接发送到你正在运行的程序中.

使用 cider-mode 提供的函数将提高你的生产力, 使你成为一个更高效的 Clojure 程序员.

不幸的是, 没有人能被告知什么是交互式编程. 你必须亲眼看看.

— Clorpheus

上述描述可能听起来有点太“元”, 所以可能查看一些演示交互式编程工作流程的视频将帮助你更好地理解关键概念. 这里有一些想法:

• 深入 CIDER - CIDER 基本功能概述
• Emacs & Clojure, 一段 Lispy 的恋情 - 所有流行的 Emacs Clojure 开发包 (包括 CIDER) 的概述

• Spacemacs 和 CIDER 的 Clojure 开发工作流

  由于 CIDER 发展迅速, 这些视频中的一些信息在你观看时可能已经过时. 尽管如此, 交互式编程的核心思想是不变的, 所以你观察和体验到的任何差异都可能是表面的.

你可以在“附加资源”页面上找到更多 CIDER 演示.

cider-mode 通常在你启动 CIDER 时自动启用, 但你也可以像这样为 Clojure(Script) 缓冲区显式启用它:

(add-hook 'clojure-mode-hook #'cider-mode)

或者如果你正在使用 clojure-ts-mode:

(add-hook 'clojure-ts-mode-hook #'cider-mode)

对于从 clojure-mode 或 clojure-ts-mode 派生的模式, 如 clojurescript-mode 和 clojure-ts-clojurescript-mode, 无需显式启用它.

cider-mode 通常在你退出 CIDER 时自动禁用, 但你也可以通过输入 M-x cider-mode (前提是它已在该缓冲区中启用) 在任何缓冲区中显式禁用它.

通常, 你与任何源缓冲区的交互都始于用 C-c C-k 求值它. 之后, 你通常只会用 C-c C-e (求值前一个 form) 或 C-c C-c (求值当前顶层 form) 来求值单个 form.

有时某个求值会花费很长时间, 你可以用 C-c C-b 来中断它.

在源文件和 REPL 之间跳转就像按 C-c C-z 一样简单. 如果你在源缓冲区中用 C-u 前缀调用该命令, 它还会将 REPL 缓冲区的命名空间更改为与源缓冲区的命名空间匹配.

你还很可能会用 M-. 查找某个定义或用 C-c C-d C-d 查找一些文档.

定义和文档查找命令对 Java 和 Clojure 都有效.

如果你记不起某个需要的 var 的名字, cider-apropos (C-c C-d a 或 C-c C-d C-a) 和 cider-apropos-documentation (C-c C-d f 或 C-c C-d C-f) 会帮助你找到匹配某个字符串的 vars.

cider-mode 还为你提供了开箱即用的代码补全功能, 无需额外设置, 并集成了 eldoc.

这几个基本命令可以让你在日常工作中走得很远. 继续阅读以获取更多信息!

这是 cider-mode 的按键绑定列表:

无需记住此列表. 如果你在一个启用了 cider-mode 的 Clojure 缓冲区中, 你将有一个 CIDER 菜单可用. 该菜单列出了所有最重要的命令及其键绑定. 你也可以调用 C-h f RET cider-mode 来获取 cider-mode 的键绑定列表.

CIDER 交互菜单

一个更好的解决方案是安装 which-key, 它会在你开始输入一些键时自动向你显示可用键绑定的列表. 这将大大简化你与 CIDER 的交互, 特别是在开始时. 如果你在 Clojure 缓冲区中输入 C-c C-d, 你会看到以下内容:

CIDER which-key

CIDER 的求值命令使用了一套在 Emacs 中流行但对不熟悉它的人来说有些困惑的术语. 让我们来看看它:

• defun - 顶层表达式
• sexp - s-expression, form
• last-sexp - 光标 (在 Emacs lingo 中称为 point) 前的 form
• sexp-at-point - 光标下/周围的 form
• buffer - Emacs 用于表示任何内容的抽象; 通常由文件支持.
• region - 缓冲区的选中部分
• load - "evaluate" 的同义词; 最常用于缓冲区/文件的上下文中

由于 CIDER 几乎所有的功能都是通过检查应用程序的运行时 (REPL) 状态来实现的, 所以在像代码补全, eldoc 或定义查找这样的功能工作之前, 你需要先求值一些东西.

通常, 当访问 Clojure 缓冲区时, 你做的第一件事就是用 cider-load-buffer (C-c C-k) 加载 (求值) 缓冲区.

之后, 大多数时候你会一次求值一个表达式, 使用 cider-eval-last-sexp (C-c C-e 或 C-x C-e) 或 cider-eval-defun-at-point (C-c C-c 或 C-M-x).

WIP

虽然前面讨论的基本求值命令对大多数人来说应该足够了, 但 CIDER 提供了大量的附加求值命令. 其中一些非常奇特, 以至于可以轻易地称之为“奇异”. 本节将简要介绍其中一些.

广义上讲, 奇异的求值命令可以分为以下几类:

• 某些基本命令的变体 (例如 cider-eval-list-at-point 和 cider-eval-sexp-at-point)
• 将结果插入当前缓冲区的命令 (例如 cider-eval-last-sexp-and-replace)
• 在不同上下文中求值表达式的命令 (例如使用用户提供的绑定)
• 求值缓冲区某个特定部分的命令 (例如 cider-eval-ns-form)

大多数奇异的求值命令没有“顶层”键绑定, 应通过 CIDER 的求值命令键映射 (cider-eval-commands-map) 访问, 这意味着它们共享标准前缀 C-c C-v. 除此之外, 几个漂亮打印其结果的相关命令被分组在 C-c C-v C-f 下.

你几乎可以在任何时候使用 M-x cider-read-and-eval (在 cider-mode 缓冲区中绑定到 C-c M-:) 在 minibuffer 中求值 Clojure 代码. TAB 补全将在 minibuffer 中工作, 就像在 REPL 和源缓冲区中一样.

在 Clojure 缓冲区中输入 C-c C-v . 会将点处的 defun 插入到 minibuffer 中进行求值. 这样你可以向函数传递参数并求值它, 并在 minibuffer 中看到结果.

你还可以在 minibuffer 中启用其他方便的模式. 例如, 你可能希望同时拥有 eldoc-mode 和 paredit-mode:

(add-hook 'eval-expression-minibuffer-setup-hook #'eldoc-mode)
(add-hook 'eval-expression-minibuffer-setup-hook #'paredit-mode)

你可以使用 cider-file-loaded-hook 来在文件被求值后触发某个动作.

cider-auto-test-mode 是基于这个钩子实现的——每次你求值一个文件时, 测试都会重新运行.

你可以使用 cider-before-eval-hook 来在求值请求发送到 nrepl 服务器之前触发某个动作.

你可以使用 cider-after-eval-done-hook 来在从 nrepl 服务器收到状态为 "done" 的求值响应后触发某个动作.

nREPL 有一个异步求值模型, 其中求值请求被排队, 响应在可用时发送回客户端. 这个模型在大多数情况下工作得很好, 因为它不需要客户端在等待响应时阻塞, 但它也要求客户端能够舒适地处理响应回调.

不幸的是, Emacs 的一些内部 API 与异步求值不兼容 (例如补全, eldoc 等), 在这些情况下, CIDER 会模拟同步求值. 理解几点很重要:

• CIDER 的同步求值命令应该谨慎使用
• 同步求值 API 最常见的用例是求值一些简单且快速运行的工具相关代码
• 同步求值可能导致客户端锁定, 因为 Emacs (大部分) 是单线程设计的

CIDER 试图通过为同步求值施加 10 秒的求值请求超时来缓解后者. 如果需要, 你可以调整这个默认值:

;; 将同步请求超时增加到 1 分钟
(setq nrepl-sync-request-timeout 60)

;; 禁用同步请求超时
(setq nrepl-sync-request-timeout nil)

CIDER 内部将其执行的第一个同步求值请求的超时增加到 30 秒, 因为它可能需要很多命名空间并且需要更多时间来完成. 详情请参见 cider—​prep-interactive-eval.

你可能已经注意到, CIDER 通常为许多求值命令提供了 2-3 个不同的键绑定. 如果你想知道“为什么?”, 答案很简单——历史原因. CIDER 的主要灵感来源, Emacs 和 SLIME, 提供了或多或少相同的功能, 但使用了不同的键绑定. CIDER 试图通过同时采纳它们来找到一个共同点.

除此之外, 当 CIDER 创下了求值命令的世界纪录时, 我们为所有求值命令引入了一个专用的键映射 (即所有以 C-c C-v 为前缀的命令). 这导致了一些有趣的情况, 比如 cider-eval-defun-at-point 有 3 个键绑定:

• C-M-x (Emacs 风格)
• C-c C-c (SLIME 风格)
• C-c C-v (C-)d (CIDER 风格)

好吧, 那些技术上是 4 个键绑定, 但谁在乎呢!

你们中的一些人可能想知道为什么是 C-c C-v 而不是 C-c C-e, 对吧? 还是历史原因. 历史上 C-c C-e 被映射到 cider-eval-last-sexp, 否则我们会选择这个绑定. 未来仍有可能回收它, 因为大多数人可能正在使用 C-x C-e 来执行 cider-eval-last-result, 而好的键绑定太宝贵了, 不应该像这样浪费.

下面是大多数求值命令的键绑定列表:

你会在 CIDER Eval 菜单中找到所有求值命令及其键绑定.

开箱即用, CIDER 使用标准的 Emacs 工具进行代码补全. 当你按 TAB 或 M-TAB 时, 你将在一个专用的缓冲区中获得补全候选.

代码补全

关于标准补全, 有两点需要注意:

1. 默认的 M-TAB 键绑定在将其用于在打开的应用程序之间切换的桌面环境中无法使用.
2. 你必须通过在你的 Emacs 配置中添加此代码片段来手动配置 TAB 进行补全:

(setq tab-always-indent 'complete)

通常 TAB 只进行缩进, 但现在如果代码已经正确缩进, 它也会进行补全.

虽然标准的 Emacs 工具工作得很好, 但我们建议 CIDER 用户考虑使用 company-mode 或 corfu-mode 代替. 这些可以用于源代码和 REPL 缓冲区中的自动补全, 具有以下优点:

• 更好的 UI.
• 与 Clojure docstrings 和 Java doc 注释的集成.

company-mode 和 corfu-mode 都受以下 CIDER 配置选项的影响:

• cider-docstring-max-lines (默认 20) 控制在提供补全时将包含多少行 docstring (最多) (在弹出窗口或回显区, 取决于你的设置). 值得注意的是, 对于 Java 文档, CIDER 不仅仅是修剪行, 而是查看结构并尝试找到适合 cider-docstring-max-lines 的最大组合:
  • 整个注释体, 后跟其“块标签” (Returns/Throws/Params 信息)
  • 注释的第一句话, 后跟块标签
  • 块标签
  • 注释的第一句话.

从 1.18 版本开始, CIDER 默认启用一个自定义的补全样式, 提供更丰富和更有用的候选匹配, 例如:

• 通过各个部分的首字母匹配包含破折号的长变量, 例如 mi 或 mai 补全为 map-indexed.
• 通过部分的首字母匹配命名空间, 例如 cji 补全为 clojure.java.io.
• 通过短名称前缀匹配未导入的类名, 例如 BiFun 补全为 java.util.function.BiFunction.

你可以在这里学习所有的补全场景和功能.

如果你只想接收标准的前缀限制补全 (候选者必须在开头逐字包含前缀), 你可以通过将其添加到你的配置中来禁用此功能:

(cider-enable-cider-completion-style -1)

补全候选将默认用对应其类型的缩写进行注解, 并且 (根据上下文) 还会注解其命名空间. 用于格式化注解的函数可以通过 cider-annotate-completion-function 进行配置. 使用的缩写由 cider-completion-annotations-alist 配置, 命名空间包含的上下文由 cider-completion-annotations-include-ns 配置.

补全注解

可以通过将 cider-annotate-completion-candidates 设置为 nil 来禁用补全注解.

CIDER 的 complete-at-point 函数支持大多数补全样式, 包括 partial-completion, orderless, flex, 以及其自定义的补全样式 cider. 后者默认启用. 有时用户可能希望为 CIDER 的 complete-at-point 函数使用不同的补全样式. 这可以通过设置 completion-category-overrides 来实现, 覆盖 CIDER complete-at-point 函数的补全样式. 以下代码片段完成了这个任务:

(add-to-list 'completion-category-overrides '(cider (styles basic)))

关于这些补全样式如何运作的更详细描述, 请参考官方 Emacs 手册中关于如何选择补全替代方案的部分.

这指定了 cider 补全类别默认应使用 basic 补全样式.

有时, 补全用户体验可能会被一个要求 Member in class 的 completing-read 中断. 这用于更好的 Java 补全和文档.

然而, 如果你对当前候选不感兴趣, 对其进行消歧就毫无用处, 并且该提示可能会很烦人.

如果你正在使用 Company 进行补全, 并使用 IDO 进行 completing-read, 你可以通过自定义使 <up> 和 <down> 键取消提示:

(advice-add 'cider-class-choice-completing-read
            :around
            (lambda (f a b)
              (cider--with-temporary-ido-keys "<up>" "<down>"
                (funcall f a b))))

有时, 补全无法识别在 REPL 启动后动态加载的依赖项带来的新类 (例如通过 Clojure 1.12 的 add-lib). 执行 M-x cider-completion-flush-caches (或通过菜单 CIDER Interaction->Misc->Flush completion cache) 会强制补全后端重新读取它能在 classpath 上找到的所有类.

如果你只使用 cider-jack-in, 你真的不需要知道这些.

代码补全逻辑的大部分位于 cider-nrepl 的 completion middleware 中. 在内部, 它委托给 compliment 进行 Clojure 补全, 委托给 clj-suitable 进行 ClojureScript 补全.

nREPL 也有一个内置的 completions op, 在没有 cider-nrepl 的情况下, CIDER 将会回退到它. 它的 API 与 cider-nrepl 中的 complete op 类似, 并且可以配置为使用不同的补全函数. 内置的 op 目前只支持 Clojure. 更多细节请参见 nREPL 文档.

基本上, 在有 cider-nrepl 的情况下你会得到很棒的代码补全, 否则就是基本的补全.

下面描述的工作流因这篇博客文章而流行, 它也是 CIDER 对此的灵感来源.

输入 C-c M-n r 或 C-c M-n M-r 将调用 cider-ns-refresh 并重新加载 classpath 上所有已修改的 Clojure 文件.

添加一个前缀参数, C-u C-c M-n r, 将无条件地重新加载 classpath 上的所有命名空间, 而不管它们的修改状态如何.

添加一个双前缀参数, C-u C-u C-c M-n r, 将在重新加载之前首先清除命名空间跟踪器的状态. 这对于从某些类型的错误中恢复很有用, 而正常的重新加载无法恢复这些错误. 一个很好的例子是循环依赖. 权衡之处在于, 任何已删除文件中的陈旧代码可能不会被完全卸载.

cider-ns-refresh 包装了 clojure.tools.namespace, 因此, 关于编写可重载代码的相同好处和注意事项也适用.

上述三个操作分别类似于 clojure.tools.namespace.repl/refresh, clojure.tools.namespace.repl/refresh-all 和 clojure.tools.namespace.repl/clear (后跟一个正常的 refresh).

你可以定义在重新加载之前和成功重新加载之后调用的 Clojure 函数, 当使用 cider-ns-refresh 时:

(setq cider-ns-refresh-before-fn "user/stop-system!"
      cider-ns-refresh-after-fn "user/start-system!")

这些必须设置为绑定到无参数函数的 vars 的命名空间限定名称. 这些函数必须是同步的 (阻塞的), 并且期望是具有副作用的 - 它们将总是串行执行, 不会重试.

默认情况下, 关于正在进行的重载状态的消息将在你调用 cider-ns-refresh 后显示在回显区. 同样的信息也将记录在 *cider-ns-refresh-log* 缓冲区中, 连同 cider-ns-refresh-before-fn 和 cider-ns-refresh-start-fn 打印到 *out* 或 *err* 的任何内容.

你可以通过将 cider-ns-refresh-show-log-buffer 变量设置为非 nil 值, 使 *cider-ns-refresh-log* 缓冲区在你调用 cider-ns-refresh 后自动显示. 这也将防止任何相关的消息同时显示在回显区.

(setq cider-ns-refresh-show-log-buffer t)

默认情况下, CIDER 会提示是否保存 classpath 上所有已修改的 clojure-mode 缓冲区访问的文件. 你可以使用 cider-ns-save-files-on-refresh 和 cider-ns-save-files-on-refresh-modes 来自定义此行为.

clj-reload 的支持是在 CIDER 1.14 中引入的.

你也可以使用 cider-ns-refresh 配合 clj-reload 而不是 clojure.tools.namespace. 它支持在重载之间保留 vars, 以及与 tools.namespace 的一些其他差异.

(setq cider-ns-code-reload-tool 'clj-reload)

使用 clj-reload, 你应该像使用文档中描述的那样设置源目录. 如果你不手动设置它们, 它将默认使用当前项目的资源目录, 方式与 tools.namespace 相同.

未来我们可能会将 cider-ns-refresh 重命名为更具工具无关性的名称 (例如 cider-ns-smart-reload), 以反映它现在支持不同的代码重载工具.

有时, cider-ns-refresh 可能不适合你. 如果你正在寻找一种更强制的重载方式, 可以使用 cider-ns-reload (C-c M-n l) 和 cider-ns-reload-all (C-c M-n M-l) 命令. 这些命令在 REPL 中调用 Clojure 的 (require ... :reload) 和 (require ... :reload-all) 命令.

这些命令不依赖于 cider-nrepl, 所以它们总是可用的.

CIDER 依赖于 nREPL 自己的值打印机制. 详情请参考 nREPL 的文档.

你可以使用选项 cider-print-fn 来配置 CIDER 用于漂亮打印求值结果和其他数据的函数, 它可以取以下可能的值:

• nil 让 nREPL 选择打印函数. 这将使用 nrepl.middleware.print/*print-fn* 的绑定值, 默认为等价于 clojure.core/pr.
• pr 使用等价于 clojure.core/pr.
• pprint 使用内置的 clojure.pprint/pprint (这是默认值).
• fipp 使用 Fast Idiomatic Pretty-Printer. 这比 clojure.core/pprint 快大约 5-10 倍.
• puget 使用 Puget, 它在 fipp 之上提供了数据的规范序列化, 但会带来轻微的性能成本.

• zprint 使用 zprint, 这是一个快速灵活的替代方案, 替代上面提到的库.

  要使 fipp, puget 和 zprint 打印机工作, 你需要在你的项目中明确添加相应的依赖项.

或者, cider-print-fn 可以设置为一个 Clojure var 的命名空间限定名称, 其函数接受三个参数:

• 要打印的对象
• 用于打印的 java.io.PrintWriter
• 一个 (可能为 nil) 的选项 map.

(setq cider-print-fn "user/my-pprint")

这里有一个例子:

(ns cider.pprint
  (:require
   [clojure.pprint :as pp]))

(defn pprint
  "A simple wrapper around ~clojure.pprint/write~.

  Its signature is compatible with the expectations of nREPL's wrap-print
  middleware."
  [value writer options]
  (apply pp/write value (mapcat identity (assoc options :stream writer))))

你可以设置 cider-print-quota 来限制任何打印操作将返回的字节数. 默认值为 1MB, 如果不希望有任何限制, 可以设置为 nil. 请注意, 如果没有设置配额, 某些打印操作可能永远不会终止 —— 你仍然可以使用 cider-interrupt 来停止它们.

你配置的打印函数也可能支持限制打印对象的长度和深度 —— 或者使用 clojure.core/*print-length* 和 clojure.core/*print-level*, 或者在提供的选项 map 中.

你可以通过设置 cider-print-options 向打印函数传递一个选项 map. 这里有一个例子:

(setq cider-print-options '(("length" 50) ("right-margin" 70)))

每个打印引擎都有自己的配置选项, 所以你必须确保相应地设置 cider-print-options.

这里有一个表格, 描述了每个打印引擎支持的最常见打印选项的名称差异.

并非所有打印引擎在所有情况下都使用 (或默认使用) 动态变量, 因此在 REPL 中设置它们可能不会产生预期的效果. 请参阅每个引擎的相应文档:

• clojure.core/pr: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/*print-dup*
• clojure.pprint: https://clojuredocs.org/clojure.pprint/write
• Fipp: https://github.com/brandonbloom/fipp/#printer-usage
• Puget: https://github.com/greglook/puget#usage
• zprint: https://github.com/kkinnear/zprint/#what-is-configurable

如果你正在使用 CIDER 提供的打印引擎之一, fill-column 的值将用于选项 map 中的相关宽度选项. 你可以通过在 cider-print-options 中硬编码相关选项来覆盖此设置.

默认情况下, 当发生异常时, CIDER 会使用 cider-stacktrace-mode 在一个错误缓冲区中显示异常. 你可以抑制这种行为, 这将导致只将错误消息作为临时 overlay 或在回显区输出:

(setq cider-show-error-buffer nil)

只有当 cider-use-overlays 不为 nil 时, 你才会看到 overlay.

从 CIDER 1.8.0 开始, 只有运行时异常 (而不是编译错误) 会导致显示堆栈跟踪缓冲区. 这更好地遵循了 Clojure 1.10 的预期语义. 此行为由 cider-clojure-compilation-error-phases 配置选项控制. 如果你希望忽略错误阶段, 并且只考虑 cider-show-error-buffer, 请自定义:

(setq cider-clojure-compilation-error-phases nil)

有时, 显示的错误可能源于 CIDER 本身的 bug. 这些内部错误可能会频繁发生并中断你的工作流程, 但你可能不想通过使用 cider-show-error-buffer 来抑制所有堆栈跟踪缓冲区. 相反, 你可能只想抑制这种特定类型的内部错误. 堆栈跟踪缓冲区在显示内部错误时提供了这样的选项. 一个带有错误类型名称的切换按钮将会显示, 你可以切换这种特定类型的错误是否会导致堆栈跟踪缓冲区自动显示. 切换按钮只在当前 Emacs 会话期间控制此行为, 但如果你想使抑制更持久, 你可以通过自定义 cider-stacktrace-suppressed-errors 变量来实现. 缓冲区还将提供一个直接链接到 bug 报告页面, 以帮助其诊断和修复.

与 cider-show-error-buffer 或 cider-stacktrace-suppressed-errors 的值无关, CIDER 总是会在后台生成错误缓冲区. 如果你决定需要, 你可以使用 cider-selector (C-c M-s) 来访问这个缓冲区.

对于错误缓冲区, 还有两种更具选择性的策略:

(setq cider-show-error-buffer 'except-in-repl) ; or
(setq cider-show-error-buffer 'only-in-repl)

要禁用在显示错误缓冲区时自动选择它:

(setq cider-auto-select-error-buffer nil)

默认情况下, 当你跳转到给定堆栈帧的源时, 将选择除 *cider-error* 之外的 Emacs 窗口. 如果你希望重用 *cider-error* 的窗口, 请配置:

(setq cider-stacktrace-navigate-to-other-window nil)

如果你自定义了此设置, 当你导航到给定的源文件时, 你可以使用 C-x <left> (previous-buffer) 或 M-, (xref-pop-marker-stack) 导航回 *cider-error*.

CIDER 附带了一个强大的解决方案来处理 Clojure 的堆栈跟踪. CIDER 在一个特殊的 major mode, cider-stacktrace-mode 中呈现堆栈跟踪, 它为你提供了一些关键功能:

• 能够过滤掉某些堆栈帧以减少混乱
• 一些方便的方法来导航到异常的原因
• 能够通过一次按键直接跳转到代码

CIDER 通过允许你使用 cider-stacktrace-default-filters 变量应用一个过滤器列表来帮助你减少 Clojure 堆栈跟踪的混乱. 有效的过滤器类型包括 java, clj, repl, tooling 和 dup. 指定这些过滤器之一将从堆栈跟踪显示中移除相应的帧. 还有一些“正向”过滤类型 (反向过滤器), 它们指定应该显示什么. 例如, project 的值将导致只显示项目帧, 而 all 将强制显示所有堆栈帧. 请注意, project 和 all 是互斥的. 如果它们都存在, 第一个将决定行为.

(setq cider-stacktrace-default-filters '(tooling dup))
;; or
(setq cider-stacktrace-default-filters '(project))

最后, CIDER 可以在缓冲区中显示错误消息时将其包装起来, 以帮助提高其可读性. CIDER 为此使用了 cider-stacktrace-fill-column, 它可以取三种类型的值:

• nil: 错误不被包装.
• numeric: 错误消息被包装到指定的填充列.
• 其他真值但非数字: 错误消息使用 fill-column 的值进行包装.

例如, 以下将导致错误消息被包装到 80 列:

(setq cider-stacktrace-fill-column 80)

在 cider-error 中, 当直接点击一个顶层异常 (原因链中的任何一个) 时, 那个特定的异常将在 CIDER Inspector 中被检查. 你也可以点击渲染的异常数据来直接检查它.

这个点击行为在 cider-stacktrace-exception-map 和 cider-stacktrace-ex-data-map 中定义和自定义.

检查异常和 ex-data

最基本的事情是转到某个符号并按 C-c C-d C-d. 这将打开一个文档缓冲区, 其中包含有关该符号引用的所有相关信息 (特殊形式, var, Java 方法等).

可以使用快捷键 C-c C-d d. 大多数 CIDER 键映射都提供了相同快捷键的两个版本 (带或不带最后的 Control), 因为有些人喜欢一直按住 Control, 而有些人则不喜欢.

通常, 该命令作用于点处的符号. 如果带前缀参数调用, 或者在点处没有找到符号, 它会提示输入一个符号.

大多数 JDK 发行版都附带一个 src.zip 文件 (一个包含所有基础 Java 源文件的归档). 如果你的 JDK 中有这样的归档文件, 当你查询 Java 类 (例如 java.lang.Thread) 或方法 (例如 java.lang.Thread/currentThread) 的文档时, CIDER 会自动解析源文件, 并在文档缓冲区中显示格式正确的 JavaDoc.

你还会看到更好的 Eldoc 文档 (minibuffer 提示) 用于 Java 方法. 如果源文件存在, 你可以通过在类名或方法名上按 M-. 跳转到类或方法的定义.

此外, 如果你下载了某个第三方 Java 库的特殊 -sources.jar 文件, CIDER 能够解析 JavaDoc 源文件并跳转到定义. 请参阅下一节关于如何下载源 JAR 的说明.

从 1.17 版本开始, CIDER 能够在您请求 Java 类/方法的文档或跳转到 Java 类/方法的定义时自动下载必要的源 JAR 文件. 为了下载源文件, 变量 cider-download-java-sources 必须启用 (默认是启用的).

当下载触发时, CIDER 会在 minibuffer 中显示一条消息. 获取单个源 JAR 通常需要几秒钟. CIDER 对每个进程的特定依赖项只会尝试下载一次源 JAR——如果下载失败 (通常是因为该依赖项没有发布源 JAR 到 Maven) , CIDER 在下次重启之前不会重试.

虽然 Eldoc 功能受益于 Java 源码, 但 eldoc 本身不会触发 Java 源 JAR 的下载. 你必须手动查找一次文档或跳转到定义, 以便下载 JAR. 之后, Eldoc 将获取 Java 源码并显示更好的提示.

或者, 你可以使用 enrich-classpath 一次性下载当前项目使用的所有源 JAR. 这会增加启动时间, 但不会在运行时触发单个 JAR 的获取.

CIDER 通过命令 cider-javadoc (C-c C-d j 或 C-c C-d C-j) 提供了对在线 Javadoc 文档的快速访问, 使用你的默认浏览器.

通常, 该命令作用于点处的符号. 如果带前缀参数调用, 或者在点处没有找到符号, 它会提示输入一个符号.

如果你不希望 CIDER 使用外部浏览器显示 JavaDoc, 你可以像这样使用内置的 EWW 浏览器:

(setq browse-url-browser-function 'eww-browse-url)

CIDER 提供了 clojure.repl/find-doc 的一个方便的替代品 - cider-apropos-documentation (C-c C-d f 或 C-c C-d C-f). 这允许你在所有已加载的 vars 的文档字符串中搜索, 结果会呈现在 Emacs 的 apropos 界面中.

或者, 你可以使用 cider-apropos-documentation-select (C-c C-d e 或 C-c C-d C-e), 它会将匹配的结果作为列表呈现在 minibuffer 中, 这样你就可以快速选择你需要的内容 (特别是如果你正在使用像 ido 或 vertico 这样的包).

CIDER 提供了与流行的 ClojureDocs 服务的集成. 你有两种主要的方式与 ClojureDocs 交互:

• 通过 cider-clojuredocs (C-c C-d C-c) 在 Emacs 的一个专用缓冲区中显示文档
• 通过 cider-clojuredocs-web (C-c C-d C-w) 在你的默认浏览器中打开文档

该文档作为 EDN 资源与 cider-nrepl (更准确地说是与 cider-nrepl 的依赖项 orchard) 捆绑在一起, 并且是 ClojureDocs 数据的快照. 你可以使用 M-x cider-clojuredocs-refresh-cache 手动将其更新到最新版本.

请记住, ClojureDocs 中的文档仅限于 Clojure 和一些 Clojure Contrib 库 (例如 core.async). 目前不支持 ClojureScript.

如果你对 CIDER 如何与 ClojureDocs 交互的内部机制感到好奇, 请查看这篇文章.

有时在你的文档字符串中, 你可能希望能够向其他程序员指出不同的定义. 如果你将一个定义的名称指定为完全限定的符号, 或者将其用反引号 (...) 或 Codox 风格的分隔符 ([[...]]) 括起来 , 当 CIDER 在文档缓冲区中显示文档字符串时, 会将这些引用转换为活动链接.

如果名称在另一个命名空间中, 那么你必须在文档字符串中包含完全限定的名称.

带有包含引用的文档字符串的示例函数:

(defn test-fn
  "Test function.
  Also see: clojure.core/map, clojure.core/reduce, `defn`.
  You can reference variables like `thor`, [[kubaru.data.zookeeper/yoda]].
  Also works with references to java interop forms, `java.lang.String/.length`."
  []
  (+ 1 1))

如果你想支持其他引用格式, 你可以更改 CIDER 用于查找引用的分隔符. 只需更新 cider-doc-xref-regexp 中的正则表达式以匹配你喜欢的格式. 正则表达式的第一个组应始终匹配交叉引用名称.

例如, 如果你想使用 Latex 风格的引用 (\ref{...}), 正则表达式将是:

(setq cider-doc-xref-regexp "\\\\ref{\\(?1:[^}]+\\)}")

CIDER 另见

默认情况下, CIDER 会将鼠标下的符号的文档显示在一个工具提示中 (使用一个 overlay) 或你的回显区. 这由配置设置 cider-use-tooltips 控制. 你可以通过将该变量设置为 nil 来禁用此行为.

(setq cider-use-tooltips nil)

如果 tooltip-mode 被禁用或 help-at-pt-display-when-idle 设置为 t, 工具提示也将被禁用.

请查看 help-at-pt-display-when-idle 的文档, 以更好地理解 help-echo Emacs 功能的工作原理.

在本节的上下文中, "会话" 指的是一组 nREPL 连接. 这不应与 nREPL 自己的会话概念相混淆 (每个 nREPL 连接可以分为多个会话).

CIDER 通过 Sesman 会话维护一个分组的已打开 nREPL 连接视图. 每个会话是共享同一个 nREPL 服务器的连接集合. 然而, 你可以有多个会话共享同一个 nREPL 服务器 (虽然你不太可能需要这样做).

所有 CIDER 命令 (求值, 补全, 切换到 REPL 等) 都在当前会话中的相关 REPL 上操作. 当前会话是所有链接会话 (或者在没有链接时是友好会话) 中最相关的会话.

会话的相关性由链接上下文的特异性和 REPL 缓冲区的最近性决定.

如果当前上下文链接到单个会话, 那么该会话就是当前会话. 如果多个会话链接到同一个上下文 (比如说, 一个项目), 那么当前会话是包含最近查看的 REPL 的那个会话.

链接到更具体上下文的优先级更高. 例如, 如果你有两个会话链接到同一个项目, 另一个会话链接到该项目内的一个目录, 那么链接到该目录的会话是当前会话. 因此, 同样, 没有歧义.

默认情况下, Sesman 允许同时链接到项目和目录的多个链接, 但每个缓冲区只有一个链接. 如果你想改变这一点, 请参见 sesman-single-link-contexts.

当前 REPL 是来自当前会话的最相关的 REPL. REPL 的相关性由当前缓冲区的类型决定. 例如, 如果当前缓冲区是 clj 缓冲区, 则选择 clj REPL.

当会话中有多个 clj REPL, 或者当前缓冲区是 cljc 缓冲区并且会话中同时存在 clj 和 cljs REPL 时, 可能会出现歧义情况. 在这种情况下, 当前 REPL 是相关类型中最近查看的 REPL.

使用 C-c C-z 切换到当前 REPL 缓冲区. 然后你可以使用相同的组合键切换回你来自的 Clojure(Script) 缓冲区.

单个前缀 C-u C-c C-z 将切换到当前 REPL 缓冲区, 并根据当前 Clojure(Script) 缓冲区中的命名空间设置该缓冲区中的命名空间.

会话可以链接到上下文 (项目, 目录和缓冲区)

• C-c C-s b (sesman-link-with-buffer)
• C-c C-s d (sesman-link-with-directory)
• C-c C-s p (sesman-link-with-project)

• C-c C-s u (sesman-unlink)

  通常, 你会想在文件缓冲区中调用这些命令, 偶尔在一些特殊缓冲区中 (例如, scratch 缓冲区). 你绝对不应该在 REPL 缓冲区中运行它们, 因为 REPL 是会话的一个组成部分.

Sesman 定义了“友好”会话, 以便在没有显式链接的上下文中对会话进行即时操作. 在 CIDER 中, 友好会话由项目依赖项定义. 例如, 当你使用 cider-find-var (M-.) 导航到依赖项目中的 var 定义时 , 当前项目的会话就成为该依赖项的友好会话.

当你从依赖项目中求值一些代码并且该项目中没有显式链接时, 将使用最近的友好会话来求值代码. 显式链接的会话优先于友好会话.

你可以通过自定义 sesman-use-friendly-sessions 来禁用友好会话推断.

使用 C-c C-s i (sesman-info) 获取当前上下文中所有链接和友好会话的信息. 使用 C-u, 显示所有 CIDER 会话的信息. 对于连接特定的信息, 请使用 CIDER 的内置 cider-describe-connection (C-c M-d).

通过 sesman-browser (C-c C-s w) 可以获得所有 CIDER 会话的交互式视图.

默认情况下, 会话名称由缩写的项目名称, 主机和端口组成 (例如, project/dir:localhost:1234). REPL 缓冲区名称由会话名称和 REPL 类型规范后缀组成 (例如, *project/dir:localhost:1234(cljs:node)*).

你可以使用 cider-session-name-template 自定义会话名称, 使用 nrepl-repl-buffer-name-template 自定义 REPL 名称. 另请参见 cider-format-connection-params 以获取可用格式.

在正常情况下, CIDER 在结束会话时会自动杀死 REPL 缓冲区并进行清理. 然而, 当会话意外终止时, 例如当它崩溃或与外部服务器进程断开连接时, REPL 缓冲区会留下一个没有活动连接的状态, 并输出一个日志:

*** Closed on < date/time > ***

在启动新连接时, CIDER 可以检测到这些“死掉的 REPL”, 并提议为新连接重用该缓冲区. 默认情况下, 每当有死掉的 REPL 缓冲区可供重用时, 它都会提示确认, 但你可以通过变量 cider-reuse-dead-repls 来自定义此行为.

将其设置为 auto 会自动重用一个死掉的 REPL 缓冲区, 仅当有多个选项可供选择时才显示提示. 要完全抑制提示, 将其设置为 nil 以总是启动一个新的 REPL 缓冲区, 或设置为 any 以重用最相关的死掉的 REPL.

CIDER 提供了一种通过 M-x cider-scratch 命令创建 Clojure 草稿板的简单方法. 这是一种很好的方式来尝试一些代码, 而不必创建源文件或污染 REPL 缓冲区, 与 Emacs 自己的 *scratch* 缓冲区非常相似.

该功能基于这篇文章中的思想, 并在 CIDER 0.22 中引入.

在 CIDER 中使用查找引用有两种方式:

• cider-xref-fn-refs (C-c C-? r) 在一个专用的缓冲区中显示点处函数的用法
• cider-xref-fn-refs-select (C-c C-? C-r) 在 minibuffer 中显示用法

下面是它们在实际操作中的样子:

CIDER 查找引用

请记住以下限制:

• 这只适用于 Clojure
• 它由运行时状态分析驱动, 这意味着它只会显示已加载命名空间的数据 (像 CIDER 的大部分功能一样)
• 它 (目前) 找不到在 lambdas 中的用法
• 它没有给我们某物被使用的精确位置, 我们只知道它被使用了

好的一面是:

• 它超级快
• 它不需要任何静态代码分析
• 它仍然比 grep 更可靠

这个功能不完美, 但至少在你需要时它在那里. 另外, 你还可以使用 cider-xref-fn-deps (C-c C-? d) 和 cider-xref-fn-deps-select (C-c C-? C-d) 快速导航到某个函数使用的所有函数. 如果你不想跳转到某个函数的源代码去看它内部引用 (使用) 了哪些函数, 这些命令非常方便.

别忘了你还有几个第三方替代方案:

• 由 clj-refactor.el 提供的更复杂的 AST 驱动的“查找用法”
• Projectile 的“在项目中 grep” (projectile-grep, 通常绑定到 C-c p g)

cider-selector (C-c M-s) 命令允许你快速导航到 Clojure 项目上下文中的重要缓冲区——例如 REPL, 堆栈跟踪缓冲区, 文档缓冲区, 最近访问的 Clojure 文件等. 该命令的使用非常简单——调用它后, 你需要输入一个标识目标缓冲区的单个键 (例如, r 代表 REPL).

关于默认键绑定 C-c M-s 需要记住的一件事是, 它只在启用了 cider-mode 的缓冲区中可用 (例如, Clojure 源缓冲区) 和 CIDER REPL 中. 如果你想让它在任何地方都可用, 在你的 Emacs 配置中添加一个全局绑定可能是个好主意:

(global-set-key (kbd "C-c s") #'cider-selector)

这是 cider-selector 所有键绑定的列表:

这些键中的任何一个都可以用 4 作前缀, 使目标缓冲区在不同的窗口中打开 (而不是当前窗口).

你可以使用 def-cider-selector-method 轻松地用新命令扩展选择器:

(def-cider-selector-method ?z
  "CIDER foo buffer."
  cider-foo-buffer)

你可以使用 M-x cider-classpath 命令轻松浏览 classpath 上的项目.

这里你可以看到它的实际效果:

Classpath 浏览器

在 classpath 条目上按 RET 可以进入它.

你可以使用 M-x cider-browse-ns 命令浏览任何已加载命名空间的内容. CIDER 会提示你输入要浏览的命名空间.

命名空间浏览器

你也可以使用 M-x cider-browse-ns-all 浏览所有可用的命名空间.

UI 的标题栏中包含按钮, 允许你控制缓冲区的显示方式 (请参阅下面的键绑定). 你也可以配置 cider-browse-ns-default-filters 变量为一个列表, 列出你希望默认隐藏的元素类型.

在浏览器缓冲区中定义了一系列有用的键绑定.

如果你已经知道要查找哪个 spec, 你可以输入 M-x cider-browse-spec, CIDER 会提示你输入一个 spec 名称, 然后让你进入 spec 浏览器.

Spec 浏览器

如果你不太确定你想要哪个 spec, 你可以输入 M-x cider-browse-spec-all. CIDER 然后会提示你输入一个正则表达式, 并过滤掉所有不匹配的 spec 名称.

Spec 浏览器

一旦进入浏览器, 你可以使用鼠标或下面的键绑定进行更深入的导航.

如果你的项目包含 org.clojure/test.check 库, 你可以在浏览 spec 时输入 e 来生成一个符合该 spec 的示例.

Spec 浏览器示例

Clojure Spec 有点历史, 有几种风格:

• spec (又名 clojure.spec, 原始版本, 从未随 Clojure 发布)
• spec-alpha (又名 clojure.spec.alpha, 原始版本, 但名称不同, 随 Clojure 发布)
• spec-alpha-2 (又名 clojure.alpha.spec, 演进版, 独立库, 但仍处于实验阶段)

Cider 支持所有这些混合, 但有一个转折.

• 当 Cider 显示一个 specs 列表时, 会显示所有注册表的键. 注册表从最新到最旧合并.
• 当 Cider 对一个 spec 进行操作时, 比如查找一个 spec 或为其生成数据, 这个操作会按从最新到最旧的顺序在所有注册表上尝试, 第一个成功的操作获胜.

虽然 CIDER 有自己的代码格式化 (缩进) 引擎, 你也可以将它与 cljfmt 一起使用——这在你与使用不同编辑器和 IDE 的团队合作时很有用.

CIDER 提供了几个与 cljfmt 交互的命令:

• cider-format-defun
• cider-format-region
• cider-format-buffer

通常, 添加像这样的钩子是个好主意, 以确保每次保存操作时你的缓冲区都得到正确格式化:

(add-hook 'before-save-hook 'cider-format-buffer t t)

注意, 你需要在保存相关缓冲区之前应用 cljfmt.

你可以通过配置变量 cider-format-code-options 向 cljfmt 提供额外的配置. 这里有一个例子:

;; 假设你想传递以下配置
;;
;;   {:indents {org.me/foo [[:inner 0]]}
;;    :alias-map {\"me\" \"org.me\"}}
;;
;; 你需要将其编码为一个 Emacs Lisp plist:

(setq cider-format-code-options
      '(("indents" (("org.me/foo" (("inner" 0)))))
        ("alias-map" (("me" "org.me")))))

CIDER 不会调用 cljfmt 的 shell 命令——它通过 nREPL 与其交互 (在 cider-nrepl 中有格式化 middleware), 这比调用 shell 命令更快.

与 cljfmt 集成类似, CIDER 还提供了一个方便的接口, 使用 clojure.tools.reader.edn 来格式化 EDN. 提供了以下命令:

• cider-format-edn-defun
• cider-format-edn-region
• cider-format-edn-buffer

从 1.2.0 版本开始, CIDER 支持 Emacs 的内置 xref 功能, 这意味着 M-. 将调用 xref-find-definitions 而不是 CIDER 自己的命令 cider-find-var. 你可以像这样禁用 CIDER 的 xref 后端的使用:

(setq cider-use-xref nil)

你必须禁用并重新启用 cider-mode 才能使此设置生效.

如果你使用其他也与 xref 集成的包 (例如, lsp-mode), 你可能希望自定义 CIDER 的 xref 后端的优先级. 优先级由后端函数在 xref-backend-functions 钩子中出现的顺序控制. 默认情况下, CIDER xref 函数将以 -90 的深度添加, 因此它将 (应该?) 排在第一位. 如果你希望它的优先级较低, 你可以更改 cider-xref-fn-depth:

(setq cider-xref-fn-depth 90)

有关深度的更多信息, 请参见设置钩子.

在 CIDER 中有两种方式可以访问 Clojure cheatsheet.

第一种方式通过 cider-cheatsheet 命令可用, 它在一个弹出缓冲区中显示 cheatsheet. 下图是两个窗口并排显示 cheatsheet 缓冲区的样子:

在缓冲区中显示 cheatsheet

第二种方式通过 cider-cheatsheet-select 命令可用, 它在 minibuffer 中使用补全来在 cheatsheet 中查找一个 var. 默认情况下, 它提供一个多步选择过程, 你需要逐个部分地进行, 直到找到一个 var. 它在 minibuffer 中的样子如下:

在 cheatsheet 中选择部分

在 cheatsheet 中选择 var

在调用 cider-cheatsheet-select 时使用前缀参数, 我们可以改变 cider-cheatsheet-select 的行为, 使每个候选都表示为到 var 的完整路径. 这对于模糊补全样式和垂直候选显示很有用, 因为在这种情况下, 我们可以在路径的任何元素中搜索, 可能会同时得到多个类别的匹配. 这样的工作流程看起来如下:

在 cheatsheet 中选择路径

可以通过自定义 cider-cheatsheet-default-action-function 来控制在选择一个 var 时使用哪个函数. 默认情况下, var 的文档使用 cider-doc-lookup 显示, 但也可以设置为 cider-clojuredocs-lookup 来显示来自 ClojureDocs 的文档, 或任何其他接受 var 作为参数的函数.

与 CIDER 的 REPL 交互非常简单——大多数时候你只需在那里编写表达式并按 RET 来求值它们.

但 REPL 的功能远不止于此, 它允许你做一些在其他 Clojure REPL 中可能无法做到的事情. 这类事情的一些例子是:

• 你可以用 C-RET 关闭一个不完整的表达式
• 你可以通过在每行末尾按 C-j 来输入一个多行表达式
• 你可以快速跳转到一个符号的定义 (.) 或其文档 (C-c C-d d)
• 你可以用 C-c C-o 清除最后一个表达式的输出
• 你可以用 C-u C-c C-o 清除 REPL 缓冲区
• 你可以用 C-c C-z 在你的源缓冲区和 REPL 之间跳转
• 你可以用 C-c M-o 在你的 Clojure 和 ClojureScript REPL 之间跳转

除此之外, REPL 是极其可配置的, 你几乎可以调整它的每一个方面.

如果你不小心尝试求值一些需要很长时间 (如果它能完成的话) 的东西, 你可以通过按 C-c C-c 来中断这个失控的求值操作.

请注意, 这与在源缓冲区中中断求值的键绑定 C-c C-b 不同.

当你用完一个 REPL 后, 你可以用 C-c C-q 来处理它.

避免用 C-c C-k 杀死 REPL 缓冲区. 这会跳过一些正确处理 REPL 缓冲区所需的操作.

通常 Clojure REPL 会在你启动的第一个 REPL 中加载以下代码:

(clojure.core/apply clojure.core/require clojure.main/repl-requires)

CIDER 也这样做, 但更进一步, 实际上允许你通过变量 cider-repl-init-code 来控制在 REPL 初始化时求值什么代码.

此初始化代码仅在第一个 REPL 命名空间 (通常是 user) 中自动加载, 但你可以使用 REPL 快捷方式 require-repl-utils 在任何命名空间中轻松调用它. 该功能也可以通过 CIDER 的菜单 ("REPL → Require REPL utils") 访问.

在使用 CIDER 时, 你很少需要 REPL 实用函数, 因为它提供了许多行为类似的 Emacs 命令 (例如, 与其做像 (doc str) 这样的事情, 你可能更愿意使用 cider-doc (C-c C-d C-d) 命令).

当 REPL 缓冲区变得非常大时, 性能可能会下降. 如果启用了 cider-repl-use-clojure-font-lock 或 nrepl-log-messages, 情况尤其如此.

非常长的行肯定会使 Emacs 变得迟缓, 因此建议使用一个 cider-print-fn 的值, 该值会将超过一定宽度的行进行换行 (即除了 pr 之外的任何内置选项).

你可以使用 cider-repl-clear-output 来清除上一次求值的结果, 或者带前缀参数清除整个 REPL 缓冲区. 你还可以设置 cider-repl-buffer-size-limit, 这将在每次求值后自动修剪缓冲区. 这种修剪也可以通过 cider-repl-trim-buffer 手动调用.

这是 CIDER 的 REPL 中可用的键绑定列表:

无需记住此列表. 在任何 REPL 缓冲区中, 你都可以使用 REPL 菜单, 其中列出了最重要的命令及其键绑定. 你也可以调用 C-h f RET cider-repl-mode 来获取 cider-repl-mode 的键绑定列表.

在 REPL 中, 你还可以在 REPL 行的开头按 , 来使用“快捷命令”. 你将看到一个可以快速运行的命令列表 (如退出, 显示一些信息, 清除 REPL 等). 用于触发快捷方式的字符可通过 cider-repl-shortcut-dispatch-char 进行配置. 以下是如何将其更改为 ;:

(setq cider-repl-shortcut-dispatch-char ?\;)

通常, 当你第一次建立 REPL 连接时, REPL 缓冲区会自动在一个单独的窗口中显示. 你可以像这样抑制这种行为:

(setq cider-repl-pop-to-buffer-on-connect nil)

如果你希望 REPL 缓冲区自动显示, 但不希望它获得焦点, 请使用:

(setq cider-repl-pop-to-buffer-on-connect 'display-only)

默认情况下, C-c C-z 会在不同的窗口中显示 REPL 缓冲区. 你可以使 C-c C-z 在当前窗口中切换到 CIDER REPL 缓冲区:

(setq cider-repl-display-in-current-window t)

你可以通过将 cider-repl-prompt-function 设置为一个接受一个参数 (命名空间名称) 的函数来自定义 REPL 缓冲区提示符. 为方便起见, CIDER 提供了三个实现常见格式的函数:

• cider-repl-prompt-lastname:

ssl>

• cider-repl-prompt-abbreviated:

l.c.ssl>

• cider-repl-prompt-default:

leiningen.core.ssl>

默认情况下, CIDER 使用 cider-repl-prompt-default.

当然, 你可以编写自己的函数. 例如, 在 leiningen 中有两个名称相似的命名空间 - leiningen.classpath 和 leiningen.core.classpath. 为了让它们易于识别, 你可以使用默认值, 或者你可以选择只显示命名空间的两个部分, 并且仍然能够知道哪个是 REPL 的当前命名空间. 这里是一个可以做到这一点的示例函数:

(defun cider-repl-prompt-show-two (namespace)
  "Return a prompt string with the last 2 segments of NAMESPACE."
  (let ((names (reverse (subseq (reverse (split-string namespace "\\.")) 0 2))))
    (concat (car names) "." (cadr names) "> ")))

你可以使用 cider-repl-tab-command 变量来控制 REPL 中 TAB 键的行为. 虽然默认的命令 cider-repl-indent-and-complete-symbol 对大多数用户来说应该是一个足够的选择, 但如果你希望, 切换到另一个命令也非常容易. 例如, 如果你希望 TAB 只进行缩进 (也许因为你习惯于用 M-TAB 进行补全), 请使用以下设置:

(setq cider-repl-tab-command #'indent-for-tab-command)

通常, Return 会立即发送一个 form 进行求值. 如果你在编辑时想在 REPL 缓冲区中插入一个换行符, 你可以使用 C-j. 如果你输入很多跨越多行的较长的 forms, 更改键绑定可能会更方便:

(define-key cider-repl-mode-map (kbd "RET") #'cider-repl-newline-and-indent)
(define-key cider-repl-mode-map (kbd "C-<return>") #'cider-repl-return)

这将使 Return 在 REPL 缓冲区中插入一个换行符, 而 C-Return 则发送 form 进行求值.

在 0.21.0 版本之前, 每当有任何输出被打印时, REPL 缓冲区都会自动重新居中, 以便提示符位于窗口的底行, 从而在其上方显示尽可能多的输出. 这不再是默认行为——你现在可以通过设置内置选项 scroll-conservatively 来复制它, 例如:

(add-hook 'cider-repl-mode-hook '(lambda () (setq scroll-conservatively 101)))

如果你的 REPL 提示符位于 REPL 窗口的开头 (例如, 你按了几次 C-l 来重新居中你的 REPL 窗口), 并且在 Clojure 缓冲区中的交互式求值中有一些输出显示在那里, 这个输出不会自动滚动到视图中. 如果你想强制显示这样的输出, 你需要在你的配置中添加以下内容:

(setq cider-repl-display-output-before-window-boundaries t)

这个行为在 CIDER 1.7 中被改变了, 因为在 REPL 提示符前自动滚动输出很少需要, 但它当前的实现非常慢.

此功能默认是禁用的.

如前所述, 如果允许 REPL 缓冲区的大小无限增长, 其性能将会下降. 你显然可以不时地手动清除 REPL, 但 CIDER 也有一些自动修剪功能, 可以为你简化这个过程.

通过将 cider-repl-buffer-size-limit 设置为一个整数, 可以启用自动修剪. 通过设置缓冲区中的字符数限制, 如果超过了设定的限制, 缓冲区可以在每次求值后 (从其开头) 被修剪. 以下是如何在你的 Emacs 配置中设置大小限制:

(setq cider-repl-buffer-size-limit 100000)

你也可以通过调用命令 cider-repl-trim-buffer 或 REPL 快捷方式 trim 来手动触发自动修剪.

你可以更改用于前缀 REPL 结果的字符串:

(setq cider-repl-result-prefix ";; => ")

这将导致以下 REPL 输出:

user> (+ 1 2)
;; => 3

默认情况下, REPL 结果没有前缀.

默认情况下, cider-repl-set-ns 不会 require 目标 ns, 只是设置它. 这是基于这样的假设: 你可能在切换到目标 ns 之前已经求值了它 (例如, 在其源缓冲区中执行 C-c C-k (cider-load-buffer)). 如果你想改变这种行为 (以避免手动调用 cider-repl-set-ns 然后再调用 (require 'my-ns)), 你可以设置:

(setq cider-repl-require-ns-on-set t)

通常, CIDER REPL 会在 user 命名空间中启动. 你可以在你的 Leiningen 项目配置的 repl-options 部分为 REPL 会话提供一个初始命名空间:

:repl-options {:init-ns 'my-ns}

你可以使用变量 cider-session-name-template 来自定义缓冲区名称. 详情请参见该变量的文档.

通常, REPL 中的代码会像在 clojure-mode 中一样被 font-locked. 在 CIDER 0.10 之前, 默认情况下, REPL 输入会用 cider-repl-input-face 进行 font-locked (在按 Return 之后), 结果会用 cider-repl-result-face 进行 font-locked. 如果你想恢复旧的行为, 请使用:

(setq cider-repl-use-clojure-font-lock nil)

你可以使用 M-x cider-repl-toggle-clojure-font-lock 或 REPL 快捷方式 toggle-font-lock 来临时禁用 Clojure font-locking.

请记住, 默认情况下 cider-repl-input-face 只是将输入加粗, 而 cider-repl-result-face 是空白的 (意味着它实际上没有对结果应用任何 font-locking), 所以你可能想根据你的偏好调整这些 faces. 一些 Emacs 颜色主题可能会为它们提供不同的默认值.

在 REPL 中使用 Clojure font-locking 可能会对性能产生负面影响, 特别是对于 font-locking 巨大的结果. 然而, 这在很大程度上被结果流所缓解.

关于结果的 Clojure font-locking, 你需要记住几件事:

• 当启用流时, 只有单块的结果会被作为 Clojure 进行 font-locked, 因为每个块都是独立进行 font-locked 的, 结果无法真正合并
• 结果的 font-locking 是一个昂贵的操作, 它涉及将值复制到一个临时缓冲区, 在那里我们检查其完整性并进行实际的 font-locking.

默认情况下, CIDER 指示 nREPL 以 4K 的块进行数据流传输, 但你可以轻松修改这个设置:

;; 让我们以 8K 的块进行数据流传输
(setq cider-print-buffer-size (8 * 1024))

将其设置为 nil 将导致使用 nREPL 的默认缓冲区大小 1024 字节. 打印缓冲区越小, 你在 REPL 中得到的反馈/更新就越快, 所以通常坚持使用相对较小的大小是个好主意.

如果你想了解更多关于结果的 font-locking, 你可以查看 cider-util.el 中 clojure-font-lock-as 和 clojure-font-lock-as-clojure 的定义.

默认情况下, REPL 总是使用 cider-print-fn 指定的打印函数来打印你的求值结果.

这个行为在 CIDER 0.20 中被改变了. 在之前的 CIDER 版本中, 漂亮打印默认是禁用的.

你可以使用 M-x cider-repl-toggle-pretty-printing 或 REPL 快捷方式 toggle-pprint 来临时禁用此行为, 并恢复到默认行为 (等同于 clojure.core/pr).

如果你想完全禁用 cider-print-fn 的使用, 请使用:

(setq cider-repl-use-pretty-printing nil)

请注意, 不建议禁用漂亮打印. Emacs 处理非常长的行效果不佳, 因此使用一个能将超过一定宽度的行进行换行的打印函数 (即除了 pr 之外的任何函数) 将使你的 REPL 运行顺畅.

有关配置打印的更多信息, 请参阅本文档的这一部分.

从 CIDER 0.17 (Andalucía) 开始, 求值为图像的表达式可以在 REPL 中呈现为图像. 你可以像这样启用此行为:

(setq cider-repl-use-content-types t)

这个设置在 CIDER 0.25 之前是默认启用的, 后来由于该功能的一些粗糙边缘从未得到妥善解决而被禁用. 详情请参见这个 bug 报告.

或者, 你可以使用 M-x cider-repl-toggle-content-types 或 REPL 快捷方式 toggle-content-types 来切换此行为.

通常 CIDER 会根据从 cider-nrepl 的一部分 track-state middleware 收到的信息, 自动检测 REPL 的类型 (Clojure 或 ClojureScript).

在一些罕见的情况下 (例如, cider-nrepl 或 shadow-cljs 中的一个 bug), 这种自动检测可能会失败并返回错误的类型 (例如, Clojure 而不是 ClojureScript). 你可以像这样禁用自动检测逻辑:

(setq cider-repl-auto-detect-type nil)

之后, 你可以使用 cider-repl-set-type 来手动设置正确的类型.

在不禁用 cider-repl-auto-detect-type 的情况下使用 cider-repl-set-type 不会有太大作用, 因为 REPL 类型会不断地被 track-state middleware 自动重置.

• 要让 REPL 历史在 CIDER 到达末尾时循环:

(setq cider-repl-wrap-history t)

• 要调整 REPL 历史中保留的最大项目数:

(setq cider-repl-history-size 1000) ; 默认是 500

• 要将所有项目的 REPL 历史存储在单个文件中:

(setq cider-repl-history-file "path/to/file")

• 要按项目存储 REPL 历史 (通过在每个项目的根目录下创建一个 .cider-history 文件):

(setq cider-repl-history-file 'per-project)

请注意, CIDER 会在你杀死 REPL 缓冲区时 (包括调用 cider-quit) 或退出 Emacs 时将历史记录写入文件.

你可以使用 M-x cider-repl-history 命令浏览你的 REPL 输入历史. 这个命令在 cider-repl-mode 缓冲区中绑定到 C-c M-p, 也可以通过 history 快捷方式使用.

历史记录以相反的顺序列出, 最新的输入在缓冲区的顶部, 最旧的输入在底部. 你可以滚动历史记录, 当你找到你想要的历史项目时, 你可以从历史缓冲区将其插入到你的 REPL 缓冲区中.

历史浏览器

历史缓冲区有自己的主模式, cider-repl-history-mode. 它派生自 clojure-mode, 所以你在历史缓冲区中可以得到字体化. 这个模式支持预期的 defcustom 钩子变量, cider-repl-history-hook.

当你使用历史缓冲区向 REPL 缓冲区插入文本时, 确切的行为取决于插入前缓冲区中光标的位置.

通常, 当你积极使用 REPL 时, 你的光标会位于 REPL 缓冲区的末尾 (point-max). 在这种情况下, 文本被插入到缓冲区的末尾, 并且点会前进到插入文本的末尾 (就好像点被文本推着前进一样).

在不寻常的情况下, 当你调用历史浏览器时, 你的光标不在 REPL 缓冲区的末尾, 插入的文本仍将被插入到缓冲区的末尾 (point-max), 但点不会被修改.

CIDER 插入的文本没有最后的换行符, 允许你编辑它. 当你准备好后, 按 Return 键, 让它被 REPL 求值.

如果你选择一个输入, 文本将被插入到 REPL 缓冲区中, 并且历史缓冲区将自动退出. 如果你决定不插入任何文本就退出, 你可以运行 cider-repl-history-quit (参见键盘快捷键) 显式退出. 因为在使用历史缓冲区时会进行初始化和清理, 所以正确退出比仅仅切换离开历史缓冲区要好.

当你退出历史缓冲区时, CIDER 可以用几种不同的方式恢复缓冲区和窗口配置. 该行为由 cider-repl-history-quit-action 控制, 它可以被赋予几个值之一:

• quit-window 恢复窗口配置到之前的状态. 这是默认值.
• delete-and-restore 恢复窗口配置到之前的状态, 并杀死 *cider-repl-history* 缓冲区.
• kill-and-delete-window 杀死 *cider-repl-history* 缓冲区, 并删除窗口.
• bury-buffer 只是埋藏 *cider-repl-history* 缓冲区, 但保留窗口.
• bury-and-delete-window 埋藏缓冲区, 如果有多个窗口, 则删除窗口.
• 任何其他值都被解释为要调用的函数的名称.

通过从历史缓冲区调用 cider-repl-history-occur, 你将被提示输入一个正则表达式. 历史缓冲区将被过滤, 只显示那些匹配该正则表达式的输入.

当 cider-repl-history-show-preview 不为 nil 时, CIDER 会在 REPL 缓冲区中显示当前选定的历史条目的 overlay.

如果你没有正确地从浏览历史中退出 (即, 如果你只是 C-x b 离开缓冲区), 你可能会在你的 REPL 缓冲区中留下一个不想要的 overlay. 如果发生这种情况, 你可以用 M-x cider-repl-history-clear-preview 清理它.

默认情况下, cider-repl-history-show-preview 为 nil (禁用).

有一个相关的功能是在条目实际插入到 REPL 缓冲区后高亮显示它, 由变量 cider-repl-history-highlight-inserted-item 控制, 它可以设置为以下值:

• solid 在固定时间内高亮插入的文本.
• pulse 使高亮逐渐淡出.
• t 选择默认的高亮样式, 目前是 pulse.
• nil 禁用高亮. 这是 cider-repl-history-highlight-inserted-item 的默认值.

当 cider-repl-history-highlight-inserted-item 不为 nil 时, 你可以使用变量 cider-repl-history-inserted-item-face 自定义插入文本的 face.

除了已经提到的, 还有相当多的自定义可用.

• cider-repl-history-display-duplicates - 当设置为 nil 时, 将不会在历史缓冲区中显示任何重复的条目. 默认是 t.
• cider-repl-history-display-duplicate-highest - 当不显示重复项时, 这控制了重复文本的一个实例在历史中的显示位置. 当为 t 时, 它在适用的最高位置显示条目; 当为 nil 时, 它在最低位置显示.
• cider-repl-history-display-style - 历史条目通常会超过一行. 该包为你提供了两种显示条目的选项:
  • separated - 在条目之间插入一个分隔符字符串; 条目可能跨越多行. 这是默认值.
  • one-line - 任何换行符都被替换为字面上的 \n 字符串, 因此不需要分隔符. 当文本插入到 REPL 中时, 每个 \n 都变成一个真正的换行符.
• cider-repl-history-separator - 当 cider-repl-history-display-style 为 separated 时, 这给出了用作分隔符的文本. 默认是一系列十个分号, 这当然是 Clojure 中的注释. 分隔符可以是任何东西, 但如果你把它设置成奇怪的东西, 可能会搞乱字体化.
• cider-repl-history-separator-face - 指定分隔符的 face.
• cider-repl-history-maximum-display-length - 当为 nil (默认) 时, 所有历史项目都完整显示. 如果你希望长项目被缩写, 你可以将此变量设置为一个整数, 每个项目将被限制为该字符数. (此变量不影响显示的项目数, 只影响每个项目的最大长度.)
• cider-repl-history-recenter - 当不为 nil 时, 总是将当前条目保持在历史窗口的顶部. 默认是 nil.
• cider-repl-history-resize-window - 是否调整历史窗口以适应其内容. 值可以是 t, 表示是, 或者是一个整数的 cons 对, (MAXIMUM . MINIMUM) 用于窗口的大小. MAXIMUM 默认为 pop-to-buffer 选择的窗口大小; MINIMUM 默认为 window-min-height.
• cider-repl-history-highlight-current-entry - 如果不为 nil, 则高亮历史缓冲区中当前选定的条目. 默认是 nil.
• cider-repl-history-current-entry-face - 指定历史条目高亮的 face.
• cider-repl-history-text-properties - 当设置为 t 时, 维护条目上的 Emacs 文本属性. 默认是 nil.

在历史缓冲区中有许多重要的键绑定.

CIDER 有几个函数可以运行所有测试或它们的选定子集. 所有的 CIDER 测试命令在源代码和 REPL 缓冲区中都可用. 在 REPL 缓冲区中, 也可以使用 , 来调用一些测试命令.

CIDER 只会运行已经加载 (求值) 的测试. 这意味着在运行某些测试之前, 你总是需要先求值它们.

相应地, 如果你对测试做了一些更改, 你需要重新求值它, 以便 CIDER 能够获取更新后的版本.

首先, 你可以用 C-c C-t p 或 C-c C-t C-p 运行项目中的所有测试. 需要注意的是, 这会加载你项目中的所有命名空间, 这可能比你预期的要多.

你可以用 C-c C-t l 或 C-c C-t C-l 运行所有已加载的测试.

如果你用一个前缀 (例如 C-u C-c C-t l) 调用这些命令中的任何一个, CIDER 将会提示测试选择器过滤器, 并只运行那些匹配选择器包含/排除的测试.

测试开发者使用选择器来定义整个测试套件的子集, 这些子集会针对不同的测试任务一起运行.

例如可以用 ^:smoke 元数据标记来标记一些测试, 用 ^:integration 标记其他. 能够在构建管道中分别运行这些测试. CIDER 帮助你在你的开发环境中运行这些相同的测试子集.

测试选择器最初是 leiningen 的一个功能, 你可以通过执行以下命令获取更多信息:

$ lein help test

使用 C-c C-t n 或 C-c C-t C-n 运行当前命名空间中的所有测试, 无论是由源文件还是由 REPL 指定.

注意, Clojure 项目的惯例是将测试放在与被测试代码不同的命名空间中. CIDER 使用一个简单的算法来确定测试的位置. 该算法工作如下:

• 在一个实现命名空间中 (例如 some.ns), CIDER 将尝试找到一个匹配的测试命名空间 (默认为 some.ns-test) 并在那里运行测试.
• 如果在一个看起来像测试命名空间的地方 (例如 some.ns-test), CIDER 将简单地在该命名空间中运行测试.

如果已经将一些测试放在了实现命名空间中, 例如使用 clojure.test/with-test, 要抑制命名空间推断逻辑, 并强制 CIDER 无条件地在当前命名空间中运行测试.

可以通过给命名空间命令添加一个前缀来实现这一点: C-u C-c C-t C-n. 这将简单地运行当前访问或活动的命名空间中存在的任何测试.

也可以使用 C-c C-t C-s 运行命名空间中定义的测试子集, 按测试选择器过滤. CIDER 会在 minibuffer 中提示选择器.

如果用一个前缀 (C-u C-c C-t C-s) 调用这个命令, 可以像对 C-u C-c C-t C-n 一样抑制命名空间推断逻辑.

最后, 可以使用 C-c C-t t 或 C-c C-t C-t 执行点处的特定测试. 它也适用于实现函数, 通过搜索一个匹配的测试命名空间和一个匹配的 deftest 名称.

可以通过多种方式配置 CIDER 的测试执行行为.

CIDER 提供了一个 minor-mode, 每当加载一个文件 (用 C-c C-k) 时, 都会自动运行该命名空间的所有测试. 可以用 M-x cider-auto-test-mode 手动切换它, 或者可以使用:

(cider-auto-test-mode 1)

这与每次加载 Clojure 缓冲区时手动输入 C-c C-t C-n 是相同的. 如前所述, CIDER 会尝试自动确定包含测试的命名空间.

如果测试失败, CIDER 会在 *cider-test-report* 缓冲区中显示一个测试结果报告.

这个缓冲区使用 cider-test-report-mode, 这使得审查可能发生的任何失败并直接跳转到失败测试的定义变得容易.

再次调用测试命令将会更新测试报告.

也可以配置测试报告在成功时显示.

大多数键绑定在 cider-test-report-mode-map 中定义, 而点击行为在 cider-test-var-keymap 中定义.

clojure.test 机制被设计为可插拔的. 任何测试库都可以与之集成并利用 cider-test 生态系统.

作为测试框架的作者, 支持内置的 clojure.test 机制 (因此也支持 cider-test) 非常直接:

1. 向与测试函数对应的 vars 添加 :test 元数据. clojure-test 机制使用此元数据来查找测试.
2. 实现 clojure.test/report multimethod 来捕获测试结果.

例如, test.check 是独立于 clojure.test 设计的, 但与之集成. 因此, cider-test 处理 defspec 的方式就像处理 deftest 一样.

test.check 只是在这个命名空间中添加了兼容性.

• test.check
• clojure-expectations 在 2.2 版本中添加了对 clojure.test 的支持, 应该也能与 CIDER 一起工作.
• fudje

Emidje 是一个第三方扩展, 不与 CIDER 捆绑.

Emidje 是 Emacs 内 Midje 的一个测试运行器, 报告查看器和格式化工具.

Emidje 扩展了 CIDER 以提供对 Midje 测试的支持, 其方式与 cider-test.el 对 clojure.test 测试的支持类似. 事实上, Emidje 的大多数功能都受到了 cider-test.el 功能的强烈启发.

在正常的 CIDER 开发过程中, 程序员通常会通过输入 C-M-x (cider-eval-defun-at-point) 来求值一个 form, 通常是一个函数定义.

当为求值命令添加一个前缀时, CIDER 也可以为一个 form 进行调试插桩: C-u C-M-x. 在插桩过程中, CIDER 会在 form 中插入尽可能多的断点.

每当执行到达一个断点时, CIDER 会进入调试模式并提示下一步该怎么做. 可以通过正常地再次求值该 form, 使用 C-M-x 来移除插桩.

也可以通过在任何代码中放置 #break 来手动插入一个断点, 放在希望断点触发的 form 前面, 然后用 C-M-x 求值该 form. 当执行到达 #break 后的 form 时, 将被带入调试器.

例如, 如果对下面的代码执行 C-M-x, 每次求值 (inspector msg) 时都会触发一个断点.

(defn eval-msg [{:keys [inspect] :as msg}]
  (if inspect
    #break (inspector msg)
    msg))

除了 #break, 也可以在 form 前面写 #dbg. 这将在 form 的前面放置一个断点, 就像 #break 一样, 并且也会在它内部的所有地方放置断点.

在上面的例子中, 这会在 (inspector msg) 周围放置一个断点, 并在 msg 周围放置另一个断点.

事实上, 输入 C-u C-M-x 来插桩一个顶层 form 只是一种方便的方式, 用一个隐含的 #dbg 来求值该 form; 行为是相同的.

在任何时候, 都可以使用 M-x cider-browse-instrumented-defs 命令来调出所有当前已插桩的 defs 的列表. 协议和类型也可以被插桩, 但它们不会被此命令列出.

在 CIDER 调试器中, "断点" 这个术语指的是调试器可以暂停执行并显示表达式值的地方.

可以用 #break 设置单个断点, 或者用 #dbg (或通过用 C-u C-M-x 求值) 在整个 form 中设置断点, 如前所述.

当使用 #dbg 或 C-u C-M-x 时, 并非每个 form 都会被断点包装. 调试器会尽量避免在不感兴趣的表达式上设置断点.

例如, 在代码中一个字面量数字 23 处停止执行并求值得到 23 完全没有意义.

一旦进入 CIDER 调试器, 有许多命令可用来单步执行代码, 求值其他 forms, 检查值, 注入新值, 或查看当前堆栈.

cider-debug 试图与 Edebug 命令键保持一致, 尽管有一些差异.

此外, 所有通常的求值命令, 如 C-x C-e 或 C-c M-: 在调试器激活时都将被限定在当前的词法上下文中, 允许访问局部变量.

这些命令会继续执行直到到达一个断点.

• next: 步进到下一个断点
• in: 步进到即将被调用的函数中. 如果下一个断点不在一个函数调用周围, 行为与 next 相同. 请注意, 并非所有函数都可以步入——只有存储在 vars 中的普通函数, CIDER 可以为其找到源代码. 你目前无法步入多方法(multimethod), 协议函数(protocol function), 或 clojure.core 中的函数 (尽管多方法和协议可以手动插桩).
• out: 步进到当前 sexp 之外的下一个断点.
• Out: 与 o 相同, 但跳过其他函数中的断点. 也就是说, 如果被跳过的代码包含对另一个插桩函数的调用, 如果你用 o 步出, 调试器会停在该函数中, 但如果你用 O 步出则不会.
• here: 将光标放在被调试函数中更远的地方, 在你想要下次停止的地方. 然后按 h, 调试器会跳过所有断点直到那个位置.
• Here: 与 h 相同, 但像 O 一样跳过其他函数中的断点.
• continue: 在当前断点不停止继续.
• continue-all: 不停止地继续, 跳过所有断点.

• eval: 提示输入一个 clojure 表达式, 它可以引用在调试器停止处作用域内的局部变量. 结果显示在一个 overlay 中.
• inspect: 在一个 cider-inspector 缓冲区中检查当前求值的值.
• inspect-prompt: 像 eval, 但在一个 cider-inspector 缓冲区中显示值.
• locals: 打开一个 cider-inspector 缓冲区, 显示在调试器停止的上下文中定义的所有局部变量.
• inject: 用你输入的表达式的值替换当前显示的值. 后续代码将看到你输入的新值.
• stacktrace: 显示调试器停止点的堆栈跟踪.
• trace: 继续执行, 但在每个断点处, 不是停止并在 overlay 中显示值, 而是将 form 及其值打印到 REPL.
• quit: 立即退出执行. 与 continue 不同, 被调试函数中的其余代码不会被执行.

断点可以是条件性的, 这样调试器只会在条件为真时停止.

条件使用附加到 form 的 :break/when 元数据指定.

(dotimes [i 10]
  #dbg ^{:break/when (= i 7)}
  (prn i))

用 C-M-x 求值上述代码, 调试器只会停止一次, 当 i 等于 7 时.

可以让 CIDER 将断点条件插入到代码中. 将光标放在希望条件所在的位置, 然后用 C-u C-u C-M-x 或 C-u C-u C-c C-c 求值.

CIDER 然后会在 minibuffer 中提示你输入条件, 并在你的代码中插入适当的 #dbg 加上元数据注解. 请注意, 需要手动删除这个注解;

不能像取消插桩 C-u C-M-x 那样简单地使用 C-M-x.

由于调试器目前的实现方式, 在处理某些 forms 时存在一些限制. 集合字面量目前完全不被插桩.

映射字面量目前只有在它们很小或者键有某种自然顺序时才被插桩. 例如, 以下表达式不会被插桩.

#dbg (count {:foo 2 :bar (inc 4) "foo" 6 "bar" 8 9
             10 11 12 13 14 15 (inc 16) 17 (inc 18)})

调试器目前受限的另一个构造是 loop/recur. 由于 recur 总是必须出现在 loop 或 fn 内部的尾部位置, 而调试器使用宏在 forms 中插入断点, 可能会发生 recur 不再出现在尾部位置的情况. 在这种情况下, 我们必须避免设置断点. 这种情况的一个例子是:

(loop [i 0]
  #break
  (when (< i 10)
    (println i)
    (recur (inc i))))

这里的断点恰好在一个 form 的前面, 该 form 的最后一个表达式是一个 recur, 它没有被包裹在一个 loop 中.

目前这个断点没有效果. 这并不意味着不能在 loop 中使用调试器, 只是意味着必须更小心地设置调试语句.

本节解释了调试器的一些内部工作原理. 它旨在帮助那些有兴趣贡献的人, 并且不教授任何关于调试器用法的内容.

CIDER 在插桩代码时分几个步骤工作:

1. CIDER 遍历代码, 向 forms 和符号添加元数据, 以识别它们在代码中的位置 (坐标).
2. 它对所有东西进行宏展开以去除宏.
3. 它再次遍历代码, 对其进行插桩.
   • CIDER 理解所有现有的special forms, 并注意不在不应该插桩的地方插桩. 例如, CIDER 不会插桩 fn* 的参数列表或 let 绑定的左侧.
   • 无论在哪里找到先前注入的元数据, 假设该位置对于插桩是有效的, 它都会用一个名为 breakpoint-if-interesting 的宏来包装该 form 或符号.
4. 当结果代码实际被编译时, Clojure 编译器将展开 breakpoint-if-interesting 宏. 这个宏决定了 form 或符号的返回值是否是用户可能想看到的东西. 如果是, form 或符号就会被一个 breakpoint 宏包装, 否则就原样返回.
5. breakpoint 宏获取在第 1 步中提供的坐标信息, 并将其发送到 Emacs (前端). 它还发送 form 的返回值和一个可用命令的提示. Emacs 然后使用这些信息来显示实际代码 forms 的值, 并提示下一个操作.

一些返回值不有趣的示例 forms (因此不会被断点包装):

• 在 (fn [x] (inc x)) 中, 返回值是一个函数对象, 不携带任何信息. 请注意, 这与你调用此函数时的返回值不同 (那是有趣的). 此外, 即使这个 form 没有被断点包装, 它内部的 forms 也会被包装 ((inc x) 和 x).
• 类似地, 在像 (map inc (range 10)) 这样的 form 中, 符号 inc 指向 clojure.core 中的一个函数. 这也是无关紧要的 (除非它被一个局部变量遮蔽, 但调试器可以识别出这一点).

在源缓冲区或 REPL 中, 在某个 form 之后输入 C-c M-i (cider-inspect) 会在一个新缓冲区中向你显示该 form 结果的结构. 你也可以使用 C-u C-c M-i 来检查当前顶层 form 的结果, 以及 C-u C-u C-c M-i 从 minibuffer 读取一个表达式并检查其结果.

或者, 在一个常规的 eval 命令之后, 你可以使用 cider-inspect-last-result 来检查最后求值的值. 当一个检查器缓冲区在后台可见时, 它会自动更新为最后的结果. 这个行为可以通过变量 cider-auto-inspect-after-eval 来控制.

检查器也可以在调试会话中途调用, 更多详情请看这里.

调试器的当前值也可以发送到 Clojure 的 tap> 设施. 这可以用来将 CIDER 与各种在 web 浏览器中渲染 tapped 值的外部工具集成, 例如.

你将在检查器缓冲区 (内部使用 cider-inspector-mode) 中拥有额外的键绑定:

默认情况下, 导航会跳过像 nils, 数字和关键字这样不值得检查的值. 你可以使用变量 cider-inspector-skip-uninteresting 来控制这种行为.

检查器缓冲区默认是自动选中的. 你可以使用变量 cider-inspector-auto-select-buffer 来禁用自动选中.

你可以使用变量 cider-inspector-page-size, cider-inspector-max-coll-size, cider-inspector-max-nested-depth, 和 cider-inspector-max-atom-length 来设置默认显示的数据量. 这些值可以通过上表中的键绑定为当前检查器缓冲区进行调整.

如果启用 cider-inspector-fill-frame, 检查器窗口将填满其框架.

你可以使用 P 切换检查器中值的漂亮打印, 并通过调整 cider-inspector-pretty-print 自定义选项来定制它们的初始表示.

当你使用 d 定义一个 var 时, 可以建议一个 var 名称 (默认为无). 你可以通过 cider-inspector-preferred-var-names 配置选项来自定义这个值. 即使设置了它, 你在输入时仍然可以自由选择新的名称. 最近的名称将在后续使用中优先.

当 cider-inspector-tidy-qualified-keywords 启用时, 如果在相同命名空间的代码缓冲区中调用检查器或 require 了相应的别名, 命名空间限定的关键字如 ::foo 或 ::alias/baz 将以相同的方式显示.

• 在 Spacemacs 中使用 CIDER 的 Inspector

• 浏览给定日志框架的 Javadocs 和网站.
• 搜索日志事件并在缓冲区中显示它们.
• 漂亮打印日志事件.
• 在 CIDER Inspector 中显示日志事件.
• 与 logview 集成.

Logview 是 CIDER Log Mode 的一个可选依赖. 我们推荐使用它, 因为它负责为日志事件上色, 并提供其他有用的功能, 如语法高亮, 过滤等. 当可用时, 它会自动使用, 其使用可以通过 cider-log-use-logview 进行自定义.

值得指出的是, Cider Log Mode 的大多数功能和工作流程都基于 transient-mode.

一个 transient 菜单是以下的小部件:

CIDER Log transient 菜单

它的用法大多是自解释的, 因为每个命令都有其键绑定附加在描述上.

要使用 CIDER Log Mode, 有两种主要的方式开始:

• M-x cider-log-show-frameworks, 查看可用的日志框架. 如果你的日志框架受支持但未显示, 请参见故障排除部分.
• M-x cider-log-event, 使用 transient-mode, 不会立即显示日志 (你应该使用 transient-mode 来显示 *cider-log* 缓冲区)
• M-x cider-log-show 是一个较新的函数, 旨在成为一个“一体化”命令, 用于简化的体验, 这对于入门或临时使用可能很有用.
  • 它不使用 transient-mode - 它旨在一步完成所有事情

  • 它会立即显示 *cider-log* 缓冲区

    这些命令中的任何一个只有在附加了 CIDER repl (Sesman 会话) 的缓冲区中才会成功.

cider-log 是一个既可以用于从头开始设置日志记录, 也可以用于调整现有设置 (例如为 consumer 添加过滤) 的函数.

它被认为是一种较低级的方法.

CIDER Log Mode 支持在运行时重新配置的日志框架. 更具体地说, 框架应支持将日志 appenders 附加到 loggers, 以捕获事件.

目前支持以下日志框架:

• Java Util Logging
• Logback

• Timbre

  如果你选择 Timbre, 请确保你的项目版本大致与 Logjam 的预期版本相匹配 - 否则不兼容的更改可能会使 Timbre 无法作为 CIDER Log Mode 框架选项出现.

支持 Log4j 的工作正在进行中, 但在运行时进行的配置更改存在一些困难, 这些更改会被 Log4j2 的重新配置机制清除掉.

如果你选择的日志框架目前不受 CIDER Log Mode 支持, 你可以选择在你的项目中使用 Clojure 官方的 tools.logging façade, 这样你就可以在本地, 不引人注目地告诉它使用一个受支持的框架 (如 Logback) 来代替你项目的默认框架. 请注意, 其日志后端实现的选择可以通过 -Dclojure.tools.logging.factory Java 系统属性来控制, 这可以在本地通过 Lein profiles 或 Clojure CLI 别名干净地进行自定义.

为了捕获日志事件, 需要将一个日志 appender 附加到框架的 logger 上. 一旦一个 appender 附加到一个 logger 上, 它就会在一个内存中的 atom 中捕获框架发出的日志事件. 一个日志 appender 可以配置为具有一定的大小 (默认: 100000) 和一个百分比阈值 (默认: 10). 当达到阈值 (appender 大小加阈值) 时, 日志事件会从 appender 中清除. 此外, appender 还可以配置为只捕获匹配一组过滤器的事件.

通过将日志 consumer 附加到 appender, 可以将日志事件流式传输到客户端. 一旦日志 consumer 附加到 appender, 它将从 appender 接收事件. 与日志 appenders 类似, consumers 也可以配置一组过滤器以仅接收某些事件.