swift-argument-parser icon indicating copy to clipboard operation
swift-argument-parser copied to clipboard

Help text: Display argv[0] for root command by default

Open dcantah opened this issue 1 month ago • 1 comments

Fixes: #633 #570 #295

This seems like the "correct" default, although I'm sure there's some crazy edge case I'm failing to take into account. If your root command had the same name as the resulting binary you produce, this was never an issue, however if your root command was named anything else, then the current Usage/help text was kind of odd.

If you don't specify an explicit commandName in CommandConfiguration, we would take the root command name and generate a command name for you out of hyphens. So, RootCommand would become root-command and this is what would be displayed in the usage text for /path/to/cool-binary --help, even though intuitively you'd expect to see USAGE: cool-binary.

The current behavior was also strange for binaries that are classically invoked via symlinks as the same thing would happen. In this case imagine the struct name matched the actual binaries name, but because the symlink is what users actually invoke you could end up seeing an unfamiliar name in help text regardless. Using argv[0] solves most of these problems.

The downside here is a LOT of tests need to change. I went with foregoing the new approach if the user explicitly provides a command name, so most of the existing tests that check for exact string matches of help text either need to replace the command name with the first argument of the binary that is running the test (xctest, but it doesn't really matter what it is as I've added a helper to plop in the first argument for all of these tests), or they need to define CommandConfiguration(commandName: "name-we-want"). For any tests that implemented ParsableCommand I mostly went with the latter to make as few changes as possible.

Given this seems like mostly a UX change, I hope this seems sane.

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
  • [x] I've updated the documentation if necessary

dcantah avatar May 31 '24 23:05 dcantah