The Swift Argument Parser has a feature to produce a JSON format of the entire command-line argument structure. If you use a version of SAP from the last few years you can run your tool with just the –-experimental-dump-help and get this structure. For example, swiftly -–experimental-dump-help will just work because it uses SAP.
This feature has enabled some really interesting tooling, such as automatically generating command-line references for DocC, or even a Unix manual page. There’s also some new tooling in the works, such as the new package templates pitch.
It has been a few years since this feature was added, and it’s proven to be stable. To further open up the world of possibilities it will be great to graduate this feature from experimental to officially supported.
I’m curious about your thoughts on this proposal: rename the flag to --dump-help-jsonv1 and keep the original one for backward compatibility with existing tooling.
The new flag has some more detail in it, including and explicit format “json” and version “v1" so that new formats and versions can be added in the future so that clients don’t receive unexpected content. It’s a form of content negotiation and if a command-line tool doesn’t support the requested format/version then they will get a non-zero exit code.
What do you think? Thoughts and suggestions are welcome.
I do think its time to graduate this flag, as I don’t think there have been changes in this area for quite some time.
A nit on this proposal is I think --dump-help-jsonv1 is really three flags in one, as it condenses the action, the format and the version into a single flag. Instead I think we should break it up into --dump-help and –-dump-help-version 1. I believe the only format for dump-help is json today, so that becomes redundant, but if we ever added more formats there could also be –-dump-help-format.
Because the flag is special in the sense that it triggers an entirely alternate workflow of the tool I think it would make sense to keep it glued together and very simple flag. What should happen if the –dump-help-version 1 is passed in without the –dump-help? Also, I wonder about making it an option instead of a flag as it adds more complexity in the handling than just “yes, I understand this and will give you what you’ve requested” or “I don’t know what this means at all, error”
I’d love to see this formalized sufficiently to use it elsewhere in the tooling, so a huge +1 from me. In particular, I’d like to use this data structure as a source for symbols to use in DocC, but focused specifically on CLI commands, subcommands, arguments, and options. The rendering that exists today is great, but the broader DocC process has a nice structure to let you mix in text from elsewhere, which would be immensely useful for maintaining additional CLI documentation.
Thanks for opening up this discussion, Chris! I agree that it's time for this. A major implication of this change is that we will begin to guarantee that projects built on top of this feature will continue to work, so let's talk a bit about future compatibility.
What are the kinds of changes to the JSON output that would require a new version?
Would it make sense to add the ArgumentParserToolInfo module as a product and include it in the source stability guarantees for the project?
I think that this could follow the same kind of approach as RESTful interfaces. Optional additions are considered compatible since decoding these within types that lack the additions when a payload contains those additions is not an error. The other way around is fine too since they are optional and the payload may not contain them, which results in an Optional.none case.
I’m unsure about this one. This would only be useful for SwiftPM consumers. In principle any other language that can invoke a Swift tool could consume the dumped help information. I think it might be better to write a JSON schema for this, or generate it from the ArgumentParserToolInfo module.