Kong Command-Line Parser for Go

When implementing command execution via Run(...) error methods, you can inject dependencies using several patterns:

1. Bind(value): Bind a value directly.
2. BindTo(interface): Bind a value to an interface type.
3. BindToProvider(func): Bind a value to a provider function.
4. Provide<Type>() error: Implement a provider method on the command structure itself.

Kong supports limited variable interpolation in help strings, placeholder strings, enum lists, and default values using the syntax ${<name>} or ${<name>=<default>}.

Variables can be provided in two ways:

1. Via kong.Vars: Pass a map of variables to kong.Parse.
2. Via set tag: Use the set:"K=V" tag on a struct field. These variables are available to that node and all its children.

Special variables available during interpolation:

• ${default}: The default value.
• ${enum}: The list of enum values.
• ${env}: The name of the associated environment variable. If ${env} is used in a help string, Kong will automatically append ($${env}) to the help text.

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

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

Kong automatically generates --help documentation based on your struct tags (help:"").

• Top-level help: Displays available commands and global flags.
• Contextual help: If a command is provided (e.g., app --help <command>), Kong shows detailed help for that specific command, including its flags and arguments.
• Custom help: Any command or argument type implementing the Help() string interface can provide additional descriptive text that augments the standard help tags.

Kong uses Go struct tags to define CLI commands, flags, and arguments. You can use the kong: tag to specify various properties like name, help, default, required, and more. If a field is marked with kong:"-", it will be ignored by Kong.

Properties can be defined directly on the field or via a Signature interface on the type to provide defaults that can be overridden by the field itself.

Use the embed:"" tag to include nested data structures. You can combine this with prefix:"" to create prefixed flags. For example, prefix:"logging." with a field Level will result in the flag --logging.level.

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

To use Kong, define a Go struct where fields represent flags, arguments, or sub-commands. Use struct tags like help:"..." for documentation, cmd:"" to define a command, and arg:"" for positional arguments.

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())
  }
}

You can configure structs as branching positional arguments by tagging an unmapped nested struct field with arg, and then including a positional argument field inside that struct with the same name as the enclosing field.

var CLI struct {
  Rename struct {
    Name struct {
      Name string `arg` // <-- NOTE: identical name to enclosing struct field.
      To struct {
        Name struct {
          Name string `arg` 
        } `cmd` 
      } `cmd` 
    } `arg` 
  } `cmd` 
}