golang多shell多命令参数自动补全插件carapace-bin的使用

简介

carapace-bin 是一个为多种 CLI 命令提供参数自动补全功能的 Golang 工具，支持多种 POSIX 和非 POSIX shell。

支持的Shell

• Bash
• Cmd (实验性)
• Elvish
• Fish
• Ion (实验性)
• Nushell
• Oil
• Powershell
• Tcsh (实验性)
• Xonsh
• Zsh

快速开始

安装

可以通过以下方式安装 carapace-bin：

# 使用go install安装
go install github.com/carapace-sh/carapace-bin/cmd/carapace@latest

# 或者使用brew安装
brew install carapace

基本使用示例

下面是一个简单的示例，展示如何为自定义命令添加自动补全功能：

package main

import (
	"github.com/carapace-sh/carapace-bin/pkg/actions"
	"github.com/carapace-sh/carapace-bin/pkg/actions/os"
	"github.com/carapace-sh/carapace-bin/pkg/carapace"
	"github.com/spf13/cobra"
)

func main() {
	var rootCmd = &cobra.Command{
		Use:   "mycmd",
		Short: "A demo command with carapace completion",
	}

	// 添加子命令
	var subCmd = &cobra.Command{
		Use:   "sub",
		Short: "A subcommand",
		Run: func(cmd *cobra.Command, args []string) {
			// 命令逻辑
		},
	}

	// 添加带补全的flag
	subCmd.Flags().StringP("file", "f", "", "specify a file")
	carapace.Gen(subCmd).FlagCompletion(carapace.ActionMap{
		"file": carapace.ActionFiles(), // 文件自动补全
	})

	// 添加带补全的位置参数
	subCmd.Flags().StringP("user", "u", "", "specify a user")
	carapace.Gen(subCmd).FlagCompletion(carapace.ActionMap{
		"user": os.ActionUsers(), // 用户自动补全
	})

	rootCmd.AddCommand(subCmd)

	// 执行命令
	carapace.Gen(rootCmd).Root().Execute()
}

为现有命令添加补全

carapace-bin 已经为许多常用命令提供了内置补全支持。要为这些命令启用补全，只需运行：

# 为git命令启用补全
carapace --setup git

# 为docker命令启用补全
carapace --setup docker

自定义补全示例

下面是一个更复杂的自定义补全示例：

package main

import (
	"github.com/carapace-sh/carapace-bin/pkg/actions"
	"github.com/carapace-sh/carapace-bin/pkg/carapace"
	"github.com/spf13/cobra"
)

func main() {
	var rootCmd = &cobra.Command{
		Use:   "complex",
		Short: "A command with complex completion",
	}

	var subCmd = &cobra.Command{
		Use:   "action",
		Short: "Perform an action",
		Args:  cobra.MinimumNArgs(1),
		Run: func(cmd *cobra.Command, args []string) {
			// 命令逻辑
		},
	}

	// 自定义补全函数
	carapace.Gen(subCmd).PositionalCompletion(
		carapace.ActionCallback(func(c carapace.Context) carapace.Action {
			// 根据上下文动态生成补全选项
			return carapace.ActionValuesDescribed(
				"start", "Start the service",
				"stop", "Stop the service",
				"restart", "Restart the service",
				"status", "Show service status",
			)
		}),
	)

	// 带条件的补全
	subCmd.Flags().StringP("type", "t", "", "specify type")
	carapace.Gen(subCmd).FlagCompletion(carapace.ActionMap{
		"type": carapace.ActionValues("dev", "prod", "test"),
	})

	// 根据flag值改变位置参数的补全
	carapace.Gen(subCmd).PositionalAnyCompletion(
		carapace.ActionCallback(func(c carapace.Context) carapace.Action {
			if typeFlag := subCmd.Flag("type").Value.String(); typeFlag != "" {
				switch typeFlag {
				case "dev":
					return carapace.ActionValues("debug", "log", "trace")
				case "prod":
					return carapace.ActionValues("deploy", "rollback", "scale")
				case "test":
					return carapace.ActionValues("unit", "integration", "e2e")
				}
			}
			return carapace.ActionValues()
		}),
	)

	rootCmd.AddCommand(subCmd)
	carapace.Gen(rootCmd).Root().Execute()
}

高级功能

carapace-bin 还支持更高级的功能，如：

• 多级补全
• 依赖补全
• 动态补全
• 条件补全

可以通过官方文档了解更多高级用法。