Supporting subcommands with same option name as reused parent command?

jonathanpenn · March 6, 2020, 9:24pm

While working on this patch to fix help output to not show duplicates of options re-used throughout a command hierarchy...

github.com/apple/swift-argument-parser

Fix duplicate options showing up in command help output

apple:master ← jonathanpenn:fix-duplicate-options-in-help

opened 09:11PM - 06 Mar 20 UTC

jonathanpenn

+11 -8

When using option groups to bring options into subcommands that are also used i…n parent commands, the help system duplicates the options in the generated output. For instance, in the `SubcommandEndToEndTest` example, the `--name` argument is listed twice for both the subcommands `CommandA` and `CommandB`, and expected by the test assertion. It is annoying in a simple case like this but causes a lot of unhelpful noise in help output when you share more and more options across a command heirarchy. To solve this we need to keep track of what `HelpGenerator.Section.Element` values have already been processed from parent commands in the command stack. I acheived this by making `Element` conform to `Hashable` to track in a `Set`. This assumes that we don't need to support re-using command names up and down a command heirarchy. It doesn't work at all today (you get an error when trying to use the exact same option in a parent and child command). If we choose to support this eventually then we'll need to augment this solution to keep track of where the `Element` was generated in the heirarchy. This also updates the test to properly assert that the `--name` option is only output once for the subcommands in `SubcommandEndToEndTest`. ### Checklist - [x] I've added at least one test that validates that my change is working, if appropriate - [x] I've followed the code style of the rest of the project - [x] I've read the [Contribution Guidelines](CONTRIBUTING.md) - [x] I've updated the documentation if necessary

I wondered what should happen if I tried to reuse the same option names in parent and subcommands. Consider this example...

struct Command: ParsableCommand {
  static var configuration = CommandConfiguration(
    subcommands: [Sub.self]
  )

  @Option()
  var arg: String

  struct Sub: ParsableCommand {

    @OptionGroup()
    var parent: Command

    @Option()
    var arg: String

    func run() throws {
      print(parent.arg, arg)
    }
  }
}

If I try to invoke this like so...

command --arg value1 sub --arg value2

...then it shows this error message...

Error: Missing one of: '--arg <arg>', '--arg <arg>'
Usage: command sub --arg <arg> --arg <arg>

The error itself is unhelpful and should be fixed, but let's ignore that for this discussion. I want to know what we expect this should do, both in the short and long terms.

When I first started poking around with subcommands, I assumed that parent command parameters brought into a subcommand would need to come before the subcommand in the line. @nnnnnnnn pointed out to me that this is not the case. We could easily call the above command example like so...

command sub --arg value1 --arg value2

Given that, it makes sense to me now why we wouldn't want to support "reusing" the same option name across a command hierarchy. It doesn't fit this model. But I figured I should bring this up and see if this is something intentional or not.