cobra

Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files.

github：https://github.com/spf13/cobra.git

cobra基于command、arguments和flags组织命令行，如：

hugo server –port=1313

hugo是command，server是arguments，port是flags。

一般程序目录结构如下：

app
├── cmd
│   ├── root.go
│   └── version.go
├── go.mod
└── main.go

main.go是主程序，cmd/root.go为基本命令文件，一般rootCmd表示在没有任何子命令的情况下的基本命令。

// Command is just that, a command for your application.
// E.g.  'go run ...' - 'run' is the command. Cobra requires
// you to define the usage and description as part of your command
// definition to ensure usability.
type Command struct {
    // Use is the one-line usage message.
    Use string

    // Aliases is an array of aliases that can be used instead of the first word in Use.
    Aliases []string

    // SuggestFor is an array of command names for which this command will be suggested -
    // similar to aliases but only suggests.
    SuggestFor []string

    // Short is the short description shown in the 'help' output.
    Short string

    // Long is the long message shown in the 'help <this-command>' output.
    Long string

    // Example is examples of how to use the command.
    Example string

    // ValidArgs is list of all valid non-flag arguments that are accepted in bash completions
    ValidArgs []string

    // Expected arguments
    Args PositionalArgs

    // ArgAliases is List of aliases for ValidArgs.
    // These are not suggested to the user in the bash completion,
    // but accepted if entered manually.
    ArgAliases []string

    // BashCompletionFunction is custom functions used by the bash autocompletion generator.
    BashCompletionFunction string

    // Deprecated defines, if this command is deprecated and should print this string when used.
    Deprecated string

    // Hidden defines, if this command is hidden and should NOT show up in the list of available commands.
    Hidden bool

    // Annotations are key/value pairs that can be used by applications to identify or
    // group commands.
    Annotations map[string]string

    // Version defines the version for this command. If this value is non-empty and the command does not
    // define a "version" flag, a "version" boolean flag will be added to the command and, if specified,
    // will print content of the "Version" variable. A shorthand "v" flag will also be added if the
    // command does not define one.
    Version string

    // The *Run functions are executed in the following order:
    //   * PersistentPreRun()
    //   * PreRun()
    //   * Run()
    //   * PostRun()
    //   * PersistentPostRun()
    // All functions get the same args, the arguments after the command name.
    //
    // PersistentPreRun: children of this command will inherit and execute.
    PersistentPreRun func(cmd *Command, args []string)
    // PersistentPreRunE: PersistentPreRun but returns an error.
    PersistentPreRunE func(cmd *Command, args []string) error
    // PreRun: children of this command will not inherit.
    PreRun func(cmd *Command, args []string)
    // PreRunE: PreRun but returns an error.
    PreRunE func(cmd *Command, args []string) error
    // Run: Typically the actual work function. Most commands will only implement this.
    Run func(cmd *Command, args []string)
    // RunE: Run but returns an error.
    RunE func(cmd *Command, args []string) error
    // PostRun: run after the Run command.
    PostRun func(cmd *Command, args []string)
    // PostRunE: PostRun but returns an error.
    PostRunE func(cmd *Command, args []string) error
    // PersistentPostRun: children of this command will inherit and execute after PostRun.
    PersistentPostRun func(cmd *Command, args []string)
    // PersistentPostRunE: PersistentPostRun but returns an error.
    PersistentPostRunE func(cmd *Command, args []string) error

    // SilenceErrors is an option to quiet errors down stream.
    SilenceErrors bool

    // SilenceUsage is an option to silence usage when an error occurs.
    SilenceUsage bool

    // DisableFlagParsing disables the flag parsing.
    // If this is true all flags will be passed to the command as arguments.
    DisableFlagParsing bool

    // DisableAutoGenTag defines, if gen tag ("Auto generated by spf13/cobra...")
    // will be printed by generating docs for this command.
    DisableAutoGenTag bool

    // DisableFlagsInUseLine will disable the addition of [flags] to the usage
    // line of a command when printing help or generating docs
    DisableFlagsInUseLine bool

    // DisableSuggestions disables the suggestions based on Levenshtein distance
    // that go along with 'unknown command' messages.
    DisableSuggestions bool
    // SuggestionsMinimumDistance defines minimum levenshtein distance to display suggestions.
    // Must be > 0.
    SuggestionsMinimumDistance int

    // TraverseChildren parses flags on all parents before executing child command.
    TraverseChildren bool

    // FParseErrWhitelist flag parse errors to be ignored
    FParseErrWhitelist FParseErrWhitelist

    ctx context.Context

    // commands is the list of commands supported by this program.
    commands []*Command
    // parent is a parent command for this command.
    parent *Command
    // Max lengths of commands' string lengths for use in padding.
    commandsMaxUseLen         int
    commandsMaxCommandPathLen int
    commandsMaxNameLen        int
    // commandsAreSorted defines, if command slice are sorted or not.
    commandsAreSorted bool
    // commandCalledAs is the name or alias value used to call this command.
    commandCalledAs struct {
        name   string
        called bool
    }

    // args is actual args parsed from flags.
    args []string
    // flagErrorBuf contains all error messages from pflag.
    flagErrorBuf *bytes.Buffer
    // flags is full set of flags.
    flags *flag.FlagSet
    // pflags contains persistent flags.
    pflags *flag.FlagSet
    // lflags contains local flags.
    lflags *flag.FlagSet
    // iflags contains inherited flags.
    iflags *flag.FlagSet
    // parentsPflags is all persistent flags of cmd's parents.
    parentsPflags *flag.FlagSet
    // globNormFunc is the global normalization function
    // that we can use on every pflag set and children commands
    globNormFunc func(f *flag.FlagSet, name string) flag.NormalizedName

    // usageFunc is usage func defined by user.
    usageFunc func(*Command) error
    // usageTemplate is usage template defined by user.
    usageTemplate string
    // flagErrorFunc is func defined by user and it's called when the parsing of
    // flags returns an error.
    flagErrorFunc func(*Command, error) error
    // helpTemplate is help template defined by user.
    helpTemplate string
    // helpFunc is help func defined by user.
    helpFunc func(*Command, []string)
    // helpCommand is command with usage 'help'. If it's not defined by user,
    // cobra uses default help command.
    helpCommand *Command
    // versionTemplate is the version template defined by user.
    versionTemplate string

    // inReader is a reader defined by the user that replaces stdin
    inReader io.Reader
    // outWriter is a writer defined by the user that replaces stdout
    outWriter io.Writer
    // errWriter is a writer defined by the user that replaces stderr
    errWriter io.Writer
}

常用command示例如下：

var cmdPrint = &cobra.Command{
    Use:   "print [string to print]",
    Short: "Print anything to the screen",
    Long: `print is for printing anything back to the screen.
    For many years people have printed back to the screen.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Print: " + strings.Join(args, " "))
    },
}

flags

一般来说，在init()函数中定义flags和处理配置。

flags分为持久flags（Persistent Flags）和本地flags（local Flags）。

Local flags：flags仅适用于指定command。以serverCmd.Flags().StringVarP(&server.ServerPort, "port", "p", "50052", "server port")为例，定义了一个flag，值存储在&server.ServerPort中，长命令为--port，短命令为-p，，默认值为50052，命令的描述为server port。

Persisten flags：flags适用于指定命令及其子命令。如rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")，``flag是可以持久的，这意味着该flag将被分配给它所分配的命令以及该命令下的每个命令。对于全局标记，将标记作为根上的持久标志。

// https://github.com/spf13/pflag.git
// StringVarP is like StringVar, but accepts a shorthand letter that can be used after a single dash.
func (f *FlagSet) StringVarP(p *string, name, shorthand string, value string, usage string) {
    f.VarP(newStringValue(value, p), name, shorthand, usage)
}

// StringP is like String, but accepts a shorthand letter that can be used after a single dash.
func (f *FlagSet) StringP(name, shorthand string, value string, usage string) *string {
    p := new(string)
    f.StringVarP(p, name, shorthand, value, usage)
    return p 
}

// String defines a string flag with specified name, default value, and usage string.
// The return value is the address of a string variable that stores the value of the flag.
func (f *FlagSet) String(name string, value string, usage string) *string {
    p := new(string)
    f.StringVarP(p, name, "", value, usage)
    return p
}

Args

Command中的Args用于指定位置参数（positional arguments）。

NoArgs - the command will report an error if there are any positional args.
ArbitraryArgs - the command will accept any args.
OnlyValidArgs - the command will report an error if there are any positional args that are not in the ValidArgs field of Command.
MinimumNArgs(int) - the command will report an error if there are not at least N positional args.
MaximumNArgs(int) - the command will report an error if there are more than N positional args.
ExactArgs(int) - the command will report an error if there are not exactly N positional args.
ExactValidArgs(int) - the command will report an error if there are not exactly N positional args OR if there are any positional args that are not in the ValidArgs field of Command
RangeArgs(min, max) - the command will report an error if the number of args is not between the minimum and maximum number of expected args.

Help

cmd.SetHelpCommand(cmd *Command)
cmd.SetHelpFunc(f func(*Command, []string))
cmd.SetHelpTemplate(s string)

后面两个用于任何子命令。

Usage

cmd.SetUsageFunc(f func(*Command) error)
cmd.SetUsageTemplate(s string)