Show the actual available flags in useline

[lugray]

Use common useline notation for available flags:

• [-f foo] for (standard) optional flags
• [-f foo | -b bar] for mutually exclusive flags
• -f foo for required flags
• {-f foo | -b bar} for mutually exclusive flags where one is required
• [-f foo -b bar] for flags required as a group

For a boolean flag f, foo is dropped from the above. The foo/bar comes from flag.UnquoteUsage.

[CLAassistant]

All committers have signed the CLA.

[marckhouzam]

This sounds like a nice improvement @lugray. Thanks! I’ll try to find some time in the coming weeks.

[nirs]

Thanks @lugray! can you share complete help output of complex commands with many arguments using this feature? How long lines are handled?

For example other tools with complex command lines options using this style use multiple lines to make the output nicer.

This example is using manual formatting - hard work but you have complete control on the output:
https://gitlab.com/nbdkit/libnbd/-/blob/master/copy/main.c?ref_type=heads#L69

[nirs]

Instead of func(*Command, []string) {}} we can use emptyRun

[nirs]

Did you consider more condensed format?

command [--foo|--bar]

popular tools like python argparse use the same format suggested, for example:

$ cat args.py 
import argparse
p = argparse.ArgumentParser()
me = p.add_mutually_exclusive_group()
me.add_argument("--foo")
me.add_argument("--bar")
p.parse_args()

$ python args.py -h | head -1
usage: args.py [-h] [--foo FOO | --bar BAR]

[nirs]

Any reason to chose {} for required choice from mutually exclusive arguments?

python argparse uses () for the same:

$ cat args.py 
import argparse
p = argparse.ArgumentParser()
me = p.add_mutually_exclusive_group(required=True)
me.add_argument("--foo")
me.add_argument("--bar")
p.parse_args()

$ python args.py -h | head -1
usage: args.py [-h] (--foo FOO | --bar BAR)

[nirs]

Using bare return is not consistent with other code added.

[nirs]

The code to list the short usage strings is repeated twice, making this function even more complicated and hard to follow. We have here many very short variable names (arg, me, or, gr, fl) and complex string formatting. It is pain to follow this code.

We can make it little better by extracting few helpers. I'm not sure about the names, they can be better.

func groupShortUsage(flags map[string]*flag.Flag, included map[*flag.Flag]struct{}) []string {
    gr := []string{}
    for _, fl := range flags {
        included[fl] = struct{}{}
        gr = append(gr, shortUsage(fl))
    }
    return gr
}

func isOneRequired(f *flag.Flag) bool {
    req, found := f.Annotations[BashCompOneRequiredFlag]
    return found && req[0] == "true"    
}

Now we have only 3 very short variables names which is easy to grasp, the rest is the obvious formatting.

		rag := flagsFromAnnotation(c, f, requiredAsGroup)
		me := flagsFromAnnotation(c, f, mutuallyExclusive)
		or := flagsFromAnnotation(c, f, oneRequired)

		if len(rag) > 0 {
			usages := groupShortUsage(rag, included)
			flagsLine += " [" + strings.Join(usages, " ") + "]"
		} else if len(me) > 0 {
			usages := groupShortUsage(me, included)
			if sameFlags(me, or) {
				flagsLine += " {" + strings.Join(usages, " | ") + "}"
			} else {
				flagsLine += " [" + strings.Join(usages, " | ") + "]"
			}
		} else if isOneRequired(f) {
			flagsLine += " " + shortUsage(f)
		} else {
			flagsLine += " [" + shortUsage(f) + "]"
		}

[nirs]

This is consistent with other options, but this change may visually break existing tools using this library. Should we use EnableVerboseFlagsInUsageLine so one can opt in to use the new feature?