anchore / fangs

fangs

A library that makes integrating Cobra and Viper simpler and more consistent.

Background

Anchore Go-based CLI tools use Cobra and Viper for building the basic CLI handling and configuration, respectively. The use of these tools has evolved over the years and some patterns have emerged that seem to work better than others and avoid some pitfalls.

This library uses some best practices we've found for integrating these tools together in fairly simple ways.

Usage

In order to use this library, a consumer will need to:

• Define configuration structs
  • By default, use mapstructure struct tags (can be changed in the Config)
  • For embedded structs to be inline, these must use the nonstandard ,squash option
  • For embedded structs, the embedded type must exported if it is embedded via a pointer
• Define Cobra commands
• Add flags to Cobra using the *Var* flag variants
• Call config.Load during command invocation

A number of examples can be seen in the tests, but a simple example is as follows:

// define configuration structs:
type Options struct {
    Output string `mapstructure:"output"`
    Scanning ScanningOptions `mapstructure:"scanning"`
	EmbeddedOptions `mapstructure:",squash"` // need to use ,squash
}

type ScanningOptions struct {
    Depth int `mapstructure:"output"`
}

type EmbeddedOptions struct {
	Embedded string `mapstructure:"string"`
}

// fangs needs a configuration with a minimum of an app name
cfg := config.NewConfig("my-app")

// in a cobra configuration function:
func makeCommand(cfg config.Config) cobra.Command {
    // an instance of options with defaults we use to add flags and configure
    opts := Options{
        Output: "default",
        Scanning: ScanningOptions {
            Depth: 1,
        },
    }

    // make a cobra command with the options you need
    cmd := cobra.Command{
        RunE: func(cmd *cobra.Command, args []string) error {
            // before using opts, call config.Load with the cmd instance,
            // after flags have been added
            err := config.Load(cfg, cmd, &opts)
            // ...
        },
    }

    // add flags like normal, making sure to use the *Var* variants
    flags := cmd.Flags()
    flags.StringVarP(&opts.Output, "output", "o", opts.Output, "output usage")
    flags.IntVar(&opts.Scanning.Depth, "depth", opts.Scanning.Depth, "depth usage")
    
    return cmd
}

fangs's Issues

Panic if `AddFlags` does not have a pointer receiver

If a user defines an AddFlags method which does not have a pointer receiver, it will not properly bind the flag to the value on the object but rather an ephemeral memory location. It also is simply not being called at the moment. An example of this causing a problem in syft where the --key flag was not bound can be seen here. Realistically, this is always a coding problem that needs to be fixed and we should panic if we find AddFlags methods that were incorrectly specified so a user can more quickly get these fixed; i.e. panic if methods seen like this:

func (o Attest) AddFlags(flags fangs.FlagSet) {
	...
}

... instead of this:

func (o *Attest) AddFlags(flags fangs.FlagSet) {
	...
}