From f23b523272a8b89620669080247ef41248936212 Mon Sep 17 00:00:00 2001 From: Rauhul Varma Date: Thu, 25 Aug 2022 00:50:44 -0700 Subject: [PATCH 1/2] Fix missing option value names in manuals - Fixes a manual generation bug where options in the synopsis were not given an option value name and flags were. --- .../CountLinesGenerateManualTests.swift | 12 ++--- .../MathGenerateManualTests.swift | 54 +++++++++---------- .../RepeatGenerateManualTests.swift | 12 ++--- .../RollDiceGenerateManualTests.swift | 20 +++---- .../DSL/ArgumentSynopsis.swift | 2 +- 5 files changed, 50 insertions(+), 50 deletions(-) diff --git a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift index fd9f824a3..6f0aeea4b 100644 --- a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift @@ -27,9 +27,9 @@ final class CountLinesGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar input-file - .Op Fl -prefix - .Op Fl -verbose Ar verbose - .Fl -help Ar help + .Op Fl -prefix Ar prefix + .Op Fl -verbose + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar input-file @@ -68,9 +68,9 @@ final class CountLinesGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar input-file - .Op Fl -prefix - .Op Fl -verbose Ar verbose - .Fl -help Ar help + .Op Fl -prefix Ar prefix + .Op Fl -verbose + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar input-file diff --git a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift index 34187d8e5..4c3c70c9f 100644 --- a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift @@ -26,8 +26,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -130,8 +130,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -164,10 +164,10 @@ final class MathGenerateManualTests: XCTestCase { .Nd "Print the sum of the values." .Sh SYNOPSIS .Nm - .Op Fl -hex-output Ar hex-output + .Op Fl -hex-output .Op Ar values... - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl x , -hex-output @@ -200,10 +200,10 @@ final class MathGenerateManualTests: XCTestCase { .Nd "Print the product of the values." .Sh SYNOPSIS .Nm - .Op Fl -hex-output Ar hex-output + .Op Fl -hex-output .Op Ar values... - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl x , -hex-output @@ -237,8 +237,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -271,10 +271,10 @@ final class MathGenerateManualTests: XCTestCase { .Nd "Print the average of the values." .Sh SYNOPSIS .Nm - .Op Fl -kind + .Op Fl -kind Ar kind .Op Ar values... - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -kind Ar kind @@ -308,8 +308,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Op Ar values... - .Fl -version Ar version - .Fl -help Ar help + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar values... @@ -343,16 +343,16 @@ final class MathGenerateManualTests: XCTestCase { .Op Ar one-of-four .Op Ar custom-arg .Op Ar values... - .Op Fl -test-success-exit-code Ar test-success-exit-code - .Op Fl -test-failure-exit-code Ar test-failure-exit-code - .Op Fl -test-validation-exit-code Ar test-validation-exit-code - .Op Fl -test-custom-exit-code - .Op Fl -file - .Op Fl -directory - .Op Fl -shell - .Op Fl -custom - .Fl -version Ar version - .Fl -help Ar help + .Op Fl -test-success-exit-code + .Op Fl -test-failure-exit-code + .Op Fl -test-validation-exit-code + .Op Fl -test-custom-exit-code Ar test-custom-exit-code + .Op Fl -file Ar file + .Op Fl -directory Ar directory + .Op Fl -shell Ar shell + .Op Fl -custom Ar custom + .Fl -version + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar one-of-four diff --git a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift index c4ba9f728..ec233eb3d 100644 --- a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift @@ -23,10 +23,10 @@ final class RepeatGenerateManualTests: XCTestCase { .Nm repeat .Sh SYNOPSIS .Nm - .Op Fl -count - .Op Fl -include-counter Ar include-counter + .Op Fl -count Ar count + .Op Fl -include-counter .Ar phrase - .Fl -help Ar help + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -count Ar count @@ -63,10 +63,10 @@ final class RepeatGenerateManualTests: XCTestCase { .Nm repeat .Sh SYNOPSIS .Nm - .Op Fl -count - .Op Fl -include-counter Ar include-counter + .Op Fl -count Ar count + .Op Fl -include-counter .Ar phrase - .Fl -help Ar help + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -count Ar count diff --git a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift index 115e46ddf..7b2eb5e25 100644 --- a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift @@ -23,11 +23,11 @@ final class RollDiceGenerateManualTests: XCTestCase { .Nm roll .Sh SYNOPSIS .Nm - .Op Fl -times - .Op Fl -sides - .Op Fl -seed - .Op Fl -verbose Ar verbose - .Fl -help Ar help + .Op Fl -times Ar n + .Op Fl -sides Ar m + .Op Fl -seed Ar seed + .Op Fl -verbose + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -times Ar n @@ -68,11 +68,11 @@ final class RollDiceGenerateManualTests: XCTestCase { .Nm roll .Sh SYNOPSIS .Nm - .Op Fl -times - .Op Fl -sides - .Op Fl -seed - .Op Fl -verbose Ar verbose - .Fl -help Ar help + .Op Fl -times Ar n + .Op Fl -sides Ar m + .Op Fl -seed Ar seed + .Op Fl -verbose + .Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -times Ar n diff --git a/Tools/generate-manual/DSL/ArgumentSynopsis.swift b/Tools/generate-manual/DSL/ArgumentSynopsis.swift index e57eb42b5..7176726df 100644 --- a/Tools/generate-manual/DSL/ArgumentSynopsis.swift +++ b/Tools/generate-manual/DSL/ArgumentSynopsis.swift @@ -32,11 +32,11 @@ struct ArgumentSynopsis: MDocComponent { // preferredName cannot be nil let name = argument.preferredName! return MDocMacro.CommandOption(options: [name.manualPage]) + .withUnsafeChildren(nodes: [argument.manualPageValueName]) case .flag: // preferredName cannot be nil let name = argument.preferredName! return MDocMacro.CommandOption(options: [name.manualPage]) - .withUnsafeChildren(nodes: [argument.manualPageValueName]) } } } From 82f4b3b0dc726effa4d4e064354337c1eb280454 Mon Sep 17 00:00:00 2001 From: Rauhul Varma Date: Thu, 25 Aug 2022 01:19:36 -0700 Subject: [PATCH 2/2] Fixup help options for built-in flags - Fixes a bug where built-in flags such as --help and --version were not properly marked with isOptional which resulted in them appearing in generated content (such as completion scripts and manuals) as required arguments. --- .../ArgumentParser/Usage/HelpGenerator.swift | 11 +++- .../CountLinesGenerateManualTests.swift | 4 +- .../MathGenerateManualTests.swift | 32 +++++------ .../RepeatGenerateManualTests.swift | 4 +- .../RollDiceGenerateManualTests.swift | 4 +- .../DumpHelpGenerationTests.swift | 54 +++++++++---------- 6 files changed, 58 insertions(+), 51 deletions(-) diff --git a/Sources/ArgumentParser/Usage/HelpGenerator.swift b/Sources/ArgumentParser/Usage/HelpGenerator.swift index b216aa255..3f09f13b3 100644 --- a/Sources/ArgumentParser/Usage/HelpGenerator.swift +++ b/Sources/ArgumentParser/Usage/HelpGenerator.swift @@ -307,7 +307,10 @@ internal extension BidirectionalCollection where Element == ParsableCommand.Type else { return nil } return ArgumentDefinition( kind: .named([.long("version")]), - help: .init(help: "Show the version.", key: InputKey(rawValue: "")), + help: .init( + options: [.isOptional], + help: "Show the version.", + key: InputKey(rawValue: "")), completion: .default, update: .nullary({ _, _, _ in }) ) @@ -318,7 +321,10 @@ internal extension BidirectionalCollection where Element == ParsableCommand.Type guard !names.isEmpty else { return nil } return ArgumentDefinition( kind: .named(names), - help: .init(help: "Show help information.", key: InputKey(rawValue: "")), + help: .init( + options: [.isOptional], + help: "Show help information.", + key: InputKey(rawValue: "")), completion: .default, update: .nullary({ _, _, _ in }) ) @@ -328,6 +334,7 @@ internal extension BidirectionalCollection where Element == ParsableCommand.Type return ArgumentDefinition( kind: .named([.long("experimental-dump-help")]), help: .init( + options: [.isOptional], help: ArgumentHelp("Dump help information as JSON."), key: InputKey(rawValue: "")), completion: .default, diff --git a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift index 6f0aeea4b..293707e6b 100644 --- a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift @@ -29,7 +29,7 @@ final class CountLinesGenerateManualTests: XCTestCase { .Ar input-file .Op Fl -prefix Ar prefix .Op Fl -verbose - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar input-file @@ -70,7 +70,7 @@ final class CountLinesGenerateManualTests: XCTestCase { .Ar input-file .Op Fl -prefix Ar prefix .Op Fl -verbose - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar input-file diff --git a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift index 4c3c70c9f..ebc925e13 100644 --- a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift @@ -26,8 +26,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -130,8 +130,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -166,8 +166,8 @@ final class MathGenerateManualTests: XCTestCase { .Nm .Op Fl -hex-output .Op Ar values... - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl x , -hex-output @@ -202,8 +202,8 @@ final class MathGenerateManualTests: XCTestCase { .Nm .Op Fl -hex-output .Op Ar values... - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl x , -hex-output @@ -237,8 +237,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Ar subcommand - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -version @@ -273,8 +273,8 @@ final class MathGenerateManualTests: XCTestCase { .Nm .Op Fl -kind Ar kind .Op Ar values... - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -kind Ar kind @@ -308,8 +308,8 @@ final class MathGenerateManualTests: XCTestCase { .Sh SYNOPSIS .Nm .Op Ar values... - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar values... @@ -351,8 +351,8 @@ final class MathGenerateManualTests: XCTestCase { .Op Fl -directory Ar directory .Op Fl -shell Ar shell .Op Fl -custom Ar custom - .Fl -version - .Fl -help + .Op Fl -version + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Ar one-of-four diff --git a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift index ec233eb3d..57618cc14 100644 --- a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift @@ -26,7 +26,7 @@ final class RepeatGenerateManualTests: XCTestCase { .Op Fl -count Ar count .Op Fl -include-counter .Ar phrase - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -count Ar count @@ -66,7 +66,7 @@ final class RepeatGenerateManualTests: XCTestCase { .Op Fl -count Ar count .Op Fl -include-counter .Ar phrase - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -count Ar count diff --git a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift index 7b2eb5e25..eaa5120eb 100644 --- a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift +++ b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift @@ -27,7 +27,7 @@ final class RollDiceGenerateManualTests: XCTestCase { .Op Fl -sides Ar m .Op Fl -seed Ar seed .Op Fl -verbose - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -times Ar n @@ -72,7 +72,7 @@ final class RollDiceGenerateManualTests: XCTestCase { .Op Fl -sides Ar m .Op Fl -seed Ar seed .Op Fl -verbose - .Fl -help + .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n .It Fl -times Ar n diff --git a/Tests/ArgumentParserUnitTests/DumpHelpGenerationTests.swift b/Tests/ArgumentParserUnitTests/DumpHelpGenerationTests.swift index b05e82656..f207ac929 100644 --- a/Tests/ArgumentParserUnitTests/DumpHelpGenerationTests.swift +++ b/Tests/ArgumentParserUnitTests/DumpHelpGenerationTests.swift @@ -180,7 +180,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -214,7 +214,7 @@ extension DumpHelpGenerationTests { "arguments" : [ { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -232,7 +232,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -290,7 +290,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -308,7 +308,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -369,7 +369,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -387,7 +387,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -418,7 +418,7 @@ extension DumpHelpGenerationTests { "arguments" : [ { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -436,7 +436,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -496,7 +496,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -514,7 +514,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -554,7 +554,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -572,7 +572,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -762,7 +762,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -780,7 +780,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -855,7 +855,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -873,7 +873,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -940,7 +940,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -958,7 +958,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -995,7 +995,7 @@ extension DumpHelpGenerationTests { "arguments" : [ { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1013,7 +1013,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1073,7 +1073,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1091,7 +1091,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1131,7 +1131,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1149,7 +1149,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1339,7 +1339,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show the version.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [ @@ -1357,7 +1357,7 @@ extension DumpHelpGenerationTests { }, { "abstract" : "Show help information.", - "isOptional" : false, + "isOptional" : true, "isRepeating" : false, "kind" : "flag", "names" : [