Fish Shell 自定义命令补全功能详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01179/article/details/148360074

Fish Shell 自定义命令补全功能详解

fish-shell The user-friendly command line shell. 项目地址: https://gitcode.com/gh_mirrors/fi/fish-shell

前言

Fish Shell 作为一款现代化的命令行 shell，提供了强大的命令补全功能。本文将深入讲解如何为 Fish Shell 编写自定义命令补全，帮助开发者扩展 shell 的功能性。

基础补全语法

在 Fish Shell 中，complete 命令是定义补全的核心工具。其基本语法结构为：

complete -c 命令名 [选项]

例如，为 myprog 命令添加补全：

complete -c myprog -a 'start stop'

这会在用户输入 myprog 后按 Tab 键时，提供 start 和 stop 两个补全选项。

参数类型处理

选项参数补全

Fish Shell 支持三种类型的选项参数补全：

短选项（单字符）：-s
GNU 风格长选项：-l
传统风格长选项：-o

例如，为 myprog 定义 -o/--output 选项：

complete -c myprog -s o -l output

参数值补全

可以为选项指定可能的参数值：

complete -c myprog -s o -l output -a "yes no"

默认情况下，参数是可选的。如果需要强制参数，使用 -r 选项：

complete -c myprog -s o -l output -ra "yes no"

文件补全控制

默认情况下，Fish 会同时提供文件补全。可以通过以下方式控制：

全局禁用文件补全：
```
complete -c myprog -f
```

为特定选项禁用文件补全：

complete -c myprog -s o -l output --no-files -ra "yes no"

在全局禁用后为特定选项启用：

complete -c myprog -l config-file --force-files -r

条件补全

Fish 支持基于条件的补全，使用 -n 选项指定条件脚本：

complete -c myprog -n "__fish_seen_subcommand_from subcmd" -a "option1 option2"

实用函数

Fish 提供了一系列以 __fish_ 开头的实用函数：

__fish_complete_directories - 仅补全目录
__fish_complete_path - 路径补全
__fish_complete_groups - 用户组补全
__fish_complete_pids - 进程ID补全
__fish_complete_users - 用户补全
__fish_print_hostnames - 主机名补全
__fish_print_interfaces - 网络接口补全

补全文件存放位置

Fish 会自动从以下路径加载补全定义（按优先级排序）：

用户自定义补全：~/.config/fish/completions/
系统级补全：/etc/fish/completions/
第三方用户补全：~/.local/share/fish/vendor_completions.d/
第三方系统补全：/usr/share/fish/vendor_completions.d/
Fish 内置补全：/usr/share/fish/completions/
自动生成补全：~/.cache/fish/generated_completions/

补全文件命名规则为：命令名.fish

最佳实践示例

以下是一个完整的 timedatectl 命令补全示例：

# 定义所有子命令
set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp

# 全局禁用文件补全
complete -c timedatectl -f

# 主命令补全
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
    -a "status set-time set-timezone list-timezones"

# 时区设置补全
complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone" \
    -a "(timedatectl list-timezones)"

# 带描述的选项补全
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
    -a "set-local-rtc" -d "Maintain RTC in local time"

# 子命令特定选项
complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" \
    -l adjust-system-clock -d 'Synchronize system clock from the RTC'

# 全局选项
complete -c timedatectl -s h -l help -d 'Print a short help text and exit'
complete -c timedatectl -l version -d 'Print a short version string and exit'
complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager'