Add new built-in flag `--dump-help` #310

KS1019 · 2021-05-17T09:46:21Z

This PR resolves #164 and adds a new built-in flag --dump-help to dump all the help information in JSON format. This feature can be useful when parsing help information and generating documentation for a command. I will add documentation if necessary. In that case, I would appreciate it if anyone could direct me to the right place to add the documentation.

Checklist

I've added at least one test that validates that my change is working, if appropriate
I've followed the code style of the rest of the project
I've read the Contribution Guidelines
I've updated the documentation if necessary

This commit will add a new builtin option named `--dump-help-info` which outputs help information in JSON.

KS1019 · 2021-05-17T09:48:12Z

@natecook1000 Please take a look when you have time. Thank you!

Edit: ~~I did not realize the conflicts when I made PR and I will need a little more time to resolve them so I am making this a Draft PR.~~

I have resolved the conflicts so please take a look. Thank you!

natecook1000

Looks like a good start, @KS1019! I haven't gotten a chance to review DumpHelpInfoGenerator yet, but wanted to give you a couple notes here.

natecook1000 · 2021-05-19T15:16:45Z

Sources/ArgumentParser/Parsing/CommandParser.swift

+    // Look for `--dump-help`
+    guard !split.contains(Name.long("dump-help")) else {
+      throw DumpHelpInfoRequested()
+    }


I'd rather handle this the same way as --version rather than than going through than separate DumpHelpInfoCommand command. HelpCommand exists so that you can write things like example help sub1 sub2, but that won't be the case here, it's just a short-circuiting flag.

At 4d97d0c, I modified the code to throw CommandError like --version does. I will look into more if I can remove DumpHelpInfoCommand completely.

I removed DumpHelpInfoRequested and DumpHelpInfoCommand at 9825ecb

natecook1000 · 2021-05-19T15:27:51Z

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -185,6 +185,7 @@ internal struct HelpGenerator {
        optionElements.append(element)
      }
    }
+    optionElements.append(.init(label: "--dump-help", abstract: "Dump help information."))


Let's leave this out of the help screen for now. I'd like to eventually add a version of the help screen that includes hidden flags, etc (via something like example --help --all or example --help-all), so this could show up as part of that.

Addressed at 40de584

natecook1000 · 2021-05-19T21:52:39Z

Sources/ArgumentParser/Usage/DumpHelpInfoGenerator.swift

+@_implementationOnly import Foundation
+
+internal struct DumpHelpInfoGenerator {
+  struct CommandInfo: Codable {


I think CommandInfo and ArgumentInfo will probably be independently useful — can you move them out to be top-level types?

Addressed at 94a81ed

natecook1000 · 2021-05-19T21:53:06Z

Sources/ArgumentParser/Usage/DumpHelpInfoGenerator.swift

+      var isDefault: Bool?
+    }
+
+    var command: ArgumentInfo


Let's not re-use this for the command's metadata — should be okay to just put the command-specific details right here instead.

Fixed at 9c8e5a7

natecook1000 · 2021-06-11T17:18:26Z

@swift-ci Please test

…ment-parser into dump-help-info

KS1019 · 2021-06-23T09:23:37Z

Hi @natecook1000
I fixed codes that had compilation errors and made changes to follow the upstream changes. Please take a look again when you have time!

natecook1000 · 2021-06-29T06:43:17Z

@swift-ci Please test

natecook1000 · 2021-07-01T17:17:55Z

@swift-ci Please test Linux platform

KS1019 · 2021-07-01T17:32:50Z

Hi @natecook1000

It seems that tests are failing on the Linux Platform because specifying only encoder.outputFormatting = .prettyPrinted gives me same JSON but in different order depending on platforms.

I am considering adding .sortedKeys to encoder.outputFormatting but since they are available only on macOS 10.13 or newer, I am not sure if that's the best option.

Alternatively, I think we can change how we test the generated JSON from comparing them as strings to comparing them as values by converting them back to the codable values.

I would love to know what do your think the best way would be to solve the problem!

natecook1000 · 2021-07-02T16:35:32Z

@KS1019 I think it would be fine to round trip through JSON and check for equality with the expectation that way. String equality for JSON is definitely tricky due to its order independence. Thanks!

…ommandInfo as public.

KS1019 · 2021-07-03T10:35:11Z

@natecook1000
I've made changes to address the issues with testing JSONs. Please take a look when you have time!

…into dump-help-info

natecook1000 · 2021-07-07T16:16:34Z

@swift-ci Please test

Repair the build after apple#310 to allow building with CMake which is required for bootstrapping.

compnerd · 2021-07-08T22:31:22Z

This regressed the Windows build :-( (#336 should repair that)

Repair the build after #310 to allow building with CMake which is required for bootstrapping.

KS1019 added 8 commits May 17, 2021 00:08

Add builtin --dump-help-info

aef205c

This commit will add a new builtin option named `--dump-help-info` which outputs help information in JSON.

Fix DumpHelpInfoGenerator

d2a315b

Modify Test helper

c205b86

Add --dump-help Dump help information. to test cases

e7eecfc

Add new test for DumpHelpGenerationTests

d5354b2

Add code to generate completion for --dump-help

3d64ead

Fix CompletionScriptTests

1f86f59

Fix MathExampleTests

8ea949b

KS1019 marked this pull request as draft May 17, 2021 10:16

KS1019 added 4 commits May 17, 2021 20:02

Merge branch 'main' into dump-help-info

510aa98

Fix comments

b85d887

Fix styling

5c63d91

Fix indentation

29ba70b

KS1019 marked this pull request as ready for review May 17, 2021 11:16

natecook1000 reviewed May 19, 2021

View reviewed changes

KS1019 added 9 commits May 20, 2021 17:53

Merge branch 'apple:main' into dump-help-info

3d94dc1

Fix test case

31cc24d

Throw CommandError instead of DumpHelpInfoRequested

4d97d0c

Remove --dump-help from help screen.

40de584

Fix tests

3f9cfe2

Move CommandInfo and ArgumentInfo to be top level types

94a81ed

Fix DumpHelpInfoGenerator

9c8e5a7

Add HelpInfo type to keep the JSON structure.

8ee5bb1

Remove DumpHelpInfoRequested and DumpHelpInfoCommand

9825ecb

KS1019 added 3 commits June 13, 2021 17:10

Merge branch 'apple:main' into dump-help-info

59e0a99

Fix compilation errors

4b12174

Fix tests

b76aa40

KS1019 added 5 commits June 13, 2021 18:06

Add condition when collecting names

609f177

Fix getHelpInfo function

7e77e2f

Fix test case

43d018c

Merge branch 'apple:main' into dump-help-info

94573f5

Merge branch 'dump-help-info' of https://github.com/KS1019/swift-argu…

17ff237

…ment-parser into dump-help-info

Add new functions for testing and expose HelpInfo, ArgumentInfo and C…

0233924

…ommandInfo as public.

Merge branch 'main' of https://github.com/apple/swift-argument-parser …

c69f4b7

…into dump-help-info

natecook1000 merged commit cfcb9cb into apple:main Jul 7, 2021

KS1019 deleted the dump-help-info branch July 8, 2021 06:50

compnerd added a commit to compnerd/swift-argument-parser that referenced this pull request Jul 8, 2021

build: update CMakeLists.txt for new source

5c70130

Repair the build after apple#310 to allow building with CMake which is required for bootstrapping.

compnerd mentioned this pull request Jul 8, 2021

build: update CMakeLists.txt for new source #336

Merged

4 tasks

natecook1000 pushed a commit that referenced this pull request Jul 9, 2021

build: update CMakeLists.txt for new source (#336)

19a5e2a

Repair the build after #310 to allow building with CMake which is required for bootstrapping.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new built-in flag `--dump-help` #310

Add new built-in flag `--dump-help` #310

KS1019 commented May 17, 2021 •

edited

KS1019 commented May 17, 2021 •

edited

natecook1000 left a comment

natecook1000 May 19, 2021

KS1019 May 20, 2021

KS1019 May 20, 2021

natecook1000 May 19, 2021

KS1019 May 20, 2021 •

edited

natecook1000 May 19, 2021

KS1019 May 20, 2021

natecook1000 May 19, 2021

KS1019 May 20, 2021

natecook1000 commented Jun 11, 2021

KS1019 commented Jun 23, 2021

natecook1000 commented Jun 29, 2021

natecook1000 commented Jul 1, 2021

KS1019 commented Jul 1, 2021

natecook1000 commented Jul 2, 2021

KS1019 commented Jul 3, 2021

natecook1000 commented Jul 7, 2021

compnerd commented Jul 8, 2021

Add new built-in flag --dump-help #310

Add new built-in flag --dump-help #310

Conversation

KS1019 commented May 17, 2021 • edited

Checklist

KS1019 commented May 17, 2021 • edited

natecook1000 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KS1019 May 20, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

natecook1000 commented Jun 11, 2021

KS1019 commented Jun 23, 2021

natecook1000 commented Jun 29, 2021

natecook1000 commented Jul 1, 2021

KS1019 commented Jul 1, 2021

natecook1000 commented Jul 2, 2021

KS1019 commented Jul 3, 2021

natecook1000 commented Jul 7, 2021

compnerd commented Jul 8, 2021

Add new built-in flag `--dump-help` #310

Add new built-in flag `--dump-help` #310

KS1019 commented May 17, 2021 •

edited

KS1019 commented May 17, 2021 •

edited

KS1019 May 20, 2021 •

edited