Make it possible to create options sections

[NicolasMassart]

Hi,
I was wondering if there's plans to enable options sections in help output like we can see in https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options

WHISPER (EXPERIMENTAL) OPTIONS:
  --shh                       Enable Whisper
  --shh.maxmessagesize value  Max message size accepted (default: 1048576)
  --shh.pow value             Minimum POW accepted (default: 0.2)
  
DEPRECATED OPTIONS:
  --fast   Enable fast syncing through state downloads (replaced by --syncmode)
  --light  Enable light client mode (replaced by --syncmode)
  
MISC OPTIONS:
  --help, -h  show help

By having something like an attribute in the @Option indicating a section id and map of sections id and sections titles in the @Command. Then we would be able to group options (@Command.groupOptions boolean attribute ?) by section.
Sorting (@Command.sortOptions attribute) could also affect the order of appearance of that in the way that alphabetical would also sort section first and options in the section.
Also a being able to use @| in sections title would be nice if we could also add an uppercase style :

@Command(sections = {
    new Section("sec0","@|uppercase My first section|@",
    new Section("sec1","@|uppercase My second section|@",
    new Section("sec2","@|uppercase My third section|@"
}

then
@Option(section = "sec0" ... )

[remkop]

Yes I like that idea very much. I did a spike for something similar in #199, but other work took priority.

[kravemir]

A bit of brainstorming. What if @Mixin was a section? For example, mixins like: PageOptions, TemplateOptions, PrintOptions, DataOptions, LoggingOptions.

With multi sub-command cli tool, such Mixins could be printed as sections in a manpage. And, won't get repeated for each sub-command, because they would be shared option groups / sections.

[remkop]

I think a separate annotation will be needed anyway for the section titles.
Then yes, once this annotation is implemented, there is no reason why a @Mixin could not use these annotations to create sections in the options list.

[remkop]

Marking this as a duplicate of #199. That’ll be a major new feature of the 4.0 release.

[remkop]

An initial implementation of this has been pushed to master.

Example usage:

@Command(argGroups = {
        @ArgGroup(name = "ALL", exclusive = false, required = false, order = 10,
                heading = "Co-occurring options:%nThese options must appear together, or not at all.%n"),
        @ArgGroup(name = "EXCL", exclusive = true, required = true, order = 20,
                heading = "Exclusive options:%n"),
        @ArgGroup(name = "COMPOSITE", exclusive = true, required = false,
                subgroups = {"ALL", "EXCL"}),
        @ArgGroup(name = "INITIAL", validate = false, heading = "", order = 0),
        @ArgGroup(name = "REMAINDER", validate = false, heading = "Remaining options:%n", order = 100)
})
class App {
    @Option(names = "-x", groups = "EXCL") int x;
    @Option(names = "-y", groups = "EXCL") int y;
    @Option(names = "-a", groups = "ALL") int a;
    @Option(names = "-b", groups = "ALL") int b;
    @Option(names = "-c", groups = "ALL") int c;
    @Option(names = "-A", groups = "INITIAL") int A;
    @Option(names = "-B", groups = "INITIAL") boolean B;
    @Option(names = "-C", groups = "INITIAL") boolean C;
    @Option(names = "-D", groups = "REMAINDER") int D;
    @Option(names = "-E", groups = "REMAINDER") boolean E;
    @Option(names = "-F", groups = "REMAINDER") boolean F;
}

This will generate the following usage help messsage:

Usage: <main class> [[-a=<a> -b=<b> -c=<c>] | (-x=<x> | -y=<y>)] [-BCEF]
                    [-A=<A>] [-D=<D>]
  -A=<A>
  -B
  -C
Co-occurring options:
These options must appear together, or not at all.
  -a=<a>
  -b=<b>
  -c=<c>
Exclusive options:
  -x=<x>
  -y=<y>
Remaining options:
  -D=<D>
  -E
  -F

Please try this out and provide feedback.

TODO:

• internationalization: getting headers from resource bundle
• documentation

[remkop]

Picocli 4.0.0-alpha-1 has been released which includes support for option sections in the usage help.
See https://picocli.info/#_argument_groups for details.

Please try this and provide feedback. We can still make changes.

What do you think of the annotations API? What about the programmatic API? Does it work as expected? Are the input validation error messages correct and clear? Is the documentation clear and complete? Anything you want to change or improve? Any other feedback?