Golang 命令行和标志解析支持子命令插件库 Kingpin 的使用

Kingpin 是一个 Go 语言的命令行和标志解析库，支持流畅风格的 API 和类型安全的参数解析。它支持标志、嵌套命令和位置参数。

安装

$ go get github.com/alecthomas/kingpin/v2

简单示例

package main

import (
  "fmt"

  "github.com/alecthomas/kingpin/v2"
)

var (
  verbose = kingpin.Flag("verbose", "Verbose mode.").Short('v').Bool()
  name    = kingpin.Arg("name", "Name of user.").Required().String()
)

func main() {
  kingpin.Parse()
  fmt.Printf("%v, %s\n", *verbose, *name)
}

复杂示例（支持子命令）

package main

import (
  "os"
  "strings"
  "github.com/alecthomas/kingpin/v2"
)

var (
  app      = kingpin.New("chat", "A command-line chat application.")
  debug    = app.Flag("debug", "Enable debug mode.").Bool()
  serverIP = app.Flag("server", "Server address.").Default("127.0.0.1").IP()

  register     = app.Command("register", "Register a new user.")
  registerNick = register.Arg("nick", "Nickname for user.").Required().String()
  registerName = register.Arg("name", "Name of user.").Required().String()

  post        = app.Command("post", "Post a message to a channel.")
  postImage   = post.Flag("image", "Image to post.").File()
  postChannel = post.Arg("channel", "Channel to post to.").Required().String()
  postText    = post.Arg("text", "Text to post.").Strings()
)

func main() {
  switch kingpin.MustParse(app.Parse(os.Args[1:])) {
  // Register user
  case register.FullCommand():
    println(*registerNick)

  // Post message
  case post.FullCommand():
    if *postImage != nil {
    }
    text := strings.Join(*postText, " ")
    println("Post:", text)
  }
}

主要特性

• 美观的帮助输出
• 可自定义的帮助模板
• 类型安全的标志和参数解析
• 支持任意深度的子命令
• 支持必需标志和必需位置参数
• 支持默认命令
• 每个命令、标志和参数的回调
• POSIX 风格的短标志组合
• 从文件读取命令行参数
• 自动生成 man 页面
• Bash/ZSH shell 自动补全

自定义解析器

Kingpin 支持自定义标志和位置参数的解析器。例如：

type HTTPHeaderValue http.Header

func (h *HTTPHeaderValue) Set(value string) error {
  parts := strings.SplitN(value, ":", 2)
  if len(parts) != 2 {
    return fmt.Errorf("expected HEADER:VALUE got '%s'", value)
  }
  (*http.Header)(h).Add(parts[0], parts[1])
  return nil
}

func (h *HTTPHeaderValue) String() string {
  return ""
}

func HTTPHeader(s kingpin.Settings) (target *http.Header) {
  target = &http.Header{}
  s.SetValue((*HTTPHeaderValue)(target))
  return
}

使用方式：

headers = HTTPHeader(kingpin.Flag("header", "Add a HTTP header to the request.").Short('H'))

重复标志

某些标志可以重复使用，这取决于它们持有的 Value 类型。Value 的 IsCumulative() bool 函数决定了是否可以多次调用 Set()。

布尔值

布尔值在 Kingpin 中有特殊处理。每个布尔标志都有一个对应的否定标志：--<name> 和 --no-<name>。

默认值

默认值是类型的零值。可以通过 Default(value...) 函数覆盖默认值。

Shell 自动补全

Kingpin 内置支持 Bash/ZSH shell 自动补全。可以通过以下方式生成补全脚本：

$ your-cli-tool --completion-script-bash
$ your-cli-tool --completion-script-zsh

自定义帮助

Kingpin 支持使用 Go 的 text/template 库自定义帮助输出。有四种内置模板：

1. kingpin.DefaultUsageTemplate - 默认模板
2. kingpin.CompactUsageTemplate - 更紧凑的表示
3. kingpin.SeparateOptionalFlagsUsageTemplate - 将必需和可选标志分开
4. kingpin.ManPageTemplate - 用于生成 man 页面

示例：带子命令的 CLI 工具

package main

import (
  "fmt"
  "os"

  "github.com/alecthomas/kingpin/v2"
)

var (
  app        = kingpin.New("myapp", "A command-line application.")
  debug      = app.Flag("debug", "Enable debug mode.").Bool()
  serverAddr = app.Flag("server", "Server address.").Default("localhost:8080").String()

  // Add command
  addCmd     = app.Command("add", "Add a new item.")
  addItem    = addCmd.Arg("item", "Item to add.").Required().String()
  addForce   = addCmd.Flag("force", "Force addition.").Short('f').Bool()

  // Delete command
  deleteCmd     = app.Command("delete", "Delete an item.")
  deleteItem    = deleteCmd.Arg("item", "Item to delete.").Required().String()
  deleteConfirm = deleteCmd.Flag("confirm", "Confirm deletion.").Short('y').Bool()
)

func main() {
  cmd := kingpin.MustParse(app.Parse(os.Args[1:]))

  fmt.Printf("Debug: %v\n", *debug)
  fmt.Printf("Server: %s\n", *serverAddr)

  switch cmd {
  case addCmd.FullCommand():
    fmt.Printf("Adding item: %s (force: %v)\n", *addItem, *addForce)
  
  case deleteCmd.FullCommand():
    fmt.Printf("Deleting item: %s (confirmed: %v)\n", *deleteItem, *deleteConfirm)
  }
}

这个示例展示了如何创建一个支持子命令的 CLI 工具，包括全局标志、子命令特定的标志和参数。