Golang 支持复杂命令行解析与多格式配置解析插件库 Kong 的使用

Kong 是一个用于 Go 的命令行解析器，支持复杂的命令行结构和多种配置格式解析。

简介

Kong 旨在以最少的开发工作量支持任意复杂的命令行结构。它通过 Go 类型表示命令行，使用结构体和标签来指导如何将命令行映射到结构体。

基本示例

以下是一个简单的命令行示例，展示了如何使用 Kong 解析命令行参数：

package main

import "github.com/alecthomas/kong"

var CLI struct {
  Rm struct {
    Force     bool `help:"Force removal."`
    Recursive bool `help:"Recursively remove files."`

    Paths []string `arg:"" name:"path" help:"Paths to remove." type:"path"`
  } `cmd:"" help:"Remove files."`

  Ls struct {
    Paths []string `arg:"" optional:"" name:"path" help:"Paths to list." type:"path"`
  } `cmd:"" help:"List paths."`
}

func main() {
  ctx := kong.Parse(&CLI)
  switch ctx.Command() {
  case "rm <path>":
  case "ls":
  default:
    panic(ctx.Command())
  }
}

帮助系统

Kong 自动生成帮助文本，每个 Kong 应用程序都包含一个 --help 标志，可以显示自动生成的帮助信息。

查看帮助

$ shell --help
usage: shell <command>

A shell-like example app.

Flags:
  --help   Show context-sensitive help.
  --debug  Debug mode.

Commands:
  rm <path> ...
    Remove files.

  ls [<path> ...]
    List paths.

查看特定命令的帮助

$ shell --help rm
usage: shell rm <paths> ...

Remove files.

Arguments:
  <paths> ...  Paths to remove.

Flags:
      --debug        Debug mode.

  -f, --force        Force removal.
  -r, --recursive    Recursively remove files.

命令处理

Kong 提供了两种处理命令的方式：

1. 通过命令字符串切换

func main() {
  ctx := kong.Parse(&CLI)
  switch ctx.Command() {
  case "rm <path>":
  case "ls":
  default:
    panic(ctx.Command())
  }
}

2. 为每个命令附加 Run() 方法

type Context struct {
  Debug bool
}

type RmCmd struct {
  Force     bool `help:"Force removal."`
  Recursive bool `help:"Recursively remove files."`

  Paths []string `arg:"" name:"path" help:"Paths to remove." type:"path"`
}

func (r *RmCmd) Run(ctx *Context) error {
  fmt.Println("rm", r.Paths)
  return nil
}

type LsCmd struct {
  Paths []string `arg:"" optional:"" name:"path" help:"Paths to list." type:"path"`
}

func (l *LsCmd) Run(ctx *Context) error {
  fmt.Println("ls", l.Paths)
  return nil
}

var cli struct {
  Debug bool `help:"Enable debug mode."`

  Rm RmCmd `cmd:"" help:"Remove files."`
  Ls LsCmd `cmd:"" help:"List paths."`
}

func main() {
  ctx := kong.Parse(&cli)
  err := ctx.Run(&Context{Debug: cli.Debug})
  ctx.FatalIfErrorf(err)
}

钩子函数

Kong 支持以下钩子函数：

钩子函数示例：

type debugFlag bool

func (d debugFlag) BeforeApply(logger *log.Logger) error {
  logger.SetOutput(os.Stdout)
  return nil
}

var cli struct {
  Debug debugFlag `help:"Enable debug logging."`
}

func main() {
  logger := log.New(io.Discard, "", log.LstdFlags)
  ctx := kong.Parse(&cli, kong.Bind(logger))
  // ...
}

绑定选项

可以使用 Bind() 选项将值注入到 Run() 方法中：

type CLI struct {
  Debug bool `help:"Enable debug mode."`

  Rm RmCmd `cmd:"" help:"Remove files."`
  Ls LsCmd `cmd:"" help:"List paths."`
}

type AuthorName string

func (l *LsCmd) Run(cli *CLI) error {
  // 在这里使用 cli.Debug
  return nil
}

func (r *RmCmD) Run(author AuthorName) error {
  // 在这里使用绑定的 author
  return nil
}

func main() {
  var cli CLI
  ctx := kong.Parse(&cli, Bind(AuthorName("penguin")))
  err := ctx.Run()
}

标志(Flags)

任何未标记为 cmd 或 arg 的字段都将被视为标志。标志默认是可选的。

type CLI struct {
  Flag string
}

命令和子命令

子命令通过在结构体字段上标记 cmd 来指定。Kong 支持任意嵌套的命令。

type CLI struct {
  Command struct {
    Flag string

    SubCommand struct {
    } `cmd`
  } `cmd`
}

分支位置参数

结构体也可以配置为分支位置参数：

var CLI struct {
  Rename struct {
    Name struct {
      Name string `arg` // <-- 注意：与封闭结构体字段名相同
      To struct {
        Name struct {
          Name string `arg`
        } `arg`
      } `cmd`
    } `arg`
  } `cmd`
}

位置参数

如果字段标记为 arg:""，它将被视为要解析的命令行的最终位置值。默认情况下，位置参数是必需的，但指定 optional:"" 可以改变这一点。

切片(Slices)

切片值会被特殊处理。输入首先根据 sep:"<rune>" 标签（默认为 ,）分割，然后每个元素由切片元素类型解析并附加到切片中。

var CLI struct {
  Ls struct {
    Files []string `arg:"" type:"existingfile"`
  } `cmd`
}

映射(Maps)

映射类似于切片，但每个值只能分配一个键/值对，sep 标签表示赋值字符，默认为 =。

var CLI struct {
  Config struct {
    Set struct {
      Config map[string]float64 `arg:"" type:"file:"`
    } `cmd`
  } `cmd`
}

指针(Pointers)

指针的工作方式类似于底层类型，但可以区分零值和未提供值之间的差异。

var CLI struct {
	Foo *int
}

嵌套数据结构

Kong 支持带有 embed:"" 的嵌套数据结构：

var CLI struct {
  Logging struct {
    Level string `enum:"debug,info,warn,error" default:"info"`
    Type string `enum:"json,console" default:"console"`
  } `embed:"" prefix:"logging."`
}

自定义命名解码器

Kong 包含许多内置的自定义类型映射器，可以通过指定标签 type:"<type>" 来使用。

支持的字段类型

Kong 支持许多常见的 Go 类型：

自定义解码器(映射器)

任何实现 encoding.TextUnmarshaler 或 json.Unmarshaler 的字段都将使用这些接口来解码值。

支持的标签

标签可以有两种形式：

1. 标准 Go 语法，例如 kong:"required,name='foo'"
2. 裸标签，例如 required:"" name:"foo"

插件

Kong CLI 可以通过嵌入 kong.Plugin 类型并用指向 Kong 注释结构体的指针填充它来扩展：

var pluginOne struct {
  PluginOneFlag string
}
var pluginTwo struct {
  PluginTwoFlag string
}
var cli struct {
  BaseFlag string
  kong.Plugins
}
cli.Plugins = kong.Plugins{&pluginOne, &pluginTwo}

动态命令

Kong 还支持通过 kong.DynamicCommand() 动态添加命令。

变量插值

Kong 支持将有限的变量插值到帮助字符串、占位符字符串、枚举列表和默认值中。

变量形式：

${<name>}
${<name>=<default>}

type cli struct {
  Config string `type:"path" default:"${config_file}"`
}

func main() {
  kong.Parse(&cli,
    kong.Vars{
      "config_file": "~/.app.conf",
    })
}

验证

Kong 对命令行的结构进行验证，但也支持可扩展的验证。树中的任何节点都可以实现以下接口之一：

type Validatable interface {
    Validate() error
 }

或

type Validatable interface {
    Validate(kctx *kong.Context) error
 }

修改 Kong 的行为

每个 Kong 解析器都可以通过传递给 New(cli any, options...Option) 的功能选项进行配置。

配置选项

1. Name(help) 和 Description(help) - 设置应用程序名称描述
2. Configuration(loader, paths...) - 从配置文件加载默认值
3. Resolver(...) - 支持从外部源获取默认值
4. *Mapper(...) - 自定义命令行如何映射到 Go 值
5. ConfigureHelp(HelpOptions) 和 Help(HelpFunc) - 自定义帮助
6. 注入值到 Run() 方法中

完整示例

以下是一个完整的示例，展示了如何使用 Kong 创建一个支持多个命令和复杂参数的 CLI 应用程序：

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/alecthomas/kong"
)

var CLI struct {
	Debug bool `help:"Enable debug mode."`

	Add struct {
		User  string `arg:"" help:"User to add."`
		Group string `arg:"" help:"Group to add user to."`
	} `cmd:"" help:"Add a user to a group."`

	Remove struct {
		User  string `arg:"" help:"User to remove."`
		Group string `arg:"" help:"Group to remove user from."`
	} `cmd:"" help:"Remove a user from a group."`

	List struct {
		Group string `arg:"" optional:"" help:"Group to list users from."`
	} `cmd:"" help:"List users in a group."`

	Config struct {
		Set struct {
			Key   string `arg:"" help:"Config key to set."`
			Value string `arg:"" help:"Config value to set."`
		} `cmd:"" help:"Set a config value."`

		Get struct {
			Key string `arg:"" help:"Config key to get."`
		} `cmd:"" help:"Get a config value."`
	} `cmd:"" help:"Manage configuration."`
}

func main() {
	ctx := kong.Parse(&CLI,
		kong.Name("myapp"),
		kong.Description("A CLI application for managing users and groups."),
		kong.UsageOnError(),
		kong.ConfigureHelp(kong.HelpOptions{
			Compact: true,
		}),
		kong.Vars{
			"version": "0.1.0",
		},
	)

	switch ctx.Command() {
	case "add <user> <group>":
		fmt.Printf("Adding user %s to group %s\n", CLI.Add.User, CLI.Add.Group)
	case "remove <user> <group>":
		fmt.Printf("Removing user %s from group %s\n", CLI.Remove.User, CLI.Remove.Group)
	case "list":
		if CLI.List.Group != "" {
			fmt.Printf("Listing users in group %s\n", CLI.List.Group)
		} else {
			fmt.Println("Listing all users")
		}
	case "config set <key> <value>":
		fmt.Printf("Setting config %s=%s\n", CLI.Config.Set.Key, CLI.Config.Set.Value)
	case "config get <key>":
		fmt.Printf("Getting config %s\n", CLI.Config.Get.Key)
	default:
		log.Printf("Unknown command: %s\n", ctx.Command())
		os.Exit(1)
	}
}

这个示例展示了如何使用 Kong 创建一个具有多个命令和子命令的 CLI 应用程序，包括参数解析、帮助生成和命令路由。