Support for option groups

[Tyrrrz]

Related to #6

Curious what are the potential use cases people have for this?
An obvious one is making two options mutually exclusive, but maybe there is something else?

[sandreas]

I would use this possibility to group the documentation / usage output for better understanding... Let's take my project tone for an example.

• There are global options / parameters like --help, --verbose, --debug or --force
• There are query options like --query, --order-by, --limit
• There are template options like --include-property, --exclude-property, --format, etc.
• There are topic-prefix groups (Logging: --log-{level,file}, Metadata: --meta-{artist,album,title,sort-album,...})

Usually, I would create a usage output in alphabetical order, but it would be a huge usability improvement to have them grouped depending on the purpose.

[Tyrrrz]

@sandreas in your use case, you're primarily looking after grouping inside the help text, right? Are you also interested in how it affects parsing, i.e. not being able to use both --query and --help together? Or is that not important?

[sandreas]

in your use case, you're primarily looking after grouping inside the help text, right?

Correct.

Example

[Command]
[GroupDescription("direction", "Options to choose the direction")]
[GroupDescription("meta", "Options to modify metadata")]
public class MetaCommand : ICommand
{
    [Group("direction")]
    [CommandOption("left")]
    public string Left { get; init; } = "Hello";

    [Group("direction")]
    [CommandOption("right")]
    public string Right { get; init; } = "world";

    [Group("meta")]
    [CommandOption("meta-album")]
    public string MetaAlbum { get; init; } = "";

    [Group("meta")]
    [CommandOption("meta-artist")]
    public string MetaArtist { get; init; } = "";

    public ValueTask ExecuteAsync(IConsole console)
    {
        console.Output.Write(Left);
        console.Output.Write(' ');
        console.Output.Write(Right);

        return default;
    }
}

Are you also interested in how it affects parsing, i.e. not being able to use both --query and --help together? Or is that not important?

While that would be an interesting thing to have, in my use case this would not have much benefit, because --help is a context specific, globally available boolean option. tone --help, tone dump --help and tone tag --help would show completely different output, while tone tag --query would not make any sense (--query is only available in thedump subcommand).

Maybe this is just a problem of terminology. In my head groups are things that somehow belong together logically, while Constraints would be things that restrict others, are mutually exclusive or depend on each other. Constraints would be much more complex to configure, I doubt that this would be convenient to do without prepared templates (e.g. for --help the [HelpOptionConstraint] combining [GlobalConstraint] and [ContextSensitiveConstraint]). Most importantly, restricting the usage of parameters may lead to unexpected consequences - what if I configured a long command and now want to see the --help page again, would it be good to restrict the --help parameter to be mutually exclusive or more like a pain not to be able to add it afterwards to look something up? I'm not sure...

While groups sound interesting, I probably wouldn't use constraints too much, but maybe I'm the wrong person to talk about these :-)

[Tyrrrz]

The original idea behind groups did envision some form of constraints, so I'm gathering feedback whether this is what users expect to find behind that functionality.