Zsh 自动补全脚本入门

入门基础

zsh 如何补全一个命令

命令的补全方法保存在以下划线 _ 开头的补全文件中，这些文件通常保存在 $fpath 变量所指定的路径下。当然，我们也通过可以在 ~/.zshrc 文件中增加如下一行代码，从而给 $fpath 新增一个搜索路径。

fpath=(~/newdir $fpath)

补全文件的第一行定义如下所示：

#compdef foobar

上述这行代码表示本文件定义了为 foobar 命令进行自动补全的代码。

我们还可以直接使用 compdef （比如：在 ~/.zshrc 中）命令指定将哪个方法作为自动补全的补全方法，如下所示：

> compdef _function foobar

除此之外，我们还可以同时为多个命令指定同一个补全方法。

> compdef _function foobar goocar hoobar

甚至，还可以传递参数至补全方法中。

> compdef '_function arg1 arg2' foobar

更多细节参见 传送门 。

通用 GNU 命令补全

很多 GNU 命令都有着一套标准的方式来对选项的描述进行罗列显示（当使用 --help 选项时）。对于这些命令，我们可以使用 _gnu_generic 方法自动创建补全方法，如下所示：

> compdef _gnu_generic foobar

当然，也可以同时为多个命令指定 _gnu_generic 补全方法。

> compdef _gnu_generic foobar goocar hoodar

这行代码可以直接添加到 ~/.zshrc 中。

复制补全功能

假设我们希望一个命令 cmd1 具有与 cmd2 一样的补全功能，并且 cmd2 的自动补全功能已经定义好了，那么我们可以使用如下方式进行复制。

> compdef cmd1=cmd2

当我们为一个命令创建了一个 alias 时，使用这种方式可以完整复制原始命令的补全功能！

如何编写补全方法

那么，如何编写属于我们自己的补全方法呢？照葫芦画瓢是一种非常好的上手方式。我们可以阅读一些别人写的补全方法。在本机的文件系统下，我们可以通过 $fpath 环境变量去搜索已有的补全功能文件，比如： /usr/local/share/zsh/site-functions 。

我们可以看到有一个 _arguments 方法在这些补全功能文件中被大量使用。 _arguments 是一个可以快速实现简单补全功能的工具方法。本质上， _arguments 方法是对内置方法 compadd 进行了封装。内置方法 compadd 是将补全单词添加至命令行，并控制补全行为的关键方法。不过，在大多数情况下，我们都不需要使用 compadd 方法，因为 zsh 提供了大量类似 _arguments 、 _describe 这样的工具方法，简单易用。

对于非常简单的补全功能， _describe 方法甚至都够用了。

工具方法

本文仅罗列一部分常用的工具方法。完整的工具方法及其使用说明，参见 传送门 。

本节我们将简单介绍一部分常用的工具方法，下一节我们将介绍如何使用这些工具方法。

用于整体补全功能的工具方法

为单个单词进行复杂补全的方法

为指定类型的对象进行补全的方法

处理已缓存补全逻辑的方法

如果我们有大量的补全，可以将它们保存在缓存文件中，以便快速加载。

其他方法

Action

类似 _arguments 、 _regex_arguments 、 _alternative 、 _value 这样的工具方法，它都都可以有一系列的调用参数。不过这些参数都遵循了一些预定义格式（或规范）的字符串，我们称之为 参数格式 ，每个参数格式的最后一个参数/选项是 Action 部分。 Action 表示如何补全相应的参数 。Action 可以有多种类型：

注意：并不是所有的工具方法都可以使用所有类型的 Action。比如： _regex_arguments 、 _alternative 方法不能使用 ->STRING 类型。

基于 _describe 的简单补全功能

_describe 方法可用于 选项/参数的顺序和位置并不重要 的简单补全功能。我们只需要创建一个数组参数来持有选项及其描述信息，然后将这个数组参数作为一个参数传递给 _describe 。下面的例子中，创建了两个补全候选项 c 和 d ，并提供了描述信息（注意：代码应该定义在名为 _cmd 文件中，并位于 $fpath 的路劲下）：

#compdef cmd
local a -subcmds
subcmds=('c:description for c command' 'd:description for d command')
_describe 'command' subcmds

除此之外，我们还可以向 _describe 方法传入多个不同的列表，并使用 -- 进行分隔。

local -a subcmds topics
subcmds=('c:description for c command' 'd:description for d command')
topics=('e:description for e help topic' 'f:description for f help topic')
_describe 'command' subcmds -- topics

如果两个候选项的描述信息相同， _describe 会将两者合并到同一行，并确保所有候选项的描述信息列对齐。 _describe 方法可以用在 _alternative 、 _arguments 、 _regex_arguments 的参数格式中的 ACTION 部分。在这种情况下，我们必须将其与参数放在一起，如： 'TAG:DESCRIPTION:{_describe 'value' options'}

基于 _alternative 的补全功能

与 _describe 方法类似， _alternative 方法可用于 选项/参数的顺序和位置并不重要 的简单补全功能。与 _describe 方法不同， _alternative 方法并不使用固定的匹配项，而是调用其他方法来生成候选项。此外， _alternative 允许混合使用不同类型的补全候选项。

_alternative 方法的参数格式是 'TAG:DESCRIPTION:ACTION' 。其中， TAG 指定补全匹配项的类型； DESCRIPTION 表示补全候选项列表的描述信息； ACTION 则是前文所描述的一种 Action 类型（ _alternative 不支持 ->STRING 和 =ACTION 类型）。

_alternative 'arguments:custom arg:(a b c)' 'files:filename:_files'

_alternative 方法的第一个参数中加入了三个候选项 a 、 b 、 c ；第二个参数调用了 _files 方法来对文件路径进行补全。

我们可以将 _alternative 方法参数分成多行，使用 \ 进行换行。如下所示，为每个自定义参数添加了描述信息：

_alternative \
  'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))' \
  'files:filename:_files'

如果我们想把参数传递给 _files 方法，可以像下面一下直接包含进来：

_alternative \
  'args:custom arg:((a\:"description a" b\:"description b" c\:"description c"))'\
  'files:filename:_files -/'

如果想使用参数扩展来创建补全列表，我们需要使用双引号来引用 _alternative 方法的调用参数。如下所示为一个简单示例：

_alternative \
  "dirs:user directory:($userdirs)" \
  "pids:process ID:($(ps -A | awk '{print $1}'))"

在这种情况下，第一个调用参数添加了存储在 $userdirs 变量中的单词，第二个调用参数则执行 ps -A | awk '{print $1}' 来获取一系列的 PID 以作为补全候选项。在实际开发中，我们可以直接使用已有的 _pids 方法。

我们还可以在 ACTION 中使用其他的工具方法（如： _values ）来生成实现更加复杂的补全功能，如下所示为一个简单示例：

_alternative \
  "directories:user directory:($userdirs)" \
  'options:comma-separated opt: _values -s , letter a b c'

上述例子会对 $userdirs 中的项进行补全，同时也会对包含 a 、 b 、 c 的逗号分隔列表进行补全。注意：在 _values 方法前需要有一个初始的空格。

和 _describe 方法一样， _alternative 方法自身也可以作为 _arguments 、 _regex_arguments 等方法的调用参数中的 ACTION 部分。

基于 _arguments 的补全功能

通过调用 _arguments 方法，我们就能够实现复杂的补全功能。 _arguments 方法能够处理带有各种选项及常规参数的命令。与 _alternative ， _arguments 方法相似，它以格式化的字符串作为其调用参数。这些格式化参数能够指定选项及其对应的选项参数（如： -f filename ）、命令参数。

_arguments 方法的调用参数的基本参数格式为 -OPT[DESCRIPTION] ，如下所示为一个简单示例：

_arguments '-s[sort output]' '--l[long output]' '-l[long output]'

稍微复杂一点的 _arguments 方法的参数格式可以是 -OPT[DESCRIPTION]:MESSAGE:ACTION 。其中， MESSAGE 和 ACTION 的含义与上述 _alternative 中描述的一样。如下所示为一个简单示例：

_arguments '-f[input file]:filename:_files'

_arguments 方法的参数格式还可以是 N:MESSAGE:ACTION 。其中， N 表示第 N 个命令参数， MESSAGE 和 ACTION 还是和之前一样。如果省略 N ，则仅表示下一个命令参数（在已指定的参数之后）。如果在 N 的前面或后面加上冒号 : ，则表示参数是可选的。如下为一个简单的示例：

_arguments '-s[sort output]' '1:first arg:_net_interfaces' '::optional arg:_files' ':next arg:(a b c)'

上面这个例子中，第一个参数是网络接口名，下一个可选参数是一个文件名，最后一个参数是 a 、 b 、 c 其中之一， s 选项可以在任意位置进行补全。

_arguments 方法支持上述所有类型的 ACTION 。这样的话，我们可以使用 case 分支来调用不同的 Action。

_arguments '-m[music file]:filename:->files' '-f[flags]:flag:->flags'
case "$state" in
    files)
        local -a music_files
        music_files=( Music/**/*.{mp3,wav,flac,ogg} )
        _multi_parts / music_files
        ;;
    flags)
        _values -s , 'flags' a b c d e
        ;;
esac

在这个例子中，music file 的路径调用 _multi_parts 方法来进行目录补全；flags 则可以调用 _value 方法，以逗号 , 分隔列表的形式进行补全。

本节，我们简单地介绍了 _arguments 方法的基本使用方法，当然，我们还可以指定互斥选项、重复选项/参数、以 + 开头而非 - 开头的选项等等。更多的使用方法，可以参见 官方教程 。此外，还可以参考本文末尾提到的教程。

基于 _regex_arguments 和 _regex_words 的补全功能

如果我们有一个复杂的命令行格式，它有多种可能的参数序列，那么 _regex_arguments 方法可能就是一个比较适合的补全方法。

_regex_arguments 方法会创建一个补全方法，补全方法的名字由第一个调用参数指定。因此，我们需要先调用 _regex_arguments 方法来创建补全方法，然后再调用该补全方法。如下所示：

_regex_arguments _cmd OTHER_ARGS..
_cmd "$@"

上述例子中， OTHER_ARGS 用于匹配并补全命令行中的单词，其可以是多个调用参数列表。这些调用参数列表可以用 '|' 进行二选一。我们还可以使用括号来指定选择的层级，不过，括号必须使用斜杠 \ 或引号 '' 进行转义， 如： \( 、 \) 或 '(' 、 ')' 。

如下所示为一个简单示例：

_regex_arguments _cmd SEQ1 '|' SEQ2 \( SEQ2a '|' SEQ2b \)
_cmd "$@"

上述例子中，指定了一个与 SEQ1 或 SEQ2 （后跟 SEQ2a 或 SEQ2b ）相匹配的命令行。这本质上就是使用正则表达式描述命令行的参数。

每个调用参数列表之前必须包含一个 /PATTERN/ 部分，后跟一个可选的 :TAG:DESCRIPTION:ACTION 部分。

每个 PATTERN 是一个正则表达式，用于匹配命令行上的一个单词。这些模式（pattern）会被顺序处理，直到遇到一个不匹配的模式，此时将执行对应的 Action 以得到该单词的补全项。

注意，必须要有一个模式来匹配命令自身。后面，我们将进一步介绍 PATTERN 。

_regex_arguments 方法参数中 :TAG:DESCRIPTION:ACTION 部分的含义与 _alternative 方法参数类似，不同的地方在于 _regex_arguments 中开头多了一个 : ，此外，它还允许调用所有的 Action 类型。

如下所示为一个简单示例：

_regex_arguments _cmd /$'[^\0]##\0'/ \( /$'word1(a|b|c)\0'/ ':word:first word:(word1a word1b word1c)' '|'\
   /$'word11(a|b|c)\0'/ ':word:first word:(word11a word11b word11c)' \( /$'word2(a|b|c)\0'/ ':word:second word:(word2a word2b word2c)'\
   '|' /$'word22(a|b|c)\0'/ ':word:second word:(word22a word22b word22c)' \) \)
_cmd "$@"

在这个例子中，第一个单词可以是 word1 （后跟 a 、 b 、 c 中的任意一个）或 word11 （后跟 a 、 b 、 c 中的任意一个）；如果第一个单词包含 11 ，那么第二个单词可以是 word2 （后跟 a 、 b 、 c 中的任意一个）或文件名。

这个例子看起来太复杂了，有一种简单的方式是使用 _regex_words 方法为 _regex_arguments 创建方法调用参数。

模式

我们可能注意到上面这个示例中， /PATTERN/ 看上去并不像正常的正则表达式。这里的字符串参数采用 $'foo\0' 的形式，通过这种形式将字符串中的 \0 解释为 null 字符，从而对参数内容进行单词分隔。如果我们没有在模式的末尾添加 \0 ，则可能无法匹配下一个单词。如果要在模式中使用变量的内容，我们可以给它添加双引号，以便对其进行扩展，然后再在后面添加一个含有 null 字符的字符串，如： "$somevar"$'\0' 。

模式的正则表达式语法似乎与普通的正则表达式有些不同。虽然没有找到相应的说明文档，但是能够总结出以下特殊字符的用法：

_regex_words

_regex_words 方法使得我们可以更容易地为 _regex_arguments 方法创建调用参数。 _regex_words 方法的结果可以存储在一个变量中，从而能够作为 _regex_arguments 方法的调用参数。

使用 _regex_words 创建 _regex_arguments 的调用参数时，需要向其提供一个标签，其次是描述信息，接着是描述各个单词的参数格式。参数格式为 WORD:DESCRIPTION:SPEC ，其中 WORD 表示要补全的单词， DESCRIPTION 表示描述信息， SPEC 可以是 _regex_words 创建的另一个变量，用于指定当前单词之后的单词，如果当前单词之后没有其他单词，则为空白。如下所示为一个简单的例子：

_regex_words firstword 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word'

_regex_words 方法执行的结果会被存储在 $reply 数组中，因此我们需要在 $reply 的值改变之前将其保存到其他数组中，如下所示：

local -a firstword
_regex_words word 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word'
firstword="$reply[@]"

基于此，我们可以这样调用 _regex_arguments 方法：

_regex_arguments _cmd /$'[^\0]##\0'/ "${firstword[@]}"
_cmd "$@"

这里我们来为初始命令添加了一个其他的模式。

下面是一个更加复杂的例子，我们为命令行中不同的单词调用 _regex_words 方法。

local -a firstword firstword2 secondword secondword2
_regex_words word1 'The second word' 'woo:tang clan' 'hoo:not me'
secondword=("$reply[@]")
_regex_words word2 'Another second word' 'yee:thou' 'haa:very funny!'
secondword2=("$reply[@]")
_regex_words commands 'The first word' 'foo:do foo' 'man:yeah man' 'chu:at chu'
firstword=("$reply[@]")
_regex_words word4 'Another first word' 'boo:scare somebody:$secondword' 'ga:baby noise:$secondword'\
 'loo:go to the toilet:$secondword2'
firstword2=("$reply[@]")

_regex_arguments _hello /$'[^\0]##\0'/ \( "${firstword[@]}" '|'  "${firstword2[@]}" \)"
_hello "$@"

在上面这个例子中，第一个单词可以是 foo 、 man 、 chu 、 boo 、 ga 、 loo 其中之一。如果第一个单词是 boo 或 ga ，那么第二个单词可以是 woo 或 hoo 。如果第一个单词是 loo 那么第二个单词可以是 yee 或 haa ，其他情况下没有第二个单词。

我们可以看一下 _ip 方法的具体实现，其内部很好地运用了 _regex_words 方法。

基于 _values 、 _sep_parts 、 _multi_parts 的复杂补全功能

_values 、 _sep_parts 、 _multi_parts 方法可以单独使用，也可以在 _alternative 、 _arguments 、 _regex_arguments 方法的调用参数的 ACTION 中使用。

如下所示是使用空格分隔 mp3 文件列表的例子：

_values 'mp3 files' ~/*.mp3

如下所示是使用逗号分隔 session id 列表的例子：

_values -s , 'session id' "${(uonzf)$(awk '{print $1}')}"

如下所示是补全 foo@news:woo 、 foo@news:laa 或 bar@news:woo 等的例子：

_sep_parts '(foo bar)' @ '(news ftp)' : '(woo laa)'

如下所示是一次补全 MAC 地址的例子：

_multi_parts : '(00:11:22:33:44:55 00:23:34:45:56:67 00:23:45:56:67:78)'

使用 compadd 直接添加补全单词

为了更准确地进行控制，我们可以使用内置的 compadd 方法直接添加补全单词。这个方法有很多不同的参数，用于控制如何显示补全以及单词补全后如何更改命令行上的文本。更多信息可以查看官方文档 传送门 。这里只给出一些简单的示例。

在可能的补全列表中添加单词：

compadd foo bar blah

和上面例子一样，区别在于会额外显示解释信息：

compadd -X 'Some completions' foo bar blah

和第一个例子一样，区别在于会在自动补全的单词之前插入前缀 what_ ：

compadd -P what_ foo bar blah

和第一个例子一样，区别在于会在自动补全的单词之后插入后缀 _todo ：

compadd -S _todo foo bar blah

和第一个例子一样，区别在于当在后缀之后输入空白字符时，会自动删除 _todo 后缀：

compadd -P _todo -q foo bar blah

将 $wordsarray 数组中的单词添加至可能的补全列表中：

compadd -a wordsarray

测试与调试

重载补全方法：

> unfunction _func
> autoload -U _func

下面这些方法能够提供一些有用的信息。

注意事项

请记住，在包含补全方法的文件的开头应该包含 #compdef 这一行。

请注意对 _arguments 、 _regex_arguments 方法的参数格式使用正确的引号类型：如果在参数格式中需要扩展参数，请使用双引号，否则请使用单引号。

检查 _arguments 、 _alternative 、 _regex_arguments 的参数格式中的冒号 : 数量和位置是否正确。

在使用 _regex_arguments 方法是，请记住要包含一个初始模式以匹配命令自身。

请记住在 _regex_arguments 的任何 PATTERN 参数的末尾加上一个空字符 $'\0' 。

提示

有时候我们会遇到这样的情况：子命令后面只能有一个选项，而在子命令后输入 tab 键时，zsh 会自动补全此选项。如果我们希望它在补全之前列出其描述信息，则可以向 ACTION 中添加另一个空选项（如： \: ），例如： TAR:DESCRIPTION:((opt1\:"description for opt1" \:)) 。注意，这仅适用于其支持 ACTION 的工具方法（如： _arguments 、 _regex_arguments ）。

其他资料

一个关于 _arguments 方法的基本教程， 传送门 。

一个关于 _arguments 方法的高级教程， 传送门 。

zshcompsys 手册， 传送门 。