Skip to content

Commit d52044c

Browse files
natecook1000natecook1000
authored
Update documentation (#420)
Updated documentation for the 1.1 release.
1 parent d7a5a79 commit d52044c

17 files changed

+373
-174
lines changed

‎Sources/ArgumentParser/Documentation.docc/ArgumentParser.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ and then either calls your `run()` method or exits with a useful message.
4949
### Essentials
5050

5151
- <doc:GettingStarted>
52-
- <doc:CommandsAndSubcommands>
5352
- ``ParsableCommand``
53+
- ``AsyncParsableCommand``
5454

5555
### Arguments, Options, and Flags
5656

@@ -65,6 +65,7 @@ and then either calls your `run()` method or exits with a useful message.
6565

6666
- <doc:CustomizingHelp>
6767
- ``ArgumentHelp``
68+
- ``ArgumentVisibility``
6869
- ``NameSpecification``
6970

7071
### Custom Types

‎Sources/ArgumentParser/Documentation.docc/Articles/CommandsAndSubcommands.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ SUBCOMMANDS:
3535
See 'math help stats <subcommand>' for detailed help.
3636
```
3737

38-
Start by defining the root `Math` command. You can provide a static `configuration` property for a command that specifies its subcommands and a default subcommand, if any.
38+
Start by defining the root `Math` command. You can provide a static ``ParsableCommand/configuration-35km1`` property for a command that specifies its subcommands and a default subcommand, if any.
3939

4040
```swift
4141
struct Math: ParsableCommand {
@@ -53,7 +53,7 @@ struct Math: ParsableCommand {
5353
32
5454
```
5555

56-
Next, define a `ParsableArguments` type with properties that will be shared across multiple subcommands. Types that conform to `ParsableArguments` can be parsed from command-line arguments, but don't provide any execution through a `run()` method.
56+
Next, define a ``ParsableArguments`` type with properties that will be shared across multiple subcommands. Types that conform to `ParsableArguments` can be parsed from command-line arguments, but don't provide any execution through a `run()` method.
5757

5858
In this case, the `Options` type accepts a `--hexadecimal-output` flag and expects a list of integers.
5959

@@ -67,7 +67,7 @@ struct Options: ParsableArguments {
6767
}
6868
```
6969

70-
It's time to define our first two subcommands: `Add` and `Multiply`. Both of these subcommands include the arguments defined in the `Options` type by denoting that property with the `@OptionGroup` property wrapper. `@OptionGroup` doesn't define any new arguments for a command; instead, it splats in the arguments defined by another `ParsableArguments` type.
70+
It's time to define our first two subcommands: `Add` and `Multiply`. Both of these subcommands include the arguments defined in the `Options` type by denoting that property with the `@OptionGroup` property wrapper (see ``OptionGroup``). `@OptionGroup` doesn't define any new arguments for a command; instead, it splats in the arguments defined by another `ParsableArguments` type.
7171

7272
```swift
7373
extension Math {
@@ -173,10 +173,13 @@ extension Math.Statistics {
173173
}
174174
```
175175

176-
Last but not least, we kick off parsing and execution with a call to the static `main` method on the type at the root of our command tree. The call to main parses the command-line arguments, determines whether a subcommand was selected, and then instantiates and calls the `run()` method on that particular subcommand.
176+
Last but not least, we add the `@main` attribute to the root of our command tree, to tell the compiler to use that as the program's entry point. Upon execution, this parses the command-line arguments, determines whether a subcommand was selected, and then instantiates and calls the `run()` method on that particular subcommand.
177177

178178
```swift
179-
Math.main()
179+
@main
180+
struct Math: ParsableCommand {
181+
// ...
182+
}
180183
```
181184

182-
That's it for this doubly-nested `math` command! This example is also provided as a part of the `swift-argument-parser` repository, so you can see it all together and experiment with it [here](https://github.com/apple/swift-argument-parser/blob/main/Examples/math/main.swift).
185+
That's it for this doubly-nested `math` command! This example is also provided as a part of the `swift-argument-parser` repository, so you can see it all together and experiment with it [here](https://github.com/apple/swift-argument-parser/blob/main/Examples/math/Math.swift).

‎Sources/ArgumentParser/Documentation.docc/Articles/CustomizingCommandHelp.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Customizing Help for Commands
2+
3+
Define your command's abstract, extended discussion, or usage string, and set the flags used to invoke the help display.
4+
5+
## Overview
6+
7+
In addition to configuring the command name and subcommands, as described in <doc:CommandsAndSubcommands>, you can also configure a command's help text by providing an abstract, discussion, or custom usage string.
8+
9+
```swift
10+
struct Repeat: ParsableCommand {
11+
static var configuration = CommandConfiguration(
12+
abstract: "Repeats your input phrase.",
13+
usage: """
14+
repeat <phrase>
15+
repeat --count <count> <phrase>
16+
""",
17+
discussion: """
18+
Prints to stdout forever, or until you halt the program.
19+
""")
20+
21+
@Argument(help: "The phrase to repeat.")
22+
var phrase: String
23+
24+
@Option(help: "How many times to repeat.")
25+
var count: Int?
26+
27+
mutating func run() throws {
28+
for _ in 0..<(count ?? Int.max) {
29+
print(phrase)
30+
}
31+
}
32+
}
33+
```
34+
35+
The customized components now appear in the generated help screen:
36+
37+
```
38+
% repeat --help
39+
OVERVIEW: Repeats your input phrase.
40+
41+
Prints to stdout forever, or until you halt the program.
42+
43+
USAGE: repeat <phrase>
44+
repeat --count <count> <phrase>
45+
46+
ARGUMENTS:
47+
<phrase> The phrase to repeat.
48+
49+
OPTIONS:
50+
-h, --help Show help information.
51+
52+
% repeat hello!
53+
hello!
54+
hello!
55+
hello!
56+
hello!
57+
hello!
58+
hello!
59+
...
60+
```
61+
62+
## Modifying the Help Flag Names
63+
64+
Users can see the help screen for a command by passing either the `-h` or the `--help` flag, by default. If you need to use one of those flags for another purpose, you can provide alternative names when configuring a root command.
65+
66+
```swift
67+
struct Example: ParsableCommand {
68+
static let configuration = CommandConfiguration(
69+
helpNames: [.long, .customShort("?")])
70+
71+
@Option(name: .shortAndLong, help: "The number of history entries to show.")
72+
var historyDepth: Int
73+
74+
mutating func run() throws {
75+
printHistory(depth: historyDepth)
76+
}
77+
}
78+
```
79+
80+
When running the command, `-h` matches the short name of the `historyDepth` property, and `-?` displays the help screen.
81+
82+
```
83+
% example -h 3
84+
nmap -v -sS -O 10.2.2.2
85+
sshnuke 10.2.2.2 -rootpw="Z1ON0101"
86+
ssh 10.2.2.2 -l root
87+
% example -?
88+
USAGE: example --history-depth <history-depth>
89+
90+
ARGUMENTS:
91+
<phrase> The phrase to repeat.
92+
93+
OPTIONS:
94+
-h, --history-depth The number of history entries to show.
95+
-?, --help Show help information.
96+
```
97+
98+
When not overridden, custom help names are inherited by subcommands. In this example, the parent command defines `--help` and `-?` as its help names:
99+
100+
```swift
101+
struct Parent: ParsableCommand {
102+
static let configuration = CommandConfiguration(
103+
subcommands: [Child.self],
104+
helpNames: [.long, .customShort("?")])
105+
106+
struct Child: ParsableCommand {
107+
@Option(name: .shortAndLong, help: "The host the server will run on.")
108+
var host: String
109+
}
110+
}
111+
```
112+
113+
The `child` subcommand inherits the parent's help names, allowing the user to distinguish between the host argument (`-h`) and help (`-?`).
114+
115+
```
116+
% parent child -h 192.0.0.0
117+
...
118+
% parent child -?
119+
USAGE: parent child --host <host>
120+
121+
OPTIONS:
122+
-h, --host <host> The host the server will run on.
123+
-?, --help Show help information.
124+
```
125+
126+
## Hiding Commands
127+
128+
You may not want to show every one of your command as part of your command-line interface. To render a command invisible (but still usable), pass `shouldDisplay: false` to the ``CommandConfiguration`` initializer.
129+
130+
## Generating Help Text Programmatically
131+
132+
The help screen is automatically shown to users when they call your command with the help flag. You can generate the same text from within your program by calling the `helpMessage()` method.
133+
134+
```swift
135+
let help = Repeat.helpMessage()
136+
// `help` matches the output above
137+
138+
let fortyColumnHelp = Repeat.helpMessage(columns: 40)
139+
// `fortyColumnHelp` is the same help screen, but wrapped to 40 columns
140+
```
141+
142+
When generating help text for a subcommand, call `helpMessage(for:)` on the `ParsableCommand` type that represents the root of the command tree and pass the subcommand type as a parameter to ensure the correct display.

‎Sources/ArgumentParser/Documentation.docc/Articles/CustomizingCompletions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Provide custom shell completions for your command-line tool's arguments and opti
66

77
`ArgumentParser` provides default completions for any types that it can. For example, an `@Option` property that is a `CaseIterable` type will automatically have the correct values as completion suggestions.
88

9-
When declaring an option or argument, you can customize the completions that are offered by specifying a `CompletionKind`. With this completion kind you can specify that the value should be a file, a directory, or one of a list of strings:
9+
When declaring an option or argument, you can customize the completions that are offered by specifying a ``CompletionKind``. With this completion kind you can specify that the value should be a file, a directory, or one of a list of strings:
1010

1111
```swift
1212
struct Example: ParsableCommand {
@@ -30,7 +30,7 @@ struct Example: ParsableCommand {
3030

3131
The generated completion script will suggest only file names for the `--input` option, only directory names for `--output-dir`, and only the strings `markdown` and `rst` for `--format`. The `--compression` option uses the default completions for a `CaseIterable` type, so the completion script will suggest `zip` and `gzip`.
3232

33-
You can define the default completion kind for custom `ExpressibleByArgument` types by implementing `static var defaultCompletionKind: CompletionKind`. For example, any arguments or options with this `File` type will automatically use files for completions:
33+
You can define the default completion kind for custom ``ExpressibleByArgument`` types by implementing ``ExpressibleByArgument/defaultCompletionKind-866se``. For example, any arguments or options with this `File` type will automatically use files for completions:
3434

3535
```swift
3636
struct File: Hashable, ExpressibleByArgument {

0 commit comments

Comments
 (0)