clj-replace

clj-replace：结构化 Clojure 代码替换

一款支持 Clojure 的代码替换工具。它通过比较代码结构（S 表达式）而非字面文本，改进了 Claude Code 内置的 str_replace。

适用场景

以下情况请使用 /clj-replace：

• Claude Code 的 str_replace 失败，因为 old_string 与目标代码的格式（空白、缩进、换行）不同
• 你需要替换代码，但空白或格式与源代码不完全一致
• 你希望替换后的代码保留原文件的格式和风格

示例： 如果 str_replace 提示“old_string not found”，但代码结构看起来相同，请改用 clj-replace。

工作原理

clj-replace 不会逐字符比较文本，而是进行结构化比较：

1. 将 old-string 和文件内容解析为 S 表达式树（zipper）
2. 遍历文件，将每个节点的结构与目标进行比较（对 sexpr 使用 =）
3. 比较时会忽略格式差异（空格、缩进、换行）
4. 找到匹配项后，替换该节点，同时保留原文件的格式

这意味着以下内容都等价：

(foo bar)          ≡ (foo  bar)        ≡ (foo
                                           bar)

参数

位置参数：

1. filename — 要修改的 Clojure 源文件路径
2. old-string — 要查找的代码片段（字符串）
3. new-string — 用于替换的代码片段（字符串）

用法

/clj-replace path/to/file.clj "old code here" "new code here"

示例

示例 1：空白差异

文件内容：

(defn update-user
  [db id attrs]
  (merge-user db id attrs))

命令：

/clj-replace src/app.clj "(merge-user db id attrs)" "(update-user-in-db db id attrs)"

即使文件的缩进不同也能正常工作。它会替换匹配的完整形式，同时保留文件风格。

示例 2：多行形式

文件内容：

(some-function
  arg1
  arg2
  arg3)

命令：

/clj-replace src/app.clj "(some-function arg1 arg2 arg3)" "(other-function arg1 arg2 arg3)"

无论原始内容如何跨行格式化，都能匹配。

退出代码

• 0 — 成功：替换了一个或多个节点
• 1 — 错误：文件不存在，或 old-string/new-string 不是有效的 Clojure
• 2 — 错误：在文件中找不到匹配的 S 表达式
• 3 — 错误：找到多个匹配的 S 表达式（存在歧义）；用户必须提供更具体的 old-string

输出

成功时：

✓ Replaced 1 node(s) in path/to/file.clj
  Location: line 42, column 5
  Old: (merge-user db id attrs)
  New: (update-user-in-db db id attrs)

存在多个匹配项时：

✗ Found 3 matching S-expressions in path/to/file.clj (ambiguous)
  1. line 42, column 5: (foo bar)
  2. line 85, column 10: (foo bar)
  3. line 120, column 1: (foo bar)
Please provide a more specific old-string (e.g., include surrounding context)

实现细节

使用 rewrite-clj 库实现：

• 保留格式的解析和修改
• S 表达式的结构化比较
• 安全地替换节点，同时保留空白和风格

该工具遵循 Clojure 的语义：如果两个表达式解析后具有相同结构，则它们等价，无论表面格式如何。