Fennel neovim开发配置

这些故事并非仅仅是巧合; 它们可以被看作是对特定机会的 系统性回应. 德鲁克在他的书《创新与企业家精神》中, 提出了七个准则来解释如何系统地选择创新机会.

• Thiago 抓住了 Vim 代码维护困难的 意外事件, 创造了 Neovim, 为“更好的插件开发工作流”这一 流程需求 提供了革命性的解决方案.
• Calvin 和 Phil 分别是“Lisp on Lua”这一 新知识 的创造者和推广者. Phil 通过建立社区, 成功利用了 Neovim 用户日益增多的 人口变化, 将 Fennel 从一个语言原型培育成了一个活跃的生态系统.
• Olical 敏锐地捕捉到 Fennel 可以编译成 Lua 的 新知识, 并将其应用于产品, 将 Conjure 移植到 Fennel, 解决了现有的性能瓶颈.

这些人之所以能引发一场革命, 部分是因为他们高超的技术能力, 但更重要的是, 他们能够 系统地识别和利用这些创新机会, 将看似偶然的机会转变为优秀的软件和蓬勃发展的社区.

如果你使用的是 Mac 电脑, 可以使用 brew 来安装.

• 安装 brew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• 安装 neovim

brew install neovim

如果你电脑上已经有 neovim, 别忘了先检查一下版本.

~$ nvim --version
NVIM v0.11.3

如果版本不是 >= v0.11.3, 之后遇到插件不兼容问题时, 请考虑升级 Neovim.

Fnlfmt 也直接安装在操作系统上, 所以我们使用 brew 来安装:

brew install fnlfmt

• 首先, 安装一个插件管理器; 我使用 vim-plug.

vim-plug 安装:

sh -c 'curl -fLo "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/autoload/plug.vim --create-dirs \
       https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'

• 接下来, 通过 vim-plug 安装插件.

打开你的 Neovim 配置文件:

~$ nvim $HOME/.config/nvim/init.vim

在该文件中, 粘贴以下内容:

" Specify a directory for plugins.
call plug#begin(stdpath('data') . '/plugged')
" === Basic Setup ===
" color, look and feel
Plug 'tomasr/molokai'

" === Highlight ===
" Syntax highlight for fennel language
Plug 'bakpakin/fennel.vim'

" rainbow parentheses
Plug 'frazrepo/vim-rainbow'

" === Interactive Development ===
" Conjure
Plug 'Olical/conjure'

" === S-expression editing ===
Plug 'guns/vim-sexp'
Plug 'tpope/vim-sexp-mappings-for-regular-people'
Plug 'kylechui/nvim-surround'
Plug 'jiangmiao/auto-pairs', { 'tag': 'v2.0.0' }

call plug#end()

if !empty(glob(stdpath('data') . '/plugged/molokai'))
    colorscheme molokai
endif
" Config the rainbow-parentheses
let g:rainbow_ctermfgs = [
    \ 'red',
    \ 'yellow',
    \ 'green',
    \ 'cyan',
    \ 'magenta',
    \ 'gray'
\ ]
" rainbow parentheses enabled for fennel
autocmd FileType fennel call rainbow#load()

let maplocalleader=","
let mapleader="\\"
" Make vim-sexp recognizes the fennel
let g:sexp_filetypes = 'fennel'
if !empty(glob(stdpath('data') . '/plugged/nvim-surround'))
    lua require("nvim-surround").setup()
endif

function! Fnlfmt()
 !fnlfmt --fix %
 " :e is to force reload the file after it got formatted.
 :e
endfunction

augroup FennelOnSave
  " Format after save
  autocmd!
  autocmd BufWritePost *.fnl call Fnlfmt()
augroup END

接下来, 在 Neovim 的 Normal Mode 下, 执行以下命令:

:source %
:PlugInstall

安装完成后, 打开一个 Fennel 文件, 应该会是这个样子:

• 首先, 在 (greet ...) 函数的右边加上一个字符串 :great. 这里要特别注意: 在 Fennel 中, 连续的字符串可以用在前面加冒号来表示.

(greet :world) :great

• 将光标移动到行, 列 (4, 14) 并按下 >)

你注意到了吗? 当你按下 >), 光标对应的 括号 被向右移动了, 正好移到了 :great 的右边, 就像它“吞下”了 :great 一样.

• 将光标移动到行, 列 (4, 21) 并按下 <)

你注意到了吗? 当你按下 ＜), 光标对应的 括号 被向左移动了, 正好移到了 :great 的左边, 就像它“吐出”了 :great 一样.

安装和设置很容易卡住. 如果你卡住了, 不妨考虑写信给我? 或者在 Clojure 社区寻求帮助?

在命令式语言中, 行数通常被用作衡量代码量的单位, 我们通常认为自己是逐行编写代码. 每一行代码都是一个语句, 一个语句可以是一个函数调用, 变量赋值等等. 这种思维模型可以称为“面向语句”. 面向语句的思维模型在调试时尤其有效, 特别是使用 Debugger 时. 因为在调试时, 我们告诉 Debugger 逐步执行: “执行一行代码, 然后立即停止.”

然而, Lisp 程序员使用一种不同的 心智模型 进行编码: 他们认为自己是通过一系列 表达式 来编写代码. 表达式以树状方式连接, 形成一个 抽象语法树. 同时, 一个模块 (通常是一个源代码文件) 通常由多个语法树组成. 每个表达式在求值后都会有一个返回值. 即使是像 (print xxx) 这样只有副作用的函数调用表达式, 也会有一个 nil 返回值.

此外, 由于交互式开发的特性, Lisp 程序员几乎总是开着一个 Debugger. 交互式开发的运作原理是: 当用户发出像 Evaluate Code 这样的编辑器命令时, 编辑器会自动抓取一个表达式, 将其发送到一个正在运行的解释器进行求值, 然后将结果发送回编辑器. 换句话说, 在开发软件时, Lisp 程序员总是有一个正在运行的软件, 其内部状态会根据他们的意图不断改变. 这种效果几乎等同于非 Lisp 程序员在操作 Debugger 时所达到的效果: “有一个正在运行的程序, 工程师可以控制它执行到哪一行, 同时修改和监控其内部状态.”

2019年, 我去了一家公司 L Corp 开发软件. 那时, 作为一名承包商, L Corp 分配给我一台 Macbook Air 用于办公. 我用我通常的方式开发软件 (Clojure on JVM), 然后, 大约每个月一次, 在写了一些代码后, Macbook Air 会因为内存被交互式开发完全消耗而强制关机并重启.

想象一下, 如果你只能在一台 1975 年的 MITS Altair 8800 上编写代码, 你会选择 C 还是 Lisp? 你不需要选择, 因为高级的 Lisp 根本无法在上面运行.

前面我们提到, Lisp 程序员不是逐行编写, 而是逐个表达式编写. 那么他们是如何阅读代码的呢?

在阅读代码时, 进行一些“非正式推理”是必不可少的. 如果代码的某些部分无法直观理解, 你必须先在脑海中运行它, 然后尝试推断其行为. 换句话说, 你成了一个活生生的解释器.

Fennel 代码的求值顺序只有三个规则:

1. 从内到外 (Inside-Out)
2. 从上到下 (Top-Down)
3. 根据宏的实现 (According to Macro Implementation)

这个规则意味着当我们遇到一个嵌套表达式时, 我们必须首先对最里面的表达式求值, 然后递归地向外移动. 这就像一个俄罗斯套娃; 你必须一层一层地打开才能看到最里面的那个.

例如:

(+ 1 (* 2 3))

在阅读这段代码时, 我们不能直接计算 (+ 1 ...) , 因为我们不知道第二个参数是什么. 我们必须首先进入最里面的表达式 (* 2 3). 在我们的脑海中, 我们首先对 (* 2 3) 求值, 得到 6. 然后, 我们用这个值替换原来的表达式, 整个代码片段就变成了 (+ 1 6). 最后, 我们对这个外层表达式求值得到 7.

这个规则适用于任何包含多个互不嵌套的表达式的情况, 无论是在一个文件内还是在一个函数内. 当代码中有多个表达式时, 求值顺序从最顶层, 最左边的表达式开始, 依次向下进行.

任何执行顺序无法用前两条规则解释的东西都是宏, 我们将在后面的章节中详细讨论宏. 对于初学者, 你只需要知道 let 和 if 是宏, 因为它们是最常用的.

• if 的执行顺序

首先, 对 A-expression 求值. 如果为真, 则对 B-expression 求值; 如果为假, 则对 C-expression 求值.

(if A-expression
   B-exression
   C-expression)

• let 的执行顺序

首先, 对 B-expression 求值, 然后将其结果临时绑定到 A-symbol. 接下来, 对 D-expression 求值, 然后将其结果临时绑定到 C-symbol. 最后, 对 E-expression 和 F-expression 求值.

(let [A-symbol B-expression
      C-symbol D-expression]
    E-expression
    F-expression)

在我们刚刚看到了像 let 这样的赋值语法后, 一个问题出现了: “一个 let 表达式有返回值吗?”

是的, 它的返回值是它内部最后一个表达式的返回值, 也就是 F-expression 的返回值.

另一个与 let 非常相似的结构是 fn, 它是定义函数的语法. 下面, print-and-multiply 是一个函数. 当它被调用时, 它会执行函数定义内的表达式, 并使用最后一个表达式的返回值作为整个函数的返回值.

(fn print-and-multiply [a b]
  (print (+ a b))
  (print (- a b))
  (* a b))

以上面的代码为例, print-and-multiply 的返回值是 (* a b) 表达式的结果, 因为它也是整个函数定义内最后一个被求值的表达式.

这一点与大多数命令式语言中的函数返回值有显著不同. 在许多命令式语言中, 你必须显式使用 return 关键字来指定返回值; 否则, 函数可能没有返回值或返回 nil. 在 Fennel 中, 最后一个表达式的返回值被自动视为整个函数的返回值.

当用作字典时, 使用 大括号 来声明. 在下面的例子中, "number" 是键; 531 是值.

{"key" value
 "number" 531
 "f" (fn [x] (+ x 2))}

• 句点 . 用于从 Table 中检索与“键”对应的“值”.

(let [tbl (function-which-returns-a-table)
      key "a certain key"]
  (. tbl key))

• tset 用于向 Table 写入新的“键/值”对或修改现有的.

(let [tbl {}
      key1 "a long string"
      key2 12]
  (tset tbl key1 "the first value")
  (tset tbl key2 "the second one")
  tbl)
; -> {"a long string" "the first value" 12 "the second one"}

当 Table 用于存储具有线性, 顺序语义的数据时, 我们需要将 Table 的所有 键 设置为从 1 开始递增的数值.

对于这种用例, Fennel 提供了一种新的声明语法, 使用 方括号 [. 在这种情况下, 你不需要写键值; 它们会自动从 1 开始生成.

["abc" "def" "xyz"]
; equivalent to {1 "abc" 2 "def" 3 "xyz"}

table.insert 有两种用法:

• 一种是插入一个没有索引的新值, 这种情况下 table.insert 会将新值附加到列表的末尾.
• 另一种是传递一个索引和一个新值, 这种情况下 table.insert 会将新值插入到相应的索引处, 列表中所有其他元素的索引会自动调整.

table.remove 也有两种用法, 类似于 table.insert, 带或不带索引.

(local ltrs ["a" "b" "c" "d"])

(table.remove ltrs)       ; Removes "d"
(table.remove ltrs 1)     ; Removes "a"
(table.insert ltrs "d")   ; Appends "d"
(table.insert ltrs 1 "a") ; Prepends "a"

(. ltrs 2)                ; -> "b"
;; ltrs is back to its original value ["a" "b" "c" "d"]

在 Fennel 中, 我们通常将用于 字典目的 的 Table 称为 通用表 (General Tables), 将用于 列表目的 的 Table 称为 序列式表 (Sequential Tables).

length 可用于返回列表容器或字符串的长度.

(let [tbl ["abc" "def" "xyz"]]
  (+ (length tbl)
     (length (. tbl 1)))) ; -> 6

Lua 的一大特色是它与 C/C++ 语言的无缝集成. 它提供了一个优雅的 C API, 允许宿主应用程序轻松注册 C 函数供 Lua 代码调用. 例如, 如果你的主程序需要读取一个配置文件, 你可以在 C 中编写一个 read_config_file 函数, 然后通过 Lua 库中的 C API 将其暴露给 Lua 环境.

当 Lua 代码调用 read_config_file 时, 控制权返回到宿主应用程序以执行 C 函数. 该函数完成后, 结果返回给 Lua. 这种机制使 Lua 不仅仅是一种脚本语言, 更像是一个高度可定制的“组件”, 可以与主程序进行深度交互, 用于逻辑处理, 配置, 甚至游戏插件等任务.

Lua 提供 8 种数据类型:

• nil: 表示“无值”. 如果在 if 条件中使用 nil, 它被视为 false.
• boolean: 只有 true 和 false. 在 Lua 中, 只有 nil 和 false 被认为是假. 所有其他值, 包括数字 0, 空字符串 "", 或空 Table {}, 都被认为是真. 这与某些其他编程语言 (如 C++ 或 JavaScript) 的行为不同.
• number: 双精度浮点数.
• string: 字符串.
• table: 唯一的容器类型.
• thread: 虽然使用了“线程”这个词, 但它实际上指的是 协程.
• function: 函数.
• userdata: 如果某些类型是由 C 语言返回的, 则使用此类型.

在 Fennel 中, 你可以使用 (type $variable) 来检查 $variable 的类型.

在 Lua 中, 标准库中的一些函数没有内置在全局环境中, 所以我们需要在使用它们之前 require 该库. 例如, 下面的 io.open:

local io = require("io")
io.open("file.txt", "r")

另一方面, 有些函数直接内置在全局环境中; 这些是全局函数. 特别重要的包括:

• tonumber: 将字符串转换为数字.
• tostring: 转换为字符串.
• print: 首先对其所有参数调用 tostring, 然后打印它们, 后面跟着一个换行符. 打印时参数之间会插入空格.
• type: 返回类型.
• pcall: 在保护模式下调用函数. 因为是保护模式, 如果发生错误, 程序不会立即崩溃. 它返回两个值: 第一个是布尔值, 表示调用是否成功; 第二个是返回值或错误消息.
• error: 停止程序执行, 生成一个错误, 并跳转到最近的 pcall.
• assert: 检查一个条件; 如果为假, 抛出一个错误.
• ipairs: 遍历序列式表.
• pairs: 遍历任何表.
• unpack: 将一个序列式表从单个表解包成多个独立的值.
• require: 加载并返回一个模块.

如果我们对上述函数做一个简单的分类:

1. 辅助函数: tonumber, tostring, print, type.
2. 错误和异常处理: pcall, error, assert.
3. 容器相关: ipairs, pair, unpack.
4. 模块加载: require.

让我们看一个 Fennel 中 unpack 的用法示例:

(local t [:a :b :c])
(print (unpack t))       ;; a   b   c

如果你做过函数式编程, 是否会想到一个巧妙的函数 apply? 由于 Fennel 采用极简主义, 并且已经从 Lua 借鉴了 unpack, Fennel 不提供 apply 函数.

如果你有任何前面介绍的函数无法处理的需求, 在引入第三方库之前, 首先查阅 Lua 5.1 手册. 你可能会在 Lua 的标准库中找到你需要的东西.

有时, GenAI 生成的代码根本无法运行, 甚至操作符位置都不正确. 这很常见, 因为 Fennel 是一种小众语言, 没有足够的训练数据供 AI 利用. 解决方法很简单: 你可以先让 GenAI 生成 Lua 代码, 然后使用编译器/反编译器将其转换为 Fennel 代码.

在 Lua 中, 一个 模块 本质上就是一个 Table. 这个 Table 包含了该模块打算向外部暴露的所有函数和变量. 当你使用 require 加载一个模块时, 它返回的就是这个 Table. 这种设计非常简洁, 因为你不需要额外的关键字或特殊语法来定义一个模块; 你只需创建一个 Table 并返回它.

例如, 假设你有一个名为 aa.lua 的文件, 内容如下:

local aa = {}

function aa.ff()
  return "This is a public function."
end

aa.vv = 100

return aa

在这个例子中, aa 是一个 Table. 我们将 ff 和 vv 设置为这个 Table 中的键值对, 以便它们可以从外部访问.

Lua 的 Table 也可以用来实现面向对象编程 (OOP), 主要通过元表 (metatable) 功能.

一个 Lua Table 可以包含一个元表, 这个元表虽然也是一个 Table, 但带有特殊的语义. 当一个包含元表的 Table 被当作一个对象并进行方法调用时, 如果找不到该方法, 它会自动在元表中搜索, 从而实现面向对象编程的关键特性, 如继承和多态.

如果容器的键是字符串类型且不包含空格或保留字符, 键可以用冒号前缀表示法书写, :shorthand.

{:key value :number 531}

这种冒号前缀表示法在 Table 键中尤其常见. 在 Clojure 语言中, 这种冒号前缀表示法直接对应于一个名为 关键字 的新数据类型, 专门用于容器键.

值得注意的是, 在 Fennel 中, 这种冒号前缀表示法在编译后会转换为 Lua 的字符串类型; 例如, :key 变成 "key". 这与 Clojure 的关键字不同, 后者是一个独立的数据类型, 但它提供了类似的便利性.

当 Table 的键使用冒号前缀表示法时, 可以使用 ${table}.${key} 来访问值, 这比 (. ${table} ${key}) 更简洁.

(let [tbl {:x 52 :y 91}]
  (+ tbl.x tbl.y)) ; -> 143

此外, ${table}.${key} 语法也可以与 set 函数一起使用.

(let [tbl {}]
  (set tbl.one 1)
  (set tbl.two 2)
  tbl) ; -> {:one 1 :two 2}

• 对于序列式表, 可以进行 基于位置 的解构.

(let [data [1 2 3]
      [fst snd thrd] data]
  (print fst snd thrd)) ; -> 1       2       3

• 对于通用表, 可以进行 基于键 的解构.

(let [pos {:x 23 :y 42}
      {:x x-pos :y y-pos} pos]
  (print x-pos y-pos)) ; -> 23      42

对于基于键的解构, 如果接受解构值的变量名与键名完全相同, 可以使用更简化的语法: 键不再使用“冒号前缀表示法”, 而是直接写成“冒号”.

 (let [pos {:x 23 :y 42}
      {: x : y} pos]
  (print x y)) ; -> 23      42

将光标移动到位置 (13, 4), 也就是 ;; (update-keys 中的 左括号, 按 ,ee 求值, 你仍然会得到一个结果.

这里有一个关键点: “即使是注释, 你仍然可以对它求值.” 方便吧? 注释就是测试.

这里解释一下代码的作用:

我定义了一个名为 update-keys 的函数. 它可以使用作为其第二个参数提供的函数对 Table 的所有键应用一个操作.

在第 13 行的注释中, {:code "(+ 1 2)" :op :eval} 经过操作后, 每个键都会从字符串变成一个 Table.

键可以使用字符串或数字以外的类型? 没错, Lua 的 Table 提供了这种语义.

如果读者在 Conjure 的 github 仓库中寻找 :conjure.nfnl.core 对应的源代码, 他们是找不到的. 这是因为 Conjure 只包含了已经编译成 Lua 的版本.

nfnl 有自己的仓库, 我发现以下库特别有用:

• core: 这是 Clojure 标准库仿制品的一个简洁版本.
• notify: 一个日志库.
• macros: 提供一个 time 函数.

Clojure 库的一个特点是“几乎每个表达式都有一个返回值.” 写代码时, 不需要过多思考; 所有东西都 просто 有一个返回值. 此外, 借助交互式开发, 你不需要太费脑筋——只需写一点代码, 观察返回值如何变化, 然后不断调整直到达到目标.

因此, 当我使用 reduce 时, 在传递给它的匿名函数内部, 我调用了 assoc, 它也有一个返回值——它返回修改后的 Table. 在这个上下文中, tset 的语义与 assoc 类似, 都是修改一个 Table, 但 tset 的返回值是 nil, 所以如果用 tset 代替 assoc, 就会导致错误.

没办法, tset 毕竟是 Lua 的函数.

Fennel 毕竟也被设计成一种函数式编程语言, 所以它自然有函数式结构, 因此有了 collect. 然而, 其核心存在细微差别: Fennel 提供的语法是用宏实现的; 另一方面, :conjure.nfnl.core 主要由函数组成.

一方面, 宏不具备函数丰富的 表达力; 例如, 宏不能作为函数参数传递. 另一方面, 正因为它们是宏, 当这段代码被编译成 Lua 时, 几乎没有多余的变量复制, 这非常节省资源, 可以看作是一种 性能优化.

记忆这些命令其实有英文线索. 例如, <localleader>lv 打开的窗口是垂直的, 所以你可以联想到 "log in vertical window". 一个稍微不那么明显的联想是, 文档的英文单词是 'documentation', 但通常缩写为 'doc', 对应 K.

Conjure 还有更多命令吗? 有的, 官方文档里有更多命令. 有必要研究更多吗? 我们这里讨论了总共 9 个 Conjure 命令, 这对于一个专业的 Lisp 程序员来说, 用五年应该也够了.

上述 9 个命令可以分为四大类, 下面逐一解释.

• 日志缓冲区

<localleader>lv, <localleader>lq, <localleader>lr 显然是用于日志缓冲区控制. 日志缓冲区是 Conjure 在众多 Vim 交互式开发插件中的一个突出设计. 日志缓冲区的一个主要优点是: 即使你求值的东西返回的数据过大, Neovim 通常也不会卡死. 数据只会存在日志缓冲区里.

• 表达式求值

这四个命令, <localleader>ee, :ConjureEval [code], <localleader>eb, <localleader>ew, 在 Conjure 的核心中, 与解释器通信时使用相同的结构. 例如, <localleader>ee 在 Conjure 中的实现是先读取一个表达式, 然后将其内容发送给解释器; 至于 <localleader>eb, 它是先读取整个缓冲区的内容, 然后将该内容发送给解释器. 上述两个命令的后半部分涉及相同的行为.

• 跳转到定义

它向解释器发送一个特殊命令来查询定义. 值得注意的是, Fennel 语言的跳转到定义功能在最新版本的 Conjure 中尚未实现. 另一方面, 我们仍然可以通过 LSP (language server protocol) 配合安装 fennel-ls 来实现跳转到定义的功能.

• 查询文档

它向解释器发送一个特殊命令来查询文档. 补充一下, K 是 Neovim 的一个内置命令, 用于查询光标下关键字的文档. Conjure 巧妙地集成了这个命令, 使得 K 可以自动向 Lisp 解释器发送查询请求, 这样我们就可以查找函数文档了.

思考以下代码: 当我们想了解局部变量 z 的值时, 似乎 print 是唯一的选择. print 的烦人之处在于, 当打印太多时, 我们必须手动搜索想要的输出.

(fn wrong-add [x y]
  (let [z (+ x 2)]
    (+ z y)))

在 Fennel 中, 我们可以使用 tset (table set) 来“捕获”运行时局部变量的值, 并将它们写入一个全局 Table, 从而可以随时检查它们. 这个技巧的核心思想是: 通过修改一个全局可访问的状态来观察内部局部变量.

下面重写的关键点是: 在顶部添加 (local ddd {}), 并使用 (tset ddd :z z) 来捕获 z 的运行时值.

(local ddd {})

(fn wrong-add [x y]
  (let [z (+ x 2)]
    (tset ddd :z z)
    (+ z y)))

(wrong-add 3 4)

用 <localleader>eb 对整个文件求值后, 将光标移到 ddd 上方, 执行命令 <localleader>eb, 你就会看到结果.

; evaluate (word): ddd
{:z 5}

这个技巧在不同的 Lisp 方言中有不同的实现; 例如, 在 Clojure 中, 通常会使用 def 来达到类似的效果.

想象一下, 在开发软件时, 你使用了一个库 A 的函数 pp. 你强烈怀疑 pp 有错误, 但如何测试来验证你的假设呢? 修改库? 这会不会有点费力, 特别是当 A 是一个已经安装的 jar 文件时?

在用 Clojure 开发时, 我做过这样的事:

1. 对 pp 执行跳转到定义, 跳转到库 A 的源代码中.
2. 修改 pp, 然后直接对缓冲区求值而不保存.

这样, pp 的定义就在解释器中被修改了, 你可以轻松地验证你的假设.

这里需要强调一点: 在 Neovim 中, 缓冲区不等于保存在硬盘上的文件. 缓冲区是你当前正在查看的文件的状态.

类似的技术在 Fennel 的情况下需要稍作调整.

对于第一步, Fennel 的跳转到定义通常无法处理库只有 Lua 源代码而没有 Fennel 源代码的情况. 在这种情况下, 你需要手动 grep 来找到正确的位置.

对于第二步, 如果找到的函数定义位置只是一个 Lua 文件, 你可以修改 Lua 文件, 并使用 Neovim 的 Ex 命令: :lua [content] 来对当前修改的内容求值.

在 day02, 这个插件是通过 vim-plug 安装的:

" rainbow parentheses
Plug 'frazrepo/vim-rainbow'

参考下图; 有了这个插件, 括号的前后对应关系就变得非常清晰了.

在 Lisp 社区, 对这个插件其实有不同的看法. 有些人认为写 Lisp 久了, 阅读代码时的重点不在括号上, 所以并不真的需要. 而彩虹括号插件则有分散注意力和造成过多视觉噪音的缺点.

另一方面, 考虑到初学者现有的思维模式, 我认为这还是相当有必要的.

对应的插件:

Plug 'jiangmiao/auto-pairs', { 'tag': 'v2.0.0' }

它能让你每次输入左括号时自动生成一个右括号. 并且这适用于你输入的任何东西: 圆括号, 方括号, 大括号, 或字符串引号符号. 换句话说, 一旦启用这个功能, 你的括号就会被强制成对.

因为编码过程中总有需要“复制粘贴”的时候, 会用到 Neovim 的 Normal Mode 命令. 然而, 自动括号配对插件只管理 Insert Mode 的命令. 也就是说, 如果我用“复制粘贴”时不小心, 就可能导致括号不成对. 但在这种情况下, 因为手动输入的括号总是成对的, 你就会卡住.

解决方法是使用 Normal Mode 命令 x 删除光标下的字符, 这样就可以直接移除不成对的括号.

用括号包围的需求是什么? 例如, 如果我已经打了一个词, 'local', 打完才发现需要加括号, 就太晚了.

local

因为“自动括号配对”的缘故, 无论我在 'local' 前面还是后面插入括号, 它都会强制一次性输入一对括号.

()local

在学习 Lisp 的前半​​年, 我会用 slurp 命令对右括号 ) 进行操作, 让它“吃掉”右边的词. 半年来, 我完全依赖 slurp 和 barf 来权宜处理所有这类问题.

后来, 我发现其实有一个优雅的解决方案: 使用命令来用括号包围.

• cseb: 用圆括号包围光标下的元素.
• cse[: 用方括号包围光标下的元素.
• cse{: 用大括号包围光标下的元素.
• dsf: 删除包围光标下元素的括号 (无论括号类型).

什么是元素? Element 是 vim-sexp-mappings-for-regular-people 插件定义的一个概念. 定义有点长, 但读者只需要记住定义中的三个规则:

• 复合形式 是由成对的 (), [], 或 {} 分隔的文本块.
• 如果光标在字符串内, 元素就是当前字符串.
• 如果光标在成对的结构化括号上, 元素就是当前的 复合形式.

要使用上述命令, 需要的插件是:

Plug 'guns/vim-sexp'
Plug 'tpope/vim-sexp-mappings-for-regular-people'
Plug 'kylechui/nvim-surround'

眼尖的读者可能会注意到关键词: vim-sexp. 没错, 这三套是 S-expression 编辑的辅助插件. 另外, 我其实在前半​​年就已经在用 S-expression 编辑了, 但我只知道用 slurp 和 barf.

在 Linux shell 中, 你可以这样移动光标:

• CTRL + a: 移动到命令行的开头
• CTRL + e: 移动到命令行的末尾

在 Neovim 中编辑单行时, 你可以这样移动光标:

• 0: 移动到行首
• $: 移动到行尾

一旦你进入了 Lisp 的世界, 我们对代码的看法就变了; 基本单位不再只是一行代码或一个词. 最重要的基本单位之一是 S-expression, 一个接一个.

编辑 S-expression 时, 你可以这样移动光标:

• (: 移动到 S-expression 的左括号.
• ): 移动到 S-expression 的右括号.
• %: 从左括号跳转到其匹配的右括号, 或从右括号跳转到其匹配的左括号.

• >e: 将光标下的元素向右移动.
• <e: 将光标下的元素向左移动.

这个功能在编写条件 if 语句时特别有用. 有时, 我们可能想交换 true 分支和 false 分支. 在分支的元素上执行一个 >e 命令就完成了交换.

我们也可以使用 vim-sexp-mappings-for-regular-people 插件定义的 元素 和 复合形式 概念作为删除的目标.

• dae: 删除光标下的元素.
• daf: 删除光标下的复合形式.

删除后, 将光标移动到另一个位置并按下粘贴命令 p; 被删除的元素或复合形式将被粘贴到新位置.

读者可能会问: “到底是什么让 S-expression 编辑这么好用? 有没有概念上的解释?”

当工程师开发软件时, 他们脑海中天生就有 语法树 的概念. 例如, 我们可能想交换一个条件语句的 true 分支和 false 分支, 每个分支都是一个子语法树. 然而, 不幸的是, 大多数时候, 编辑器无法像人类一样解析语法树. 因此, 在编写代码时, 即使我们脑子里想的是一个高度抽象的语义: “交换 true/false 分支,” 我们仍然必须将这个高级语义翻译成低级编辑器命令来完成编辑.

因为 Lisp 语法本身就反映了代码的语法树结构, 这种特殊的编程语言设计使得编辑器插件可以轻松解析 Lisp 的语法树, 从而使 高级编辑命令 (即 S-expression 编辑) 成为可能.

如果不是 Lisp, 编辑代码时, 我们在行, 词和字符之间移动 (注 1); 然而, 对于 Lisp, 编辑代码时, 我们可以在语法树内导航和编辑.

从设计的角度来看, 我们也可以说 Lisp 和 S-expression 编辑是 UNIX 哲学的一种体现:

Rule of Representation: Fold knowledge into data so program logic can be stupid and robust.

在 Lua 中, 声明 Table 的语法是:

local fruits = {"apple", "banana", "orange"}

local person = {
  name = "Alice",
  age = 30,
  city = "Taipei"
}

对应的 Fennel 语法是:

(local fruits [:apple :banana :orange])
(local person {:age 30 :city :Taipei :name :Alice})

而 Reader Macros 的工作原理如下:

当 Reader 读取源代码时, 遇到 […] 字符, 它会触发对应的 [...] 的 Reader Macro, 从而将其解析为 (sequential-table ...) ; 类似地, 遇到 {…} 字符, 它会触发对应的 {...} 的 Reader Macro, 从而将其解析为 (general-table ...) . (这里, 假设上述 Fennel 语法是通过 Reader Macros 实现的, 但实际上, Fennel 是直接在 Reader 中实现的)

观察上面的例子, 可以看到 Reader Macros 只改变了代码的 表现形式; 换句话说, 它们只提供了新的语法.

与 Reader Macros 相反, Lisp 宏的核心能力在于定义新的语义, 这意味着‘改变代码的 行为, 而不仅仅是改变其 表现形式.’ 让我们用 Fennel 的 Thread First 宏 -> 作为例子来解释这个概念.

在 Fennel 中, 如果你想对一段数据执行一系列操作, 你会嵌套函数调用, 从内到外写. 例如, 如果你想先给一个数加一, 然后乘以十, 最后取绝对值:

(math.abs (* 10 (+ 1 5)))

这段代码的阅读顺序是从内层到外层: (+ 1 5) → (* 10 ...) → (math.abs ...). 这种由内向外的写法使得代码在处理复杂的顺序操作时难以阅读和理解.

Fennel 的 -> 宏解决了这个问题, 它允许你用一种更自然, 线性的方式来表达相同的逻辑:

(-> 5
  (+ 1)
  (* 10)
  math.abs)

这是一个宏提供新语义的绝佳例子. 标准 Lisp 没有内置的“将前一个操作的结果作为下一个操作的参数”的语法. -> 是一个宏, 它的功能是在编译阶段将你写的线性代码:

(-> 5 (+ 1) (* 10) math.abs)

转换成一个嵌套的 S-expression:

(math.abs (* 10 (+ 1 5)))

这个重写过程就是宏赋予代码新行为的体现. 它不仅仅是替换一些字符, 而是创造了一个全新的操作流程和逻辑.

由于在现实世界的软件开发场景中真正需要编写 Lisp 宏的概率并不高, 如何编写它们的部分留给读者自行研究.

另一方面, 有一种特殊的 Lisp 宏用法, Clojure 社区也鼓励经常使用, 可以称之为 With-Macros.

例如, Fennel 有一个 with-open 语法, 这是一种 With-Macro.

用法如下:

;; Basic usage
(with-open [fout (io.open :output.txt :w) fin (io.open :input.txt)]
  (fout:write "Here is some text!\n")
  ((fin:lines))) ; => first line of input.txt

它的功能是帮助处理文件读取结束时关闭文件和释放资源. 换句话说, 虽然它也改变了‘行为’, 但它所做的行为改变通常只涉及开头和结尾的一些上下文管理.

这种 With-Macro 在处理与副作用相关的函数调用时特别有用.

在 Python 语言中, 没有 Lisp 宏, 但有一个与 With-Macros 等价的设计, 称为 Context Manager.

# Without using 'with'
f = open('test.txt', 'r')
try:
    content = f.read()
    # Even if an error occurs here, the f.close() in the finally block will still be executed.
    # This approach is more cumbersome and requires manual resource closing.
    print(content)
finally:
    f.close()

---

# Using 'with'
with open('test.txt', 'r') as f:
    content = f.read()
    # If an error occurs in the code here, `with` ensures that the `f` object's
    # `__exit__` method is automatically called, thereby correctly closing the file.
    # This approach is more concise and safe.
    print(content)

如果只用 S-expression 来构造向量和集合, 会写成这样:

(vector 1 2 3)
(set 1 2 3)

然而, Clojure 提供了一种更简洁的语法, 让数据结构看起来更像数据:

[1 2 3]   ;=> Represents a vector containing 1, 2, 3.
#{1 2 3}  ;=> Represents a set containing 1, 2, 3. Elements within a set must be unique.

经过符号的适当修改后, 语法是不是更简洁, 却仍然易于理解?

传统的编程语言通常将数据和逻辑分开处理. 数据是数据, 函数是函数; 它们是相互独立的. 然而, 在 Clojure 中, 逻辑 通常可以通过某些数据结构来表达, 而且甚至更容易理解.

这是什么意思呢? 让我们看一个简单的例子.

在 Clojure 中, 你可以用一个向量来表示一个“路径”. 例如, 向量 [:a :b :c] 可以表示一个顺序的 逻辑操作: 先进入 :a, 然后进入 :b, 最后到达 :c.

当你把这个向量传递给 get-in 函数时, 这个向量就不再是简单的数据了; 它把自己转换成了“告诉函数如何执行”的逻辑.

(def data {:a {:b {:c 100}}})

(get-in data [:a :b :c])
;; => 100

在这里, 向量 [:a :b :c] 清楚地表达了“从 data 字典中顺序检索 :a, :b, 和 :c 对应的值”的逻辑.

同样, 集合也可以用来表达逻辑. 想象你有一个数据序列 data-seq, 你想筛选出所有包含 :a 或 :b 的元素. 你不需要写一个冗长的匿名函数; 只需直接将集合 #{:a :b} 传递给 filter 函数.

(def data-seq [:a :c :b :d])

(filter #{:a :b} data-seq)
;; => (:a :b)

在这个例子中, filter 函数会依次将 data-seq 的每个元素 (:a, :c, :b, :d) 传递给作为函数的 #{:a :b}. 这个集合不仅仅是数据; 它还定义了筛选规则.

这是 Clojure 的核心思想之一: 通过简单, 可读的数据结构来表达逻辑, 这使得代码更简洁, 更易于理解. 也可以说, 在这些例子中, 数据结构是一种 DSL (领域特定语言), 因为它们被赋予了新的语义.

这种面向数据的思维模型让 Clojure 程序员一方面继承了 Lisp 程序员的传统: “为特定问题定义新语言 (DSL), 最终使代码成为表达其意图的优秀工具.” 另一方面, 它巧妙地避免了使用过多宏可能导致程序难以调试的缺点.

读者可能会问: “如果我想赋予数据结构非常复杂的语义, 我应该如何设计它们?”

这时候你就可以写一个树遍历解释器 (treewalk interpreter).

传统 Lisp 的一句经典名言, “代码即数据 (Code is Data),” 可以这样理解: 因为代码是 S-expression, 代码也是一个抽象语法树, 而抽象语法树是一种数据结构 (Data). 也就是说, 代码是一种数据结构. 而 Lisp 宏可以转换 S-expression, 从而增加新的语义. 换句话说, “代码即数据”说的是 Lisp 宏.

另一句经典名言是“数据即代码 (Data is Code),” 可以这样理解: 在 Lisp 代码中, 有一些 S-expression 不是函数, 不是宏, 而是数据结构 (Data). 而这些数据结构通常可以被赋予新的语义, 所以它们实际上是 DSL, 这是另一种形式的代码. 如果要赋予更复杂的语义, 就需要一个树遍历解释器. 换句话说, “数据即代码”说的是 作为 DSL 的数据结构.

与传统 Lisp 强调“代码即数据”哲学相比; Clojure 除了使用“代码即数据”哲学, 还积极使用“数据即代码”哲学.

你会定义一个变量 balance, 然后通过一系列赋值操作来改变它的状态:

- ~balance = 0~ (initial value)
- ~balance = balance + 35000~ (salary)
- ~balance = balance - 65~ (breakfast)
- ~balance = balance - 15000~ (rent)

用这种方法, 绝对是超级节省内存, 计算也简单. 它也能达到目标: 知道每天正确的总余额. 顺便说一句, 上述“顺序改变状态”的方法是命令式编程的一个特点; 在某种程度上, 这是一个特性, 因为它非常节省内存.

那么, 用 函数式编程 (FP) 来记账会是什么样子呢?

FP 不是通过重复修改现有状态来实现计算, 而是将“计算余额”看作一个 函数. 你会将所有交易记录视为这个函数的 输入, 然后函数会给你一个 输出, 这就是最终的余额. 它最小化了“改变”状态, 而是重复地“计算”新结果.

例如, 你可以想象一个 sum 函数, 它的输入是一个包含所有交易的列表, 输出是最终的余额:

balance = sum([+35000, -65, -15000, -350, -850])

注意这里的计算方法: 一方面, 你需要记录每一笔交易, 一个都不能丢, 这显然消耗更多的内存. 另一方面, sum 函数的结果 (输出) 只与它的输入有关, 完全独立于任何外部状态.

读到这里, 你可能会想: “两种方法都能得出最终余额, 那么 FP 的实际好处是什么?”

假设今天出了一个错误, 你发现最终结果算错了?

如果你的记账使用 命令式编程, 典型的调试方法是每次 balance 改变时检查新值是否正确. 换句话说, 你会不断地检查系统的内部状态.

但如果你的记账使用 函数式编程, 典型的调试方法是确保 sum 函数的数据转换是否正确, 以及提供给 sum 的输入是否正确. 你注意到了吗? 与 命令式编程 的调试方法相比, 函数式编程巧妙地将调试复杂度分成了两个领域: 数据转换 和 输入.

正是上面提到的这种“分而治之”的可能性, 使得调试可以大大简化.

Fennel, 作为一种编译成 Lua 的 Lisp, 大量利用宏来解决这个问题. 宏是一种在编译时展开代码的工具. 你可以把它看作一个“代码生成器”.

例如, Fennel 的 icollect 实际上是一个宏. 当你写 (icollect ...) 时, 它在编译时会被展开成一个 Lua 的 for 循环. 这个循环直接对数据进行操作, 而不生成中间数组.

这样做的好处是, 在语法层面, 你仍然可以享受到 FP 语法提供的优雅和抽象, 但在底层, 它被转换成了性能更高的命令式代码, 大大减少了值复制.

Clojure 是 FP 的另一个领导者, 它对大量复制问题的解决方案是不可变集合 (Immutable Collection). 什么叫不可变集合?

它是一种特殊的数据结构, 一旦创建就不能被修改. 如果你需要“修改”它, 你会得到一个新的不可变集合, 但这个新的集合和旧的集合会共享大部分底层结构.

以 Clojure 的向量为例, 它使用的是持久化向量 (Persistent Vector) 数据结构. 其原理是一个树形结构. 当你对一个向量执行 assoc (添加或修改元素) 操作时, 它不会复制整个向量, 而只复制从根节点到需要修改的叶子节点的路径. 这使得每次“修改”的成本非常小, 大约是 log₃₂(n), 而不是 O(n).

这种设计的优点是:

• 性能优化: 显著减少了数据复制的开销, 特别是对于大型集合.
• 内存效率: 新旧集合共享大部分内存空间, 减少了内存消耗.
• 保持纯粹性: 仍然遵循 FP 的不可变性原则, 使代码更安全, 更易于推理.

总而言之, 在处理值复制问题时, FP 通过使用宏或特殊的不可变集合结构, 在保持不可变性核心概念的同时, 有效地解决了潜在的性能问题. 这是使 FP 在现代软件开发中得以实用的重要基础之一.

在 Clojure 中, mapcat 是 map 和 concat 的组合. 它的目的是将一个函数应用于集合中的每个元素, 然后将所有返回的序列连接成一个单一的序列. 这在我们从集合中的每个元素生成一个新的集合, 然后需要将这些小集合合并成一个大集合时特别有用.

例如, 假设我们有一个包含多个子集合的集合, 我们想将它们扁平化成一个单一的序列.

(def data '((1 2) (3 4) (5 6)))

;; Using map and concat
(apply concat (map identity data))
;; => (1 2 3 4 5 6)

;; Using mapcat
(mapcat identity data)
;; => (1 2 3 4 5 6)

另一个更常见的应用场景是, 当我们需要处理一个集合并从每个元素生成一个包含多个值的新序列时.

(def users '("Alice" "Bob" "Charlie"))

;; Suppose we have a function that can generate social media accounts related to a username
(defn get-social-media-accounts [user]
  (condp = user
    "Alice" '("twitter/alice" "github/alice")
    "Bob" '("twitter/bob")
    "Charlie" '("twitter/charlie" "linkedin/charlie")))

;; Use mapcat to get all social accounts for all users and merge them into a single sequence
(mapcat get-social-media-accounts users)
;; => ("twitter/alice" "github/alice" "twitter/bob" "twitter/charlie" "linkedin/charlie")

if 模式是一类变化多端的习语, 讨论起来相当冗长. 有兴趣的读者可以参考这篇文章.

如果松耦合机制在面向对象的编程语言中, 包括 Java 和 Lua, 它们通常通过 Java 接口或 Lua 元表实现, 通常作为服务提供者接口 (Service Provider Interface). 未来, 如果我们需要替换一个通过这种机制耦合的旧模块, 我们只需要开发一个实现相同 Java 接口或注册相同 Lua 元表函数的新模块, 新模块就可以顺利替换旧模块.

因此, 我们可以说面向对象编程语言提供的松耦合机制是一种: “函数签名作为传输协议”.

那么 FP 呢? 在典型的 FP 程序中, 我们不会创建很多对象, 因为没有必要. 对于数据建模, 大多数时候, 我们可以简单地使用像列表或字典这样的数据结构. 因此, 代码库将主要由大量的数据结构和函数组成.

那么有松耦合机制吗? 有的.

首先, 数据结构本身就是一种优秀的松耦合机制. 回想一下前面传输协议的例子, 传输协议仅仅规定通信双方相互传输正确形状的数据, 仅此而已. 换句话说, 我们可以说函数式编程语言提供的松耦合机制是一种: “数据结构作为传输协议”.

此外, 还有一个非常重要的概念: 许多动态语言实际上具有鸭子类型 (Duck Typing). 鸭子类型本身也可以被视为“函数签名作为传输协议”的一种实现.

首先, 你需要安装 LuaJIT. 相比于找到 Neovim 的 LuaJIT, 直接用 Homebrew 安装一个新的会更简单.

brew install luajit

接下来, 开始下载 LuaRocks 的 tarball, 创建一个系统特定的 ~/.luarocks-luajit 目录, 设置参数, 编译并安装.

wget https://luarocks.org/releases/luarocks-3.12.0.tar.gz
tar zxvf; cd luarocks-3.12.0
mkdir ~/.luarocks-luajit
./configure \
  --with-lua=$(brew --prefix luajit) \
  --with-lua-include=$(brew --prefix luajit)/include/luajit-2.1 \
  --lua-suffix=jit \
  --prefix=$HOME/.luarocks-luajit
make && make install

最后, 我们需要告诉操作系统将来在哪里找到 luarocks 命令的可执行文件. 并使用 source 重新加载 shell 的配置文件.

echo 'export PATH=$HOME/.luarocks-luajit/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

特别注意: 上面提到的 LuaRocks 版本非常重要, 因为 LuaJIT 2.0 有 65536 个常量的限制. 如果不是特定的 LuaRocks 版本, 你会遇到这个错误: "Error: main function has more than 65536 constants"

安装成功后, 当你发出命令:

luarocks install ${package}

新的 ${package} 将被安装在 $HOME/.luarocks-luajit/ 目录下.

到目前为止, 尽管新的 Lua 模块已经安装到正确的位置, Neovim 内的 LuaJIT 仍然找不到它们, 所以我们必须明确设置路径.

首先, 找到 Neovim 的配置文件位置, 并在那里创建一个 lua 文件夹.

cd ~/.config/nvim/
mkdir lua

在该文件夹中, 创建一个 Lua 脚本: luarocks.lua. (文件名可以任意.)

nvim lua/luarocks.lua

将以下内容粘贴到 luarocks.lua 中, 然后保存.

local function add_luarocks_paths()
  local home_dir = os.getenv("HOME")
  local luarocks_path = string.format("%s/.luarocks-luajit/share/lua/5.1/?.lua;%s/.luarocks-luajit/share/lua/5.1/?/init.lua", home_dir, home_dir)
  local luarocks_cpath = string.format("%s/.luarocks-luajit/lib/lua/5.1/?.so", home_dir)
  package.path = package.path .. ";" .. luarocks_path
  package.cpath = package.cpath .. ";" .. luarocks_cpath
end

return {add_luarocks_paths = add_luarocks_paths}

最后一步是在 ~/.config/nvim/init.vim 中添加一行.

lua require("luarocks").add_luarocks_paths()

对更具体细节感兴趣的读者可以考虑使用 Ex 命令 :luafile % 在 Neovim 中加载当前打开的 Lua 模块, 以及 Ex 命令 :lua print(os.getenv("HOME")) 来快速验证这些 Lua 命令的效果.

我们将创建一个 Hello World 插件, 它将在 Neovim 启动时初始化, 并为 Neovim 注册一个 Ex 命令. 之后, 用户就可以使用 :HelloFennel Ex 命令.

• 先决条件, 准备 nfnl 配置文件.

echo "{}" > ~/.config/nvim/.nfnl.fnl

有了这个配置文件, nfnl 的自动编译功能就可以被启用. 详细说明请参考 nfnl 的 README.

• 创建插件文件夹

mkdir ~/.config/nvim/fnl

• 创建一个新文件 ~ /.config/nvim/fnl/hello.fnl, 内容如下:

(fn hello []
  (print "Hello World Fennel!"))

(fn setup []
  (vim.api.nvim_create_user_command
    :HelloFennel
    hello
    {}))

;; Export the setup function so init.vim can call it
{: setup}

• 修改 ~/.config/nvim/init.vim 文件, 添加以下行:

lua require("hello").setup()

• 测试:

当你保存 hello.fnl 文件时, nfnl 会自动将其编译成 ~/.config/nvim/lua/hello.lua.

重启 Neovim 后, 输入 Ex 命令 :HelloFennel, 你会看到底部打印出 Hello World Fennel! 的消息.

首先, 让我们看一下 hello.fnl 的内容. 在这个文件中, 我们定义了两个函数: hello 和 setup. hello 用于打印消息, 而 setup 用于注册一个 Ex 命令.

在 setup 内部, vim.api.nvim_create_user_command 是 Neovim 的 API. 这个 API 的第一个参数是 Ex 命令的名称; 第二个参数是 Ex 命令要执行的函数; 第三个参数是要传递给函数的参数 (Lua Table 数据类型).

在 hello.fnl 的末尾, 按照惯例, 写入一个包含此 hello 模块外部 API 的 Lua Table. 在这个例子中, 显然是 setup.

当 Neovim 启动时, 它首先读取 init.vim. 当它读到命令 lua require("hello").setup() 时, 它会在 ~/.config/nvim/lua/ 文件夹中查找并加载 hello.lua 文件. 然后, 该文件中的 setup 函数将执行并注册 :HelloFennel 命令.

• 首先, 确保 Neovim 中已安装 nfnl 插件.
• 创建一个项目文件夹并进入.

$ mkdir my-plugin
$ cd my-plugin

• 在项目目录中准备 nfnl 配置文件.

echo "{}" > .nfnl.fnl

有了这个配置文件, nfnl 的自动编译功能就可以被启用. 详细说明请参考 nfnl 的 README.

• 创建子目录

mkdir -p lua/my-plugin fnl/my-plugin

• 创建文件 fnl/my-plugin/init.fnl, 内容如下:

(fn hi []
  (print "Hi World Fennel!"))

(fn setup []
  (vim.api.nvim_create_user_command
    :HiFennel
    hi
    {}))

;; Export the setup function so that init.vim can call it
{: setup}

• 保存文件后, lua/my-plugin/init.lua 将被自动生成.
• 如果你运行 tree 命令, 你应该会看到:

~$ tree -a
.
├── .nfnl.fnl
├── fnl
│   └── my-plugin
│       └── init.fnl
└── lua
    └── my-plugin
        └── init.lua

• 将以下文件包含在你的版本控制系统中:

.nfnl.fnl
fnl/my-plugin/init.fnl
lua/my-plugin/init.lua

• 将插件发布到你的 GitHub.

• 在你的 init.vim 文件中, 将你的插件添加到 Plug 块中:

call plug#begin(stdpath('data') . '/plugged')
Plug '$username/my-plugin'
call plug#end()

将 $username 替换为你的 GitHub 用户名.

• 在 Neovim 的 Normal Mode 下, 执行以下命令:

:source %
:PlugInstall

• 在你的 init.vim 文件的 Plug 块下面, 再添加一行:

lua require("my-plugin").setup()

这一行用于初始化插件.

• 重启 Neovim 后, 你就可以在 Neovim 中使用定义的 :HiFennel 命令了.

这个错误发生的原因是 Neovim 的 Lua 搜索路径 package.path 不包含你当前项目目录下的 lua 文件夹. 因此, 当 require 尝试加载 my-plugin.util 模块时, 它在默认路径中找不到对应的 lua/my-plugin/util.lua 文件, 从而抛出 'module 'my-plugin.util' not found' 错误.

执行命令 package.path = vim.fn.getcwd() .. "/lua/?.lua;" .. package.path 后, 这一行将当前工作目录下的 lua 文件夹添加到了 Lua 搜索路径中. 这样, require 就能正确找到并加载 my-plugin.util 模块了.

我们也可以使用目录本地 Neovim 配置 (Fennel)将这个对 Lua 搜索路径的修改直接整合到项目中, 这样将来就不需要用命令手动调整路径了. 此外, 一旦这个 Neovim 插件被安装, 这个路径问题将不复存在, 因为插件的目录会自动被包含在 Neovim 的 runtimepath 中.

你可以直接在命令行中使用 :lua 执行 Lua 代码. 这是一个非常方便的 Ex 命令, 特别适合快速测试几行代码或检查变量值.

例如, 当你想确认一个 Lua 模块是否加载成功时, 你可以执行命令:

:lua print(require('module.name'))

如果模块加载成功, require 函数将返回该模块的 table, 然后 :lua print(...) 会打印这个 Table 的内存地址 (例如 table: 0x...). 如果模块不存在, require 会抛出一个错误. 这是一个简单但有效的验证方法.

当 Neovim 运行时, 所有由 print, vim.notify 等函数生成的输出都会被记录下来. 你可以使用以下 Ex 命令查看这些历史消息.

:messages

当你直接使用 print 函数输出一个 Lua Table 时, 你通常只会看到一个类似 table: 0x... 的内存地址, 而不是具体内容. 这在调试时会造成很大的麻烦.

为了解决这个问题, 你可以使用 Neovim 内置的 vim.inspect 函数, 它可以将任何 Lua 值 (特别是 Table) 转换成人类可读的字符串格式. 这是一个非常实用的调试工具, 而且不需要安装任何额外的插件.

例如, 你可以在 Ex 命令或 Fennel 代码中使用它:

• 在 Ex 命令中

:lua print(vim.inspect({a = 5, b = "hello"}))
-- The output will be:
-- { a = 5, b = 'hello' }

• 在 Fennel 代码中

(vim.inspect {:a 5 :b "hello"})

plugin/ 目录下的文件在 Neovim 启动时立即加载, 无论你打开什么文件类型. 这些文件通常用于设置全局键绑定, 命令或自动命令 (autocmd), 并且这些配置应该始终处于活动状态.

ftplugin/ 目录下的文件仅在 Neovim 识别到特定文件类型 (filetype) 时才加载. 例如, ~/.config/nvim/ftplugin/lua.lua 仅在编辑 Lua 文件时才会执行. 这些文件适用于设置特定语言的键绑定, 缓冲区局部选项或自动命令.

after/plugin/ 目录下的文件仅在 plugin/ 目录下的文件加载完成后才会执行. 这是一个非常重要的概念; 它提供了一种覆盖或修改其他插件设置的机制.

例如, 如果你想修改一个在 plugin/ 目录下的插件设置的全局键绑定, 你可以在 after/plugin/ 目录下创建一个文件来重新定义它. 这确保了你的设置在插件的默认设置之后加载, 从而成功覆盖它们.

简单来说, plugin 用于全局设置, ftplugin 用于特定文件类型, 而 after/plugin 则在所有默认插件加载后提供了一个自定义或覆盖设置的机会. 理解这个执行顺序可以帮助你更有效地管理和调试你的 Neovim 配置.

为了让 Fennel 程序与 Neovim 协同工作, 我们主要需要克服两个挑战:

1. Neovim 实际上不理解 Fennel, 因为它只有一个内置的 Lua Runtime. 因此, 我们必须将 Fennel 编译成 Lua.
2. 在 Neovim 内部, 有一个名为 runtimepath 的变量, 它根据该变量内的路径来查找要加载和执行的 Lua 文件. 更准确地说, 我们必须将我们的 Lua 代码放在 runtimepath 变量指向的文件夹下的 /lua 子目录中, Neovim 才能找到我们的代码.

为了编译方便, 我们需要安装另一个插件: nfnl

安装方法:

• 打开文件 ~/.config/nvim/init.vim
• 在文件中找到由 plug#begin 和 plug#end 包围的部分, 并添加 nfnl 安装命令.

call plug#begin(stdpath('data') . '/plugged')
...
" === Fennel (Config) Support ===
Plug 'Olical/nfnl'
...
call plug#end()

• 接下来, 在 Neovim 的 Normal Mode 下, 执行以下命令:

:source %
:PlugInstall

• 此外, 因为自动编译插件的命令与 fnlfmt 有些冲突, 我们必须修改 ~/.config/nvim/init.vim 中的 FennelOnSave 设置. 将其更改如下:

augroup FennelOnSave
  " Format and compile after save
  autocmd!
  autocmd BufWritePost *.fnl call Fnlfmt() | NfnlCompileFile
augroup END

安装并设置好这个 nfnl 插件后, 如果我们稍后编辑 $path/fnl/some_file.fnl 并保存文件, 该插件会自动生成一个对应的 $path/lua/some_file.lua 文件.

首先, 我们可以使用以下 Neovim Ex 命令来查看 runtimepath.

set runtimepath?

结果是:

runtimepath=~/.config/nvim, ...

因此, 我们可以知道放在 ~/.config/nvim/lua 文件夹中的 Lua 文件可以被 Neovim 读取.

回想一下, 之前在 day06, 当我们安装 LuaRocks 时, 我们也把我们手写的 luarocks.lua 放在了 ~/.config/nvim/lua 文件夹中.

让我们考虑另一个关键问题: “如果编译后的 Lua 文件应该放在 ~/.config/nvim/lua 文件夹中, 那么对应的 Fennel 文件呢?” 自然, 它们应该放在 ~/.config/nvim/fnl 文件夹中.

重写 src/websocket/server_ev.lua 以便它可以在 Neovim 中运行. 注意: 原始实现依赖于四个库: ev, loop, websocket.ev_common, socket. 请移除对这些库的依赖, 转而使用 vim.uv. …

提示 1 生成的代码大部分是可用的, 但其中一个函数 message_io 是一个严重的幻觉, 而这个幻觉相当合理, 因为我没有注意到 websocket.ev_common 实际上是 server_ev.lua 本身的一个主要部分, 而不是一个外部依赖.

因此, 我用了第二个提示来纠正这个问题.

考虑 src/websocket/ev_common.lua 中的 message_io, 它依赖于 lua ev 的 loop. 请重构 message_io, 并将 message_io 中的 sock 改为 vim.uv 中 uv.new_tcp() 的返回值, 意思是这个 sock 有像 read_start, write 这样的函数可以调用. …

经过两个提示后, 我进行了一些简单的手动调试, WebSocket 连接就建立起来了.

克服了这个障碍后, 我重新设计了我的提示, 在原始提示后添加了一段来引导 LLM 的思考:

在尝试解决这个问题时, 请按以下顺序思考:

1. 所需功能是否是 spc476 库的设计者最初可能没有涵盖的场景?
2. 库的设计者是否已经为这种情况应用了松耦合机制, 允许用户稍后进行修改?
3. Lua 的松耦合机制有哪些?
4. 考虑了 1, 2 和 3 之后, lua.encode 应该如何调用?

当我用这个新的提示来要求 LLM 演示库调用时, LLM 的输出质量显著提高. 一些 LLM 甚至成功了; 即使是失败的, 也只差一步之遥.

在开发一个新项目时, 行走骨架是一种能快速减少不确定性的方法. 它的概念是: “先集成所有有副作用 (IO) 的组件, 然后再开发核心逻辑.” 一个更高级的行走骨架还包括从一开始就完成一键部署.

通过采用这种开发顺序, 一方面, 高度不确定的组件的集成被提前了, 所以系统中的整体不确定性在项目初期就迅速下降. 更重要的是, 一旦系统有了 UI, 非开发者协作者就可以加入项目提供反馈; 如果部署也到位了, 甚至可以及早收集到真实软件用户或客户的反馈.

虽然行走骨架是一种极其简单的方法, 但它能迅速减少不确定性, 并显著降低项目风险.

在规划许多系统时, 常常发现某些需要的模块不存在, 但它们在其他平台上存在. 在这种情况下, 我们可以采用移植作为减少不确定性的一种方式.

从其他平台移植模块可以说能迅速减少‘需求方向’的不确定性. 一般来说, 当我们谈论需求时, 这个词通常有两个含义: 一个是直接来自真实用户的需求. 另一个含义是由于外部用户需求而需要的 合理的模块接口. 设计合理的模块接口其实非常困难; 许多写在书中的经典接口设计都是无数前人尝试, 失败和改进的结果.

采用移植的方法可以将不确定性集中在软件实现和依赖上, 显著减少整体不确定性.

当发现某些需要的模块不存在时, 除了自己重新开发, 也可以考虑移植.

另一方面, 在软件开发过程中, 很多时候我们也有第三方库可以使用; 然而, 虽然第三方模块可以用, 但它们通常很难用.

什么时候会发生这种情况? 例如, 当使用像 Clojure 这样主要支持函数式编程的语言时, 如果我们需要使用不太常见的用例, 我们可能会求助于第三方库, 特别是纯 Java 库. 然而, Java 库的一个特点是它们带有大量的类型. 如果直接引用, 会让 Clojure 代码中充满 Java 类型.

在这种情况下, 一个更好的方法是剥离与包装: 在引用 Java 库之前, 逐层剥离, 直到找到一个还没有将数据转换成无数类型的层. 直接剥掉该模块的上层, 用 Clojure 语言重写它们.

这种方法允许利用第三方库 (减少不确定性), 同时确保它们不会污染整个系统.

剥离与包装的方法来自 Arne Brasseur 的一条推文:

Much of Clojure development is peeling back layers and layers of Java libraries to get to the bit that actually matters, then wrapping that in a tiny API layer over plain data.

邻近可能性 的一个关键特征在于其二元性: 它 既是约束也是机会.

• 作为约束: 系统的当前状态决定了你能去哪里. 你不能直接从一个 Java 项目跳到一个成熟复杂的 Rust 项目, 除非你先获得 Rust 知识, 找到相关库, 并完成架构验证. 现有的技术债, 团队技能和架构复杂性都限制了我们能有效探索的范围. 如果我们盲目地‘跃进’, 失败的概率会极高.
• 作为机会: 同时, 当前状态也是所有新可能性的来源. 你已经拥有的所有类, 函数, 接口和数据结构都是潜在的‘乐高积木’. 当你组合这些积木时, 一个新的, 可行的状态就会出现在你的 邻近可能性 中. 有效的开发策略是巧妙地使用现有的积木, 或引入最少量的外部积木, 来扩展这个空间.

从这个角度来看, 上述开发模式都可以被理解为系统地管理这些‘约束’和‘机会’:

• 行走骨架: 是一种通过尽早建立一个可工作的基础来 快速探索邻近可能性 的方法. 它首先稳定了最不确定的方面 (I/O, 部署), 将这些高风险的约束转变为稳定的基石. 这种新状态使得团队可以更安全地探索后续功能, 并从早期反馈中找到新的‘邻近可能性’方向.
• 移植: 是利用外部资源来战略性地扩展 邻近可能性 的边界. 它将其他领域经过验证的解决方案引入到我们的 邻近可能性 空间中, 直接绕过了需求方向的不确定性约束, 从而跳过了冗长的设计和试错过程.
• 剥离与包装: 也是一种利用外部资源 (机会) 的方法, 同时小心地 管理外部依赖带来的约束. 通过创建一个薄的 API 层, 它将外部组件转变为符合系统自身风格的新工具, 防止 邻近可能性 空间被混乱的外部依赖所污染, 并确保系统的内部一致性.

总而言之, 这些策略不仅仅是技术实践, 而是系统地管理不确定性并在 邻近可能性 空间内加速有效探索的方法. 它们的核心思想是: 首先建立一个稳定的基石, 将约束转化为机会, 然后有组织, 有目标地逐步扩展到下一个可行的状态, 而不是盲目地闯入未知.

容器/展示者模式是 React 前端开发中常见的设计方法. 其核心思想是分离“做什么”和“怎么做”, 使代码结构更清晰, 更易于维护.

• 容器 (Container) 负责“显示什么”和“交互发生后做什么”. 它管理状态, 处理逻辑, 并决定需要触发哪些事件. 换句话说, 容器回答的是 What to display 的问题.
• 展示者 (Presenter) 专注于“屏幕应该如何显示”. 它完全根据 props 来渲染 UI, 并将事件传递给注入的处理程序; 至于数据来源和事件语义, 它完全不关心. 展示者回答的是 How to display 的问题.

当一个复杂的 UI 被拆分成这两个角色时, what/how 分离的好处变得非常直观:

• 了解“屏幕需要什么数据, 点击后会发生什么” — 看容器.
• 了解“这些数据是如何呈现的, 按钮长什么样” — 看展示者.

这种分离简化了每个组件的职责, 从而大大降低了理解代码的难度.

领域特定语言 (DSL) 和解释器模式的结合是 what/how 分离的另一个经典体现. 这就像设计一种专门的语言 (DSL) 来描述一个问题, 然后用一个解释器来执行它.

Tree-sitter 是一个用于解析代码语法的库, 它完美地体现了这一概念.

• what (查询语言): Tree-sitter 提供了一种强大的查询语言, 允许你使用类似 CSS 选择器的语法来描述你想在抽象语法树 (AST) 中找到什么. 例如, 你可能会写 (function_declaration name: (identifier) @name) 来描述“我想找到所有函数声明并捕获它们的名称.” 这个查询本身就是一个 DSL; 它清楚地定义了你想要什么, 而不需要关心底层的搜索算法.
• how (执行引擎): Tree-sitter 的核心引擎负责解释和执行你的查询. 它知道如何遍历语法树, 如何匹配节点类型, 如何处理命名捕获 (@name) 等等. 对用户来说, 当查询语言始终正常工作时, 他们可以完全忽略执行引擎的实现.

换句话说, 当你使用 Tree-sitter 时, 你只专注于描述你的需求 (what), 即你想从代码中提取什么信息. 至于这个需求是如何实现的 (how), 则完全由底层引擎处理. 这种模式让你只需几行查询就能轻松完成复杂的代码分析任务, 而无需深入研究底层算法的细节.

当我们使用传输协议 (例如, HTTP, gRPC) 作为不同服务或模块之间的接口时, 它提供了一个天然的隔离层. 服务 A 只需要知道如何根据商定的传输协议与服务 B 通信; 它不需要关心服务 B 内部是如何实现的.

如果今天服务 B 由于性能问题需要从 Node.js 重写为 Go 语言, 只要它提供给服务 A 的传输协议保持不变, 服务 A 就完全不需要任何修改. 这是“*对于消费者, 边界允许替换生产者*”的最佳例子. 服务 B 的内部实现改变了, 但对于服务 A, 边界 (传输协议) 是稳定的, 修改没有传播. 这种机制在微服务架构中尤其常见, 允许每个服务独立开发, 部署和扩展.

这个概念不仅限于服务之间的通信. 在单体应用中, 接口 可以扮演同样的角色. 当一个模块 (消费者) 依赖于一个接口而不是一个具体的类实现 (生产者) 时, 你可以自由地替换底层的实现而不影响消费者. 这正是依赖注入的结构基础.

EDN (Extensible Data Notation) 是 Clojure 生态系统中常用的可扩展数据格式. 它类似于 JSON 或 XML, 但其最关键的优点是允许你使用标签来扩展数据类型.

例如, 你可以在 EDN 格式中自定义一个 #date 标签来表示日期, 当数据传输时, 它会以类似 #date "2025-09-24" 的格式出现. 接收端看到这个标签后, 就知道这是一个日期, 并可以将其恢复为相应的数据类型.

这种机制完美地体现了“*对于生产者, 边界允许注入新的实现*”的概念.

假设你的系统今天需要处理一种新的数据类型; 你不需要修改现有的架构或数据格式. 你只需要在 EDN 格式中定义一个新的标签, 并在接收端添加处理这个标签的代码. 这样, 新的数据类型可以通过微小的改动添加进来, 而无需大幅改动系统架构, 让你可以在不大动干戈地修改旧系统的情况下逐步扩展功能, 有效地防止了修改传播.

类似的概念也出现在 策略模式 中. 在这个模式中, 系统的核心部分 (例如, 一个支付处理模块) 定义一个接口, 但具体的支付方式 (如信用卡, PayPal, Apple Pay) 则作为不同的类实现. 当需要添加新的支付方式时, 你只需要添加一个新的实现类, 而无需修改核心处理模块的代码.

以软件项目交接为例, 这极大地需要流程的辅助. 一个好的流程可以有效地帮助接手工作的人快速避开所有坑, 确保隐性知识能够被转移.

一个简单的项目交接流程可以是:

1. 确保新人可以在本地建立项目.
2. 确保新人在本地进行基本测试.
3. 确保新人知道如何部署项目.
4. 确保新人知道如何在生产环境中调试.

如果标准流程要求将上述所有内容逐一执行并记录下来, 交接过程就可以避免许多旧的陷阱或及早发现新的陷阱, 从而减少未来的风险.

在软件中, 经常发生软件和文档都没有改变, 但构建失败, 部署失败的情况. 这是因为一些依赖版本已经更新, 或者一些用于部署的操作系统已经寿终正寝. 遇到这些陷阱时, 原项目开发者的隐性知识立刻就发挥了作用.

除了流程, 将隐性知识显性化最直接的方式就是写文档. 然而, 文档常常模糊不清, 原因是缺乏对文档旨在传达的知识是为了满足不同情况需求的意识.

Diátaxis 是一种系统化的文档方法, 它根据读者的需求将文档类型分为四类:

• 教程 (Tutorials): 这些文档旨在引导读者从零开始, 一步步地完成一个具体的, 有意义的项目或任务. 它们回答的是“我该如何开始?”的问题.
• 操作指南 (How-to guides): 当读者已经知道他们想要实现什么目标, 但不知道具体步骤时, 这些文档就派上用场了. 它们回答的是“我该如何解决一个特定问题?”的问题.
• 技术参考 (Technical reference): 这些文档就像一本字典或百科全书, 详细说明了所有函数, 类, 接口, 命令或配置选项. 它们回答的是“这是什么?”的问题.
• 解释 (Explanation): 这些文档旨在提供宏观的背景知识和理解, 回答的是“为什么?”的问题.

通过区分这四种文档类型, 我们可以确保每份文档都为特定的读者和情况提供最有效的信息. 这样, 文档将不再是孤立的知识碎片, 而是成为帮助团队持续成长的系统化知识库.

除了手动编写文档, 现代 AI 工具的兴起为将隐性知识显性化提供了强大的技术途径. 传统上, 非正式文档容易散乱且易于过时, 但 RAG (Retrieval-Augmented Generation) 知识库工具改变了这一状况.

这些工具 (例如 Google NotebookLM) 的价值在于, 它们允许开发团队导入所有非结构化的知识碎片——包括会议记录, 旧代码, 设计文档, 甚至 Slack 聊天记录——来创建一个项目特定的知识索引.

这将隐性知识的转移从“人工搜索和综合”转变为“AI 驱动的快速检索和提炼”:

• 跨文档问答: 新工程师不再需要像大海捞针一样查找文档; 他们可以直接问 AI: “项目中 UserAuth 模块最初的设计意图是什么?” AI 会准确地引用所有来源的代码注释, 设计文档或历史讨论来回答这个“为什么”的问题.
• 代码与知识验证: RAG 工具不仅可以整理非正式讨论, 还可以将这些非正式知识 (例如, 某个设计决策) 与最新的代码状态进行比较, 指出潜在的语义矛盾或过时的描述, 以确保口头理论与实际操作的一致性.

通过基于 RAG 的知识库, 团队可以在不中断日常开发的情况下, 有效地将原本散落在开发者脑中且从未写下的“理论”转化为可查询, 可验证的显性知识, 从而大大降低隐性知识转移的成本和风险.

考虑到“不确定性”的挑战, Basecamp 提出了一种产品开发方法论 ShapeUp: 一个小组负责“塑造未来项目”; 而另一个小组则在六周的周期内负责“构建项目”. 我们也可以将其看作: 擅长处理不确定性挑战的团队是 塑造团队 (Shaping Team); 而在六周周期内工作的团队是 周期团队 (Cycle Team).

考虑到“复杂性”的挑战, 团队拓扑 (Team Topology) 提倡将团队分为流对齐团队 (Stream-aligned Teams) 和平台团队 (Platform Teams). 流对齐团队专注于单一的, 有价值的业务流程或产品; 他们是离客户最近的团队, 负责端到端地交付价值. 平台团队负责以“即服务 (as-a-Service)”的方式提供内部平台服务 (例如, 基础设施, 部署工具, 监控系统等), 允许流对齐团队自助使用. 这种分工的核心目的是减轻流对齐团队的认知负荷. 通过将复杂的底层技术细节委托给专业的平台团队, 流对齐团队可以更专注于业务逻辑和快速交付客户价值, 从而应对日益复杂的软件系统带来的挑战.

考虑到“变更传播”的挑战, 许多团队设有架构师角色, 他们在项目早期负责各种规划或技术选型, 以便即使后期发生变更传播, 仍然容易纠正或缓解.

通过专业化分工, 可以有效减少隐性知识转移的需求, 从而实现管理理论中所说的“让平凡的人做不平凡的事”.

Naur 所指的“理论”不是科学定律, 而是开发团队对以下两个方面的完整心智掌握 (Mental Grasp):

1. 代码如何工作的原理: 程序的各个部分是如何设计的, 它们如何相互作用, 以及在执行过程中它如何与机器互动.
2. 程序与其环境的关系: 代码如何反映现实世界的需求和约束, 以及环境中的哪些变化可能需要代码调整.

这个“理论”就是 Naur 所指的软件开发中的隐性知识. 它无法完全写进文档或代码注释, 只能通过经验, 对话和亲手实践来获得和维持.

因此, Naur 的论点为本文提到的“流程”和“文档”策略提供了哲学基础: 这些措施的真正目的是最大化地将团队共享的理论显性化和结构化, 并确保它能够在团队成员之间持续地被重构, 审查和转移.