Grouping options in help

I have created a command with many options. If I run the command with the --help flag I get a full page of options which hard to interpret.

I have seen that I can actually group options in a so-called OptionGroup which allows me to, for example put all options that have to do with auto-layout in a sub-struct:

struct AutoLayout: ParsableArguments {
    @Option(...) var option1
    @Option(...) var option2
    @Option(...) var option3
}

struct Application: ParsableCommand {
   ...
   @Option(...) var regular
   @OptionGroup var icons: AutoLayout
}

If I then run the command with --help this does not have any visual effect in the generated help.

It would be really nice if I could do something like this:

struct AutoLayout: ParsableArguments {
    static var description: String {
         "Auto layout options"
    }
    @Option(...) var option1
    @Option(...) var option2
    @Option(...) var option3
}

which would then result in a help output that would use the group description:

   --regular   bla bla
  
   Auto layout options

      --option1   description option 1
      --option2   description option 2
      --option3   description option 3

It would be nice if something could be made possible in a future version.

1 Like

Definitely — I'm tracking that issue here. My idea is that you could provide a title when declaring an @OptionGroup, which would cause the group to be separated from rest:

struct Options: ParsableArguments {
    @Flag(help: "Display extra information while processing.")
    var verbose = false

    @Option(help: "The number of extra lines to show.")
    var extraLines = 0
}

struct Example: ParsableCommand {
    @OptionGroup(title: "Shared Options")
    var group: Options

    @Flag(help: "Parse as a binary file.")
    var parseAsBinary = false

    @Argument(help: "The input file.")
    var inputFile: String?
}

What do you think about providing the title at the @OptionGroup-level instead of in the included type?

Thanks for the response.

As you understood, the use of description in my example was indeed just an example. The advantage of using a title parameter to the @OptionGroup instead of a fixed static title in the @OptionGroup would be that in theory we could use a different title for each subcommand. So title as a parameter is more flexible.

Hi @nnnnnnnn

Am I correct in understanding that this title to the @OptionGroup never made it into the code.
The issue you were referring to has been merged now but there is no initializer that accepts a title.

Right, the issue is still open — there was a related change, but the "titled option groups" feature hasn't been added yet.