Skip to content

Commit b551ec8

Browse files
rauhulrauhul
authored
Add completion kind and help command to ToolInfo (#697)
Updates ToolInfo to include the built-in `help` subcommand and also include details on each argument's completion method if any.
1 parent c2d8414 commit b551ec8

24 files changed

+740
-3
lines changed

‎Sources/ArgumentParser/Usage/DumpHelpGenerator.swift

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,11 @@ fileprivate extension ArgumentSet {
8989
fileprivate extension ToolInfoV0 {
9090
init(commandStack: [ParsableCommand.Type]) {
9191
self.init(command: CommandInfoV0(commandStack: commandStack))
92+
// FIXME: This is a hack to inject the help command into the tool info
93+
// instead we should try to lift this into the parseable command tree
94+
var helpCommandInfo = CommandInfoV0(commandStack: [HelpCommand.self])
95+
helpCommandInfo.superCommands = (self.command.superCommands ?? []) + [self.command.commandName]
96+
self.command.subcommands = (self.command.subcommands ?? []) + [helpCommandInfo]
9297
}
9398
}
9499

@@ -159,6 +164,7 @@ fileprivate extension ArgumentInfoV0 {
159164
defaultValue: argument.help.defaultValue,
160165
allValueStrings: argument.help.allValueStrings,
161166
allValueDescriptions: allValueDescriptions,
167+
completionKind: ArgumentInfoV0.CompletionKindV0(completion: argument.completion),
162168
abstract: argument.help.abstract,
163169
discussion: discussion)
164170
}
@@ -194,3 +200,22 @@ fileprivate extension ArgumentInfoV0.NameInfoV0 {
194200
}
195201
}
196202
}
203+
204+
fileprivate extension ArgumentInfoV0.CompletionKindV0 {
205+
init?(completion: CompletionKind) {
206+
switch completion.kind {
207+
case .`default`:
208+
return nil
209+
case .list(let values):
210+
self = .list(values: values)
211+
case .file(let extensions):
212+
self = .file(extensions: extensions)
213+
case .directory:
214+
self = .directory
215+
case .shellCommand(let command):
216+
self = .shellCommand(command: command)
217+
case .custom(_):
218+
self = .custom
219+
}
220+
}
221+
}

‎Sources/ArgumentParserToolInfo/ToolInfo.swift

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,19 @@ public struct ArgumentInfoV0: Codable, Hashable {
133133
case flag
134134
}
135135

136+
public enum CompletionKindV0: Codable, Hashable {
137+
/// Use the specified list of completion strings.
138+
case list(values: [String])
139+
/// Complete file names with the specified extensions.
140+
case file(extensions: [String])
141+
/// Complete directory names that match the specified pattern.
142+
case directory
143+
/// Call the given shell command to generate completions.
144+
case shellCommand(command: String)
145+
/// Generate completions using the given closure.
146+
case custom
147+
}
148+
136149
/// Kind of argument the ArgumentInfo describes.
137150
public var kind: KindV0
138151

@@ -169,6 +182,11 @@ public struct ArgumentInfoV0: Codable, Hashable {
169182
/// Mapping of valid values to descriptions of the value.
170183
public var allValueDescriptions: [String: String]?
171184

185+
/// The type of completion to use for an argument or option.
186+
///
187+
/// `nil` if the tool use use the default completion kind.
188+
public var completionKind: CompletionKindV0?
189+
172190
/// Short description of the argument's functionality.
173191
public var abstract: String?
174192
/// Extended description of the argument's functionality.
@@ -186,6 +204,7 @@ public struct ArgumentInfoV0: Codable, Hashable {
186204
defaultValue: String?,
187205
allValueStrings: [String]?,
188206
allValueDescriptions: [String: String]?,
207+
completionKind: CompletionKindV0?,
189208
abstract: String?,
190209
discussion: String?
191210
) {
@@ -205,6 +224,8 @@ public struct ArgumentInfoV0: Codable, Hashable {
205224
self.allValueStrings = allValueStrings?.nonEmpty
206225
self.allValueDescriptions = allValueDescriptions?.nonEmpty
207226

227+
self.completionKind = completionKind
228+
208229
self.abstract = abstract?.nonEmpty
209230
self.discussion = discussion?.nonEmpty
210231
}

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,14 @@ This is optional.
2121
**--help:**
2222

2323
*Show help information.*
24+
25+
26+
## color.help
27+
28+
Show subcommand help information.
29+
30+
```
31+
color help [<subcommands>...]
32+
```
33+
34+
**subcommands:**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,14 @@ count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
2424
**--help:**
2525

2626
*Show help information.*
27+
28+
29+
## count-lines.help
30+
31+
Show subcommand help information.
32+
33+
```
34+
count-lines help [<subcommands>...]
35+
```
36+
37+
**subcommands:**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,3 +190,18 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<values>...] [--file=<f
190190
**--help:**
191191

192192
*Show help information.*
193+
194+
195+
196+
197+
198+
199+
## math.help
200+
201+
Show subcommand help information.
202+
203+
```
204+
math help [<subcommands>...]
205+
```
206+
207+
**subcommands:**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,14 @@ repeat [--count=<count>] [--include-counter] <phrase> [--help]
2424
**--help:**
2525

2626
*Show help information.*
27+
28+
29+
## repeat.help
30+
31+
Show subcommand help information.
32+
33+
```
34+
repeat help [<subcommands>...]
35+
```
36+
37+
**subcommands:**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,14 @@ Use this option to override the default value of a six-sided die.
3131
**--help:**
3232

3333
*Show help information.*
34+
35+
36+
## roll.help
37+
38+
Show subcommand help information.
39+
40+
```
41+
roll help [<subcommands>...]
42+
```
43+
44+
**subcommands:**

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testColorMultiPageManual().mdoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
.Nm color
77
.Sh SYNOPSIS
88
.Nm
9+
.Ar subcommand
910
.Fl -fav Ar fav
1011
.Op Fl -second Ar second
1112
.Op Fl -help
@@ -38,6 +39,35 @@ A yellow color.
3839
.It Fl h , -help
3940
Show help information.
4041
.El
42+
.Sh "SEE ALSO"
43+
.Xr color.help 9
44+
.Sh AUTHORS
45+
The
46+
.Nm
47+
reference was written by
48+
.An -nosplit
49+
.An "Jane Appleseed" ,
50+
.Mt [email protected] ,
51+
and
52+
.An -nosplit
53+
.An "The Appleseeds"
54+
.Ao
55+
.Mt [email protected]
56+
.Ac .
57+
.\" "Generated by swift-argument-parser"
58+
.Dd May 12, 1996
59+
.Dt COLOR.HELP 9
60+
.Os
61+
.Sh NAME
62+
.Nm "color help"
63+
.Nd "Show subcommand help information."
64+
.Sh SYNOPSIS
65+
.Nm
66+
.Op Ar subcommands...
67+
.Sh DESCRIPTION
68+
.Bl -tag -width 6n
69+
.It Ar subcommands...
70+
.El
4171
.Sh AUTHORS
4272
The
4373
.Nm

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testColorSinglePageManual().mdoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
.Nm color
77
.Sh SYNOPSIS
88
.Nm
9+
.Ar subcommand
910
.Fl -fav Ar fav
1011
.Op Fl -second Ar second
1112
.Op Fl -help
@@ -37,6 +38,11 @@ A yellow color.
3738
.El
3839
.It Fl h , -help
3940
Show help information.
41+
.It Em help
42+
Show subcommand help information.
43+
.Bl -tag -width 6n
44+
.It Ar subcommands...
45+
.El
4046
.El
4147
.Sh AUTHORS
4248
The

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testCountLinesMultiPageManual().mdoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
.Nm count-lines
77
.Sh SYNOPSIS
88
.Nm
9+
.Ar subcommand
910
.Op Ar input-file
1011
.Op Fl -prefix Ar prefix
1112
.Op Fl -verbose
@@ -21,6 +22,35 @@ Include extra information in the output.
2122
.It Fl h , -help
2223
Show help information.
2324
.El
25+
.Sh "SEE ALSO"
26+
.Xr count-lines.help 9
27+
.Sh AUTHORS
28+
The
29+
.Nm
30+
reference was written by
31+
.An -nosplit
32+
.An "Jane Appleseed" ,
33+
.Mt [email protected] ,
34+
and
35+
.An -nosplit
36+
.An "The Appleseeds"
37+
.Ao
38+
.Mt [email protected]
39+
.Ac .
40+
.\" "Generated by swift-argument-parser"
41+
.Dd May 12, 1996
42+
.Dt COUNT-LINES.HELP 9
43+
.Os
44+
.Sh NAME
45+
.Nm "count-lines help"
46+
.Nd "Show subcommand help information."
47+
.Sh SYNOPSIS
48+
.Nm
49+
.Op Ar subcommands...
50+
.Sh DESCRIPTION
51+
.Bl -tag -width 6n
52+
.It Ar subcommands...
53+
.El
2454
.Sh AUTHORS
2555
The
2656
.Nm

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testCountLinesSinglePageManual().mdoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
.Nm count-lines
77
.Sh SYNOPSIS
88
.Nm
9+
.Ar subcommand
910
.Op Ar input-file
1011
.Op Fl -prefix Ar prefix
1112
.Op Fl -verbose
@@ -20,6 +21,11 @@ Only count lines with this prefix.
2021
Include extra information in the output.
2122
.It Fl h , -help
2223
Show help information.
24+
.It Em help
25+
Show subcommand help information.
26+
.Bl -tag -width 6n
27+
.It Ar subcommands...
28+
.El
2329
.El
2430
.Sh AUTHORS
2531
The

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Show help information.
1919
.El
2020
.Sh "SEE ALSO"
2121
.Xr math.add 9 ,
22+
.Xr math.help 9 ,
2223
.Xr math.multiply 9 ,
2324
.Xr math.stats 9
2425
.Sh AUTHORS
@@ -262,3 +263,30 @@ and
262263
.Ao
263264
.Mt [email protected]
264265
.Ac .
266+
.\" "Generated by swift-argument-parser"
267+
.Dd May 12, 1996
268+
.Dt MATH.HELP 9
269+
.Os
270+
.Sh NAME
271+
.Nm "math help"
272+
.Nd "Show subcommand help information."
273+
.Sh SYNOPSIS
274+
.Nm
275+
.Op Ar subcommands...
276+
.Sh DESCRIPTION
277+
.Bl -tag -width 6n
278+
.It Ar subcommands...
279+
.El
280+
.Sh AUTHORS
281+
The
282+
.Nm
283+
reference was written by
284+
.An -nosplit
285+
.An "Jane Appleseed" ,
286+
.Mt [email protected] ,
287+
and
288+
.An -nosplit
289+
.An "The Appleseeds"
290+
.Ao
291+
.Mt [email protected]
292+
.Ac .

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,11 @@ Show the version.
8787
Show help information.
8888
.El
8989
.El
90+
.It Em help
91+
Show subcommand help information.
92+
.Bl -tag -width 6n
93+
.It Ar subcommands...
94+
.El
9095
.El
9196
.Sh AUTHORS
9297
The

‎Tests/ArgumentParserGenerateManualTests/Snapshots/testRepeatMultiPageManual().mdoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
.Nm repeat
77
.Sh SYNOPSIS
88
.Nm
9+
.Ar subcommand
910
.Op Fl -count Ar count
1011
.Op Fl -include-counter
1112
.Ar phrase
@@ -21,6 +22,35 @@ The phrase to repeat.
2122
.It Fl h , -help
2223
Show help information.
2324
.El
25+
.Sh "SEE ALSO"
26+
.Xr repeat.help 9
27+
.Sh AUTHORS
28+
The
29+
.Nm
30+
reference was written by
31+
.An -nosplit
32+
.An "Jane Appleseed" ,
33+
.Mt [email protected] ,
34+
and
35+
.An -nosplit
36+
.An "The Appleseeds"
37+
.Ao
38+
.Mt [email protected]
39+
.Ac .
40+
.\" "Generated by swift-argument-parser"
41+
.Dd May 12, 1996
42+
.Dt REPEAT.HELP 9
43+
.Os
44+
.Sh NAME
45+
.Nm "repeat help"
46+
.Nd "Show subcommand help information."
47+
.Sh SYNOPSIS
48+
.Nm
49+
.Op Ar subcommands...
50+
.Sh DESCRIPTION
51+
.Bl -tag -width 6n
52+
.It Ar subcommands...
53+
.El
2454
.Sh AUTHORS
2555
The
2656
.Nm

0 commit comments

Comments
 (0)