golang通过规范文件定义简单补全功能的插件库carapace-spec的使用

golang通过规范文件定义简单补全功能的插件库carapace-spec的使用

carapace-spec 是一个允许通过规范文件定义简单补全功能的Golang库，它基于carapace实现。

基本使用

下面是一个完整的YAML规范文件示例，展示了如何使用carapace-spec定义命令补全：

name: mycmd
description: my command
flags:
  --optarg?: optarg flag  # ?表示可选参数
  -r, --repeatable*: repeatable flag  # *表示可重复参数
  -v=: flag with value  # =表示需要值的参数
persistentflags:
  --help: bool flag
completion:
  flag:
    optarg: ["one", "two\twith description", "three\twith style\tblue"]  # 定义补全选项
    v: ["$files"]  # 使用$files宏补全文件
commands:
- name: sub
  description: subcommand
  completion:
    positional:
      - ["$list(,)", "1", "2", "3"]  # 使用$list宏定义列表补全
      - ["$directories"]  # 使用$directories宏补全目录

功能说明

  1. 标志定义:

    • --optarg?: 可选参数标志
    • -r, --repeatable*: 可重复标志
    • -v=: 需要值的标志

  2. 补全定义:

    • 可以为标志定义静态补全选项(如optarg)
    • 可以使用预定义宏(如$files, $directories)
    • 支持带描述和样式的补全项(如"two\twith description")

  3. 子命令:

    • 可以定义子命令及其补全
    • 支持位置参数的补全

完整Golang示例

下面是一个完整的Golang程序示例，展示如何使用carapace-spec:

package main

import (
	"fmt"
	"os"

	"github.com/carapace-sh/carapace-spec/pkg/action"
)

func main() {
	// 加载规范文件
	spec, err := action.LoadSpec("path/to/spec.yaml")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// 执行补全
	if len(os.Args) > 1 && os.Args[1] == "complete" {
		action.Complete(spec)
		return
	}

	// 正常命令逻辑
	fmt.Println("命令执行中...")
}

生成器

carapace-spec还提供了一些生成器，可以从其他库自动生成规范文件:

  • carapace-spec-clap: 为clap-rs/clap生成规范
  • carapace-spec-kingpin: 为alecthomas/kingpin生成规范
  • carapace-spec-kong: 为alecthomas/kong生成规范
  • carapace-spec-man: 从manpage生成规范
  • carapace-spec-urfavecli: 为urfave/cli生成规范
  • carapace-spec-oclif: 为oclif生成规范

注意：虽然可以使用carapace-spec二进制来补全规范文件，但推荐使用carapace-bin，因为它支持更多自定义宏。


更多关于golang通过规范文件定义简单补全功能的插件库carapace-spec的使用的实战教程也可以访问 https://www.itying.com/category-94-b0.html

1 回复

更多关于golang通过规范文件定义简单补全功能的插件库carapace-spec的使用的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


使用carapace-spec创建Golang命令行补全插件

carapace-spec是一个用于为Golang命令行工具创建补全功能的库，它允许你通过YAML规范文件定义补全行为，而无需编写大量代码。下面我将介绍如何使用carapace-spec创建简单的补全功能。

安装

首先安装carapace-spec：

go get github.com/rsteube/carapace-spec

基本用法

1. 创建规范文件

创建一个YAML文件（例如completion.yaml）来定义你的命令行工具的结构和补全行为：

name: mytool
description: A simple command line tool
commands:
  - name: greet
    description: Greet someone
    flags:
      - name: --name
        description: Name to greet
        completions:
          static:
            - Alice
            - Bob
            - Charlie
    positional:
      - name: language
        description: Language to use
        completions:
          static:
            - English
            - Spanish
            - French

2. 集成到你的程序中

在你的Golang程序中集成补全功能：

package main

import (
	"os"

	"github.com/rsteube/carapace-spec/pkg/spec"
	"github.com/spf13/cobra"
)

func main() {
	rootCmd := &cobra.Command{
		Use:   "mytool",
		Short: "A simple command line tool",
	}

	// 添加greet子命令
	greetCmd := &cobra.Command{
		Use:   "greet",
		Short: "Greet someone",
		Run: func(cmd *cobra.Command, args []string) {
			name, _ := cmd.Flags().GetString("name")
			language := ""
			if len(args) > 0 {
				language = args[0]
			}
			// 实际业务逻辑
			println("Hello", name, "in", language)
		},
	}
	greetCmd.Flags().String("name", "", "Name to greet")
	rootCmd.AddCommand(greetCmd)

	// 加载补全规范
	spec.FromFile("completion.yaml").AddTo(rootCmd)

	if err := rootCmd.Execute(); err != nil {
		os.Exit(1)
	}
}

高级功能

动态补全

除了静态补全，你还可以定义动态补全：

commands:
  - name: list
    description: List items
    positional:
      - name: category
        description: Item category
        completions:
          command: mytool categories

条件补全

你可以根据已输入的参数值来定义条件补全：

commands:
  - name: deploy
    description: Deploy application
    flags:
      - name: --env
        description: Environment
        completions:
          static:
            - dev
            - staging
            - prod
    positional:
      - name: service
        description: Service to deploy
        completions:
          command: mytool services --env $env

更复杂的规范示例

name: mytool
description: A complex command line tool
commands:
  - name: db
    description: Database operations
    commands:
      - name: migrate
        description: Run database migrations
        flags:
          - name: --database
            description: Database name
            completions:
              command: mytool db list
          - name: --version
            description: Migration version
            completions:
              command: mytool db versions --database $database
        positional:
          - name: direction
            description: Migration direction
            completions:
              static:
                - up
                - down

构建和测试

  1. 构建你的程序：
go build -o mytool
  1. 测试补全功能：
# 测试greet命令的补全
./mytool greet --name <TAB>
# 应该显示Alice, Bob, Charlie

./mytool greet --name Alice <TAB>
# 应该显示English, Spanish, French

总结

carapace-spec提供了一种声明式的方法来为Golang命令行工具添加补全功能，主要优点包括：

  1. 通过YAML文件定义补全行为，与代码分离
  2. 支持静态和动态补全
  3. 可以基于已有输入值进行条件补全
  4. 与cobra框架无缝集成

这种方法特别适合中大型命令行工具，可以显著减少编写和维护补全代码的工作量。

回到顶部