bash-completor：声明式编写 Bash 补全脚本

[adoyle]

编写简单的 Bash 补全脚本仅需一行。可对于拥有许多复杂参数的命令来说，这就不够用了。开发者需要编写可编程补全脚本。

可是，编写复杂的可编程补全脚本却是一件困难的事。Bash 脚本的语法十分自由（容易出错），教程也五花八门，你可能需要踩很多坑。 即使有 scop/bash-completion 这样现成的补全脚本库，可是它只收录常用命令。对于某些社区不常用的命令，还是得自己手写补全脚本。

为了减少开发者接触 bash 的痛苦时间。我创造了 bash-completor。 bash-completor 是一个用 bash 脚本编写的 Bash 补全脚本生成器。帮助 bash 新手快速地实现 bash 补全。 它用声明式写法来实现逻辑。学习门槛非常低。

可能有人会想，bash 就一胶水语言，不应该用来写这么复杂的功能。为何不用 js 、go 、rust 等高级编程语言来实现补全逻辑？ 当然可以，只不过这会引入开发环境配置，依赖部署等问题。 需要使用 bash 补全功能的人一定安装了 bash 。所以用 Bash 脚本来写，不引入其他依赖。用户安装使用就很简单。

下面介绍这个工具。

功能

• 声明式编程。你只需要懂最基础的 bash 语法。
• 编译时只依赖 bash 和 sed 。运行时只依赖 bash 。无其他依赖。
• 支持命令格式如 <cmd> [options] [arguments]。
• 支持子命令。命令格式如 <cmd> [cmd-options] <subcmd> [subcmd-options] [arguments]。
• 支持 -o, --option, --option <value>, --option=, +o, +option 格式的参数。
• 支持补全文件或目录路径。
• 支持补全单词列表。
• 支持自定义补全函数。
• 友好的配置项填错检查和提示。

依赖

• 编译补全脚本时
  • Bash v4.3+
  • cat, sed (兼容 GNU 和 BSD)
• 运行补全脚本
  • Bash v4.0+

安装

你可以用 curl 或者 git 安装它。具体请看项目文档，这里不赘述。

用法

以创建 bash-completor 自身的补全脚本为例。

首先，创建配置文件 completor.bash 。 配置文件也是用 bash 语法写的。你只需要懂最基础的 bash 语法即可。

output=dist/bash-completor.completion.bash
authors=('ADoyle ([email protected])')
cmd=bash-completor
cmd_opts=(
  -c:@files
  -h --help
  --version
)

这就是配置的全部内容。然后执行 bash-completor -c ./completor.bash 生成补全脚本。完成。

复杂的例子也可以看这些链接：

• zig.completor.bash
• nvim-shell-completions/nvim.completor.bash
• 其他例子见 ./example/

更多语法见这个链接。

补全脚本

生成的补全脚本遵循以下代码风格。无需担心重名问题。而且这也便于在运行时调试。

• 主命令的补全函数必须是 _${cmd}_completions。
• 所有子命令的补全函数必须以 _${cmd}_completions_${subcmd} 为前缀命名。
• 其他所有的变量和函数都必须以 _${cmd}_comp_ 为前缀命名。
• 主命令的选项必须是 _${cmd}_comp_cmd_opts
• 子命令的选项必须以 _${cmd}_comp_subcmd_opts_${subcmd} 为前缀命名。
• 所有 reply 函数必须以 _${cmd}_comp_reply_ 为前缀命名。
• 所有自定义的 reply 函数必须以 _${cmd}_comp_reply_custom_ 为前缀命名。

以上介绍完了。如果你觉得不错，可以给文章点给赞，或者给项目点个 star 。

https://github.com/adoyle-h/bash-completor