Add support for backward compatible flag groups

[technicianted]

This PR adds support for flag grouping. Group can be set either directly on Flag or using SetGroup() function. A new function Groups() can be used to obtain a list of defined groups.

By default, Group is empty and FlagUsages() will work as expected.

Although this work can be done using custom usage functions, having a built-in way of doing it seems more intuitive as the package already handles bulk flag formatting using FlagUsages() method.

With this change, things like spf13/cobra can update its template to provide consistent and backward compatible output. For example, Flags: output section can be replaced with:

{{- if .HasAvailableLocalFlags}}
  {{- $flags:=.LocalFlags}}
  {{- range $flags.Groups}}

{{.}}{{- if . }} {{end}}Flags:
{{ $flags.FlagUsagesForGroup . | trimTrailingWhitespaces}}
  {{- end}}
{{- end}}

and output would look like this:

cobracai is an example of grouping flags

Usage:
  cobracai [flags]
  cobracai [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command

Listener Flags:
      --listener-address string         Listen address (default "0.0.0.0")
      --listener-type string            Listener type: {tcp|unix} (default "tcp")

Metrics and Telemetry Flags:
      --log-level string                Set log level (default "info")
      --metrics-listen-address string   Metrics listen address (default ":8080")
      --metrics-type string             Metrics exposition type (default "prometheus")

Flags:
  -h, --help                            help for cobracai

Additional help topics:
  cobracai subcomm    

Use "cobracai [command] --help" for more information about a command.

[CLAassistant]

All committers have signed the CLA.

[RainbowMango]

I like this feature. Any updates?

[technicianted]

I like this feature. Any updates?

You can temporarily use my fork technicianted/pflag and add the following to your go.mod:

replace github.com/spf13/pflag v1.0.5 => github.com/technicianted/pflag v1.0.6-0.20211216182845-d6307205cfab

[RainbowMango]

Thanks @technicianted, have you used this in any project? Is there an example?

[technicianted]

Thanks @technicianted, have you used this in any project? Is there an example?

If you're using spf13/cobra, you can use this usage template like this:

import (
    _ "embed"
)

var (
    //go:embed usage.txt
    usageTemplate string
)

func init() {
    myCMD.SetUsageTemplate(usageTemplate)
}

usage.txt is in Go template format that I had adapted from the original cobra usage template. You can tweak it any way you want.