Retrieving a machine-readable list of possible options and arguments

[matthewbastien]

Description

The vscode-swift extension recently added support for creating a new swift project. It does so using swift package init with some user input to initialize the project with. Right now, it relies on parsing the output from swift package init --help to find the list of available project types for the --type option. However, this isn't really an ideal solution as the format could presumably change at any point (and has already drastically changed between swift 5.3 and 5.10).

Here's what the output looks like in Swift 5.8:

swift package init --help
OVERVIEW: Initialize a new package

USAGE: swift package init <options>

OPTIONS:
  --type <type>           Package type: (default: library)
        library           - A package with a library.
        executable        - A package with an executable.
        tool              - A package with an executable that uses
                            Swift Argument Parser. Use this template if you
                            plan to have a rich set of command-line arguments.
        empty             - An empty package with a Package.swift manifest.
  --name <name>           Provide custom package name
  --version               Show the version.
  -h, -help, --help       Show help information.

It would be nice to have a more reliable output format (e.g. JSON) that contains the enumerations for the --type parameter. No additional information is needed beyond what's already available in the output - the extension only needs the enum value as well as a brief description (a human readable label would be nice to include, but is not necessary as the enum value can be parsed rather easily).

Seeing as this is something that might be beneficial for other commands: it might even be a good idea to add this as a feature of swift argument parser. However, I'm raising an issue here first since this is the primary use case for the vscode-swift extension.

Expected behavior

No response

Actual behavior

No response

Steps to reproduce

No response

Swift Package Manager version/commit hash

No response

Swift & OS version (output of swift --version && uname -a)

No response

[MaxDesiatov]

I'm ok with either swift package init --list-available-options or swift package init list-options, although slightly biased towards the latter: it makes it impossible to specify ambiguous combinations like swift package init --type executable --list-available-options.

@bnbarham @bitjammer WDYT?

[rauhul]

So this is not fully supported (yet) but what about swift package init --experimental-dump-help the output of which can be parsed via swift-argument-parser's ArgumentParserToolInfo.

cc @natecook1000

[bnbarham]

My preference would be some support in swift-argument-parser to output in JSON, though interestingly in this case

  --type <type>           Package type: (default: library)
        library           - A package with a library.
        executable        - A package with an executable.
        tool              - A package with an executable that uses
                            Swift Argument Parser. Use this template if you
                            plan to have a rich set of command-line arguments.
        empty             - An empty package with a Package.swift manifest.

comes from discussion in @Option, which would have to be ignored.

From there we could have something like @rauhul --experimental-dump-help which would work anywhere.

[MaxDesiatov]

I hope JSON could also be supported that way, as that allows tools from other ecosystems to easily consume it.

[unnamedd]

If I may, I'd like to add that not only the list of --type could be converted into a JSON, but all the arguments and options. As mentioned above by @MaxDesiatov, it would allow any other use. Instead of having just a list of options, we could have a list of everything, something like:

Suggested JSON

{
  "overview": "Initialize a new package",
  "usage": "swift package init [--type <type>] [--enable-xctest] [--disable-xctest] [--enable-experimental-swift-testing] [--disable-experimental-swift-testing] [--name <name>]",
  "options": [
    {
      "description": "Package type",
      "argument": "type",
      "type": "list",
      "default": "library",
      "values": [
        {
          "value": "library",
          "decription": "A package with a library"
        },
        {
          "value": "executable",
          "decription": "A package with an executable"
        },
        {
          "value": "tool",
          "decription": "A package with an executable that uses Swift Argument Parser. Use this template if you plan to have a rich set of command-line arguments."
        },
        // ... other options
      ]
    },
    {
      "description": "Enable support for XCTest",
      "argument": "xctest",
      "type": "bool",
      "default": "false",
      "values": [
        {
          "value": "enable-xctest",
          "decription": "Enable XCTest"
        },
        {
          "value": "disable-xctest",
          "decription": "Disable XCTest"
        }
      ]
    },
    {
      "description": "Enable experimental support for swift-testing",
      "argument": "experimental-swift-testing",
      "type": "bool",
      "default": "false",
      "values": [
        {
          "value": "enable-experimental-swift-testing",
          "decription": "Enable Experimental Swift Testing"
        },
        {
          "value": "disable-experimental-swift-testing",
          "decription": "Disable Experimental Swift Testing"
        }
      ]
    },
    {
      "description": "Provide custom package name",
      "argument": "name",
      "type": "string",
      "default": ""
    },
    {
      "description": "Show the version",
      "argument": "version",
      "type": "flag",
      "default": ""
    }
  ]
}

All the options in the JSON above should be feasible to be generated by the properties declared in the user's struct that inherits from ParsableArguments.

[bnbarham]

All the options in the JSON above should be feasible to be generated by the properties declared in the user's struct that inherits from ParsableArguments.

This is why I mentioned --type above, because its documentation comes from discussion and so the proposed "values" in your JSON wouldn't actually be possible in that case - there's no way to split those values at the moment.

[natecook1000]

It seems like the request for a machine-readable list of options is satisfied by the dump-help functionality. Support for more structure in the help around values is a separate request that will need its own design – @matthewbastien, could you open that as a separate issue?