cli

Documentation

Overview

Package cli is a light wrapper around the cobra argument parsing/command library. The goal is to make it a bit easier to add examples and to limit some options in the name of ease-of-use.

Index

• Variables
• type Command
  • func NewCLI(appName, buildVersion, buildSHA, buildDate string, opts CommandOptions) *Command
  • func NewCommand(cmdName string, opts CommandOptions) *Command
  • func (c *Command) AddExamples(descCmds ...string)
  • func (c *Command) AddSubCommands(cmds ...*Command)
  • func (c *Command) SetRunFunc(run func(cmd *Command, args []string) error)
• type CommandOptions

Variables

var ExactArgs = cobra.ExactArgs

ExactArgs is a possible CommandOptions.Args value that indicates an exact number N of positional arguments is required

Pass as CommandOptions.Args = ExactArgs(3) for exactly 3 args

var MaximumNArgs = cobra.MaximumNArgs

MaximumNArgs is a possible CommandOpitions.Args value that indicates at most N positional arguments are allowed

Pass as CommandOptions.Args = MaximumNArgs(3) for at most 3 args

var MinimumNArgs = cobra.MinimumNArgs

MinimumNArgs is a possible CommandOptions.Args value that indicates at least N positional arguments are required

Pass as CommandOptions.Args = MinimumNArgs(3) for at least 3 args

var NoArgs = cobra.NoArgs

NoArgs is a possible CommandOptions.Args value that indicates that no positional arguments should occur

Pass as CommandOptions.Args = NoArgs

var RangeArgs = cobra.RangeArgs

RangeArgs is a possible CommandOptions.Args vlue that indicates between M and N positional arguments are required

Pass as CommandOptions.Args = RangeArgs(3, 5) for at least 3 and at most 5 args

Types

type Command

type Command struct {
	*cobra.Command
}

Command is a thin wrapper around a cobra.Command pointer to provide some convenience functions

func NewCLI

func NewCLI(appName, buildVersion, buildSHA, buildDate string, opts CommandOptions) *Command

NewCLI constructs a new Command struct that is intended to be the root command for a cli application

- appName is used to name the application - buildVersion, buildDate, and buildSHA are used to construct a version string - opts determines how the command behaves

func NewCommand

func NewCommand(cmdName string, opts CommandOptions) *Command

NewCommand constructs a new Command struct that can be used as a subcommand

- cmdName is the name of the command - opts determines how the command behaves

func (*Command) AddExamples

func (c *Command) AddExamples(descCmds ...string)

AddExamples extends the existing Command.Example value with more examples

- descCmds is a list whose alternating elements are example descriptions and example invocations (so the first, third, fifth entries, etc., are the descriptions, and the second, fourth, sixth, etc are the commands being described). If there are an uneven number of descriptions and commands, the extra descriptions are ignored.

func (*Command) AddSubCommands

func (c *Command) AddSubCommands(cmds ...*Command)

AddSubCommands attaches a list of Command structs as subcommands to the current command

func (*Command) SetRunFunc

func (c *Command) SetRunFunc(run func(cmd *Command, args []string) error)

SetRunFunc sets the function that is called when the command executes.

type CommandOptions

type CommandOptions struct {
	ShortHelp    string
	LongHelp     string
	Example      string
	PosArgsUsage string
	Deprecated   string
	Args         cobra.PositionalArgs

	Aliases      []string
	Hidden       bool
	SilenceUsage bool
}

CommandOptions is a way to specify the structure of a cli command

- ShortHelp is the short description of the command (should be one line) - LongHelp is a longer description of the command - Example is a string containing examples (can also be constructed and expanded with Command.AddExamples) - PosArgsUsage is a string to represent the positional arguments expected - Deprecated is a string that will be displayed to indicate the command is deprecated - Args is a specifier for the number of positional arguments (see NoArgs, ExactArgs, MinimumNArgs, MaximumNArgs, RangeArgs) - Aliases is a list of aliases for the command - Hidden enables hiding the command from help messages - SilenceUsage will prevent a usage message from being displayed if an error occurs