cmdparser

Documentation

Index

• func Initialize(init func())
• func New[T PtrAsReceiverWrapper[pointerType], pointerType any](dependencies dependency.Options) (command T)
• func TestCmd[T PtrAsReceiverWrapper[pointerType], pointerType any](args ...string) string
• func TestSetup(t *testing.T)
• type AlternativeForFlagOptions
• type Cmd
  • func (c *Cmd) AddFlag(options FlagOptions)
  • func (c *Cmd) CheckErr(err error)
  • func (c *Cmd) Command() *cobra.Command
  • func (c *Cmd) DefineCommand(options ...CommandOptions)
  • func (c *Cmd) Dependencies() dependency.Options
  • func (c *Cmd) Execute()
  • func (c *Cmd) IsSubCommand(command string) (valid bool)
  • func (c *Cmd) Output() *output.Output
  • func (c *Cmd) SetArgsForUnitTesting(args []string)
  • func (c *Cmd) SetCrossCuttingConcerns(dependencies dependency.Options)
• type Command
• type CommandOptions
• type ExampleOptions
• type FlagOptions
• type PtrAsReceiverWrapper

Functions

func Initialize

func Initialize(init func())

Initialize runs the init func() after the command-line provided by the user has been parsed.

func New

func New[T PtrAsReceiverWrapper[pointerType], pointerType any](dependencies dependency.Options) (command T)

func TestCmd

func TestCmd[T PtrAsReceiverWrapper[pointerType], pointerType any](args ...string) string

Run a command expecing it to pass, passing in any supplied args (args are split on " " (space))

func TestSetup

func TestSetup(t *testing.T)

Setup internal packages for testing

Types

type AlternativeForFlagOptions

type AlternativeForFlagOptions struct {
	Flag  string
	Value *string
}

The AlternativeForFlagOptions type represents options for defining an alternative for a flag. It consists of the name of the flag, as well as a pointer to the value to be used as the alternative. This type is typically used in the case where the user has provided an argument that should be treated as an alternative to a specific flag.

type Cmd

type Cmd struct {
	// contains filtered or unexported fields
}

Cmd is the main type used for defining and running command line programs. It contains fields and methods for defining the command, setting its options, and running the command.

func (*Cmd) AddFlag

func (c *Cmd) AddFlag(options FlagOptions)

AddFlag adds a flag to the command instance of type Cmd. The flag is added according to the provided FlagOptions. If the FlagOptions does not have a name or usage, then the function panics. If the flag is of type String then it adds the flag to the PersistentFlags of the command instance with the provided options. Similarly, if the flag is of type Int or Bool, the flag is added to the PersistentFlags with the provided options. If a shorthand is provided, then it uses StringVarP or BoolVarP or IntVarP instead of StringVar or BoolVar or IntVar respectively.

func (*Cmd) CheckErr

func (c *Cmd) CheckErr(err error)

CheckErr passes the error down to cobra.CheckErr (which is likely to call os.Exit(1) if err != nil. Although if running in the golang unit test framework we do not want to have os.Exit() called, as this exits the unit test runner process, and call panic instead so the call stack can be added to the unit test output.

func (*Cmd) Command

func (c *Cmd) Command() *cobra.Command

Command returns the cobra Command associated with the Cmd. This method allows for easy access and manipulation of the command's properties and behavior.

func (*Cmd) DefineCommand

func (c *Cmd) DefineCommand(options ...CommandOptions)

DefineCommand defines a command with the provided CommandOptions and adds it to the command list. If only one CommandOptions is provided, it is used as the command options. Otherwise, the default CommandOptions are used. The function sets the command usage, short and long descriptions, aliases, examples, and run function. It also sets the maximum number of arguments allowed for the command, and adds any subcommands specified in the CommandOptions.

func (*Cmd) Dependencies

func (c *Cmd) Dependencies() dependency.Options

func (*Cmd) Execute

func (c *Cmd) Execute()

Execute function is responsible for executing the underlying command for this Cmd object. The function first attempts to execute the command, and then checks for any errors that may have occurred during execution. If an error is detected, the CheckErr method is called to handle the error. This function is typically called after defining and configuring the command using the DefineCommand and SetArgsForUnitTesting functions.

func (*Cmd) IsSubCommand

func (c *Cmd) IsSubCommand(command string) (valid bool)

IsSubCommand returns true if the provided command string matches the name or an alias of one of the object sub-commands, or if the command string is "--help" or "completion". Otherwise, it returns false.

func (*Cmd) Output

func (c *Cmd) Output() *output.Output

Output function is a getter function that returns the output.Output instance associated with the Cmd instance. If no output.Output instance has been set, the function initializes a new instance and returns it.

func (*Cmd) SetArgsForUnitTesting

func (c *Cmd) SetArgsForUnitTesting(args []string)

SetArgsForUnitTesting sets the arguments for a unit test. This function allows users to specify arguments to the command for testing purposes.

func (*Cmd) SetCrossCuttingConcerns

func (c *Cmd) SetCrossCuttingConcerns(dependencies dependency.Options)

Inject dependencies into the Cmd struct. The options parameter is a struct containing a reference to the output struct, which the function then assigns to the output field of the Cmd struct. This allows for the output struct to be mocked in unit tests.

type Command

type Command interface {
	// CheckErr checks if the given error is non-nil and, if it is, it prints the error
	// to the output and exits the program with an exit code of 1.
	CheckErr(error)

	// Command returns the underlying cobra.Command object for this command.
	// This is useful for defining subcommands.
	Command() *cobra.Command

	// DefineCommand is used to define a new command and its associated
	// options, flags, and subcommands. It takes in a CommandOptions
	// struct, which allow the caller to specify the command's name, description,
	// usage, and behavior.
	DefineCommand(...CommandOptions)

	// IsSubCommand is TEMPORARY code that will be removed when the
	// old Kong CLI is retired.  It returns true if the command-line
	// provided by the user looks like they want the new cobra CLI, e.g.
	// sqlcmd query, sqlcmd install, sqlcmd --help etc.
	IsSubCommand(command string) bool

	// SetArgsForUnitTesting method allows a caller to set the arguments for the
	// command when running unit tests. This is useful because it allows the caller
	// to simulate different command-line input scenarios in their tests.
	SetArgsForUnitTesting(args []string)

	// SetCrossCuttingConcerns is used to inject cross-cutting concerns (i.e. dependencies)
	// into the Command object (like logging etc.). The dependency.Options allows
	// the Command object to have access to the dependencies it needs, without
	// having to manage them directly.
	SetCrossCuttingConcerns(dependency.Options)
}

Command is an interface for defining and running a command which is part of a command line program. Command contains methods for setting command options, running the command, and checking for errors.

type CommandOptions

type CommandOptions struct {
	Aliases                    []string
	Examples                   []ExampleOptions
	FirstArgAlternativeForFlag *AlternativeForFlagOptions
	Long                       string
	Run                        func()
	Short                      string
	Use                        string
	SubCommands                []Command
}

CommandOptions is a struct that allows the caller to specify options for a Command. These options include the command's name, description, usage, and behavior. The Aliases field specifies alternate names for the command, and the Examples field specifies examples of how to use the command. The FirstArgAlternativeForFlag field specifies an alternative to the first argument when it is provided as a flag, and the Long and Short fields specify the command's long and short descriptions, respectively. The Run field specifies the behavior of the command when it is executed, and the Use field specifies the usage instructions for the command. The SubCommands field specifies any subcommands that the command has.

type ExampleOptions

type ExampleOptions struct {
	Description string
	Steps       []string
}

ExampleOptions specifies the details of an example usage of a command. It contains a description of the example, and a list of steps that make up the example. This type is typically used in conjunction with the Examples field of the CommandOptions struct, to provide examples of how to use a command in the command's help text.

type FlagOptions

type FlagOptions struct {
	Name      string
	Shorthand string
	Usage     string

	String        *string
	DefaultString string

	Int        *int
	DefaultInt int

	Bool        *bool
	DefaultBool bool
}

FlagOptions type represents options for defining a flag for a command-line interface. The Name and Shorthand fields specify the long and short names for the flag, respectively. The Usage field is a string that describes how the flag should be used. The String, DefaultString, Int, DefaultInt, Bool, and DefaultBool fields are used to specify the type and default value of the flag, if it is a string, int, or bool type. The String and Int fields should be pointers to the variables that will store the flag's value, and the Bool field should be a pointer to a bool variable that will be set to true if the flag is present. The DefaultString, DefaultInt, and DefaultBool fields are the default values to use if the flag is not provided by the user.

type PtrAsReceiverWrapper

type PtrAsReceiverWrapper[T any] interface {
	Command
	*T
}

PtrAsReceiverWrapper per golang design doc "an unfortunate necessary kludge": https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md#pointer-method-example https://www.reddit.com/r/golang/comments/uqwh5d/generics_new_value_from_pointer_type_with/