Skip to content

Commit 397d704

Browse files
natecook1000natecook1000
authored
Add DocC documentation bundle. (#347)
1 parent d4dd8e7 commit 397d704

19 files changed

+514
-101
lines changed

‎[email protected]‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// swift-tools-version:5.5
2+
//===----------------------------------------------------------*- swift -*-===//
3+
//
4+
// This source file is part of the Swift Argument Parser open source project
5+
//
6+
// Copyright (c) 2020 Apple Inc. and the Swift project authors
7+
// Licensed under Apache License v2.0 with Runtime Library Exception
8+
//
9+
// See https://swift.org/LICENSE.txt for license information
10+
//
11+
//===----------------------------------------------------------------------===//
12+
13+
import PackageDescription
14+
15+
var package = Package(
16+
name: "swift-argument-parser",
17+
products: [
18+
.library(
19+
name: "ArgumentParser",
20+
targets: ["ArgumentParser"]),
21+
],
22+
dependencies: [],
23+
targets: [
24+
.target(
25+
name: "ArgumentParser",
26+
dependencies: ["ArgumentParserToolInfo"],
27+
exclude: ["CMakeLists.txt"]),
28+
.target(
29+
name: "ArgumentParserTestHelpers",
30+
dependencies: ["ArgumentParser", "ArgumentParserToolInfo"],
31+
exclude: ["CMakeLists.txt"]),
32+
.target(
33+
name: "ArgumentParserToolInfo",
34+
dependencies: [],
35+
exclude: ["CMakeLists.txt"]),
36+
37+
.executableTarget(
38+
name: "roll",
39+
dependencies: ["ArgumentParser"],
40+
path: "Examples/roll"),
41+
.executableTarget(
42+
name: "math",
43+
dependencies: ["ArgumentParser"],
44+
path: "Examples/math"),
45+
.executableTarget(
46+
name: "repeat",
47+
dependencies: ["ArgumentParser"],
48+
path: "Examples/repeat"),
49+
50+
.executableTarget(
51+
name: "changelog-authors",
52+
dependencies: ["ArgumentParser"],
53+
path: "Tools/changelog-authors"),
54+
55+
.testTarget(
56+
name: "ArgumentParserEndToEndTests",
57+
dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
58+
exclude: ["CMakeLists.txt"]),
59+
.testTarget(
60+
name: "ArgumentParserUnitTests",
61+
dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
62+
exclude: ["CMakeLists.txt"]),
63+
.testTarget(
64+
name: "ArgumentParserExampleTests",
65+
dependencies: ["ArgumentParserTestHelpers"]),
66+
]
67+
)
68+
69+
#if swift(>=5.2)
70+
// Skip if < 5.2 to avoid issue with nested type synthesized 'CodingKeys'
71+
package.targets.append(
72+
.testTarget(
73+
name: "ArgumentParserPackageManagerTests",
74+
dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
75+
exclude: ["CMakeLists.txt"]))
76+
#endif

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

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# ``ArgumentParser``
2+
3+
Straightforward, type-safe argument parsing for Swift.
4+
5+
## Overview
6+
7+
By using `ArgumentParser`, you can create a command-line interface tool
8+
by declaring simple Swift types.
9+
Begin by declaring a type that defines
10+
the information that you need to collect from the command line.
11+
Decorate each stored property with one of `ArgumentParser`'s property wrappers,
12+
declare conformance to ``ParsableCommand``,
13+
and implement your command's logic in its `run()` method.
14+
15+
```swift
16+
import ArgumentParser
17+
18+
@main
19+
struct Repeat: ParsableCommand {
20+
@Argument(help: "The phrase to repeat.")
21+
var phrase: String
22+
23+
@Option(help: "The number of times to repeat 'phrase'.")
24+
var count: Int?
25+
26+
mutating func run() throws {
27+
let repeatCount = count ?? .max
28+
for _ in 0..<repeatCount {
29+
print(phrase)
30+
}
31+
}
32+
}
33+
```
34+
35+
When a user executes your command,
36+
the `ArgumentParser` library parses the command-line arguments,
37+
instantiates your command type,
38+
and then either calls your `run()` method or exits with a useful message.
39+
40+
```
41+
$ repeat hello --count 3
42+
hello
43+
hello
44+
hello
45+
$ repeat --help
46+
USAGE: repeat [--count <count>] <phrase>
47+
48+
ARGUMENTS:
49+
<phrase> The phrase to repeat.
50+
51+
OPTIONS:
52+
--count <count> The number of times to repeat 'phrase'.
53+
-h, --help Show help for this command.
54+
$ repeat --count 3
55+
Error: Missing expected argument 'phrase'.
56+
Help: <phrase> The phrase to repeat.
57+
Usage: repeat [--count <count>] <phrase>
58+
See 'repeat --help' for more information.
59+
```
60+
61+
## Topics
62+
63+
### Essentials
64+
65+
- <doc:GettingStarted>
66+
- <doc:CommandsAndSubcommands>
67+
- ``ParsableCommand``
68+
69+
### Arguments, Options, and Flags
70+
71+
- <doc:DeclaringArguments>
72+
- ``Argument``
73+
- ``Option``
74+
- ``Flag``
75+
- ``OptionGroup``
76+
- ``ParsableArguments``
77+
78+
### Property Customization
79+
80+
- <doc:CustomizingHelp>
81+
- ``ArgumentHelp``
82+
- ``NameSpecification``
83+
84+
### Custom Types
85+
86+
- ``ExpressibleByArgument``
87+
- ``EnumerableFlag``
88+
89+
### Validation and Errors
90+
91+
- <doc:Validation>
92+
- ``ValidationError``
93+
- ``CleanExit``
94+
- ``ExitCode``
95+
96+
### Shell Completion Scripts
97+
98+
- <doc:InstallingCompletionScripts>
99+
- <doc:CustomizingCompletions>
100+
- ``CompletionKind``
101+
102+
### Advanced Topics
103+
104+
- <doc:ManualParsing>

‎Documentation/03 Commands and Subcommands.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/CommandsAndSubcommands.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Defining Commands and Subcommands
22

3+
Break complex command-line tools into a tree of subcommands.
4+
5+
## Overview
6+
37
When command-line programs grow larger, it can be useful to divide them into a group of smaller programs, providing an interface through subcommands. Utilities such as `git` and the Swift package manager are able to provide varied interfaces for each of their sub-functions by implementing subcommands such as `git branch` or `swift package init`.
48

59
Generally, these subcommands each have their own configuration options, as well as options that are shared across several or all aspects of the larger program.

‎Documentation/07 Completion Scripts.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/CustomizingCompletions.md‎

Lines changed: 3 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,8 @@
1-
# Completion Scripts
1+
# Customizing Completions
22

3-
Generate customized completion scripts for your shell of choice.
3+
Provide custom shell completions for your command-line tool's arguments and options.
44

5-
## Generating and Installing Completion Scripts
6-
7-
Command-line tools that you build with `ArgumentParser` include a built-in option for generating completion scripts, with support for Bash, Z shell, and Fish. To generate completions, run your command with the `--generate-completion-script` flag to generate completions for the autodetected shell, or with a value to generate completions for a specific shell.
8-
9-
```
10-
$ example --generate-completion-script bash
11-
#compdef example
12-
local context state state_descr line
13-
_example_commandname="example"
14-
typeset -A opt_args
15-
16-
_example() {
17-
integer ret=1
18-
local -a args
19-
...
20-
}
21-
22-
_example
23-
```
24-
25-
The correct method of installing a completion script depends on your shell and your configuration.
26-
27-
### Installing Zsh Completions
28-
29-
If you have [`oh-my-zsh`](https://ohmyz.sh) installed, you already have a directory of automatically loading completion scripts — `.oh-my-zsh/completions`. Copy your new completion script to that directory.
30-
31-
```
32-
$ example --generate-completion-script zsh > ~/.oh-my-zsh/completions/_example
33-
```
34-
35-
> Your completion script must have the following filename format: `_example`.
36-
37-
Without `oh-my-zsh`, you'll need to add a path for completion scripts to your function path, and turn on completion script autoloading. First, add these lines to `~/.zshrc`:
38-
39-
```
40-
fpath=(~/.zsh/completion $fpath)
41-
autoload -U compinit
42-
compinit
43-
```
44-
45-
Next, create a directory at `~/.zsh/completion` and copy the completion script to the new directory.
46-
47-
### Installing Bash Completions
48-
49-
If you have [`bash-completion`](https://github.com/scop/bash-completion) installed, you can just copy your new completion script to the `/usr/local/etc/bash_completion.d` directory.
50-
51-
Without `bash-completion`, you'll need to source the completion script directly. Copy it to a directory such as `~/.bash_completions/`, and then add the following line to `~/.bash_profile` or `~/.bashrc`:
52-
53-
```
54-
source ~/.bash_completions/example.bash
55-
```
56-
57-
### Installing Fish Completions
58-
59-
Copy the completion script to any path listed in the environment variable `$fish_completion_path`. For example, a typical location is `~/.config/fish/completions/your_script.fish`.
60-
61-
## Customizing Completions
5+
## Overview
626

637
`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.
648

‎Documentation/04 Customizing Help.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Support your users (and yourself) by providing rich help for arguments and commands.
44

5+
## Overview
6+
57
You can provide help text when declaring any `@Argument`, `@Option`, or `@Flag` by passing a string literal as the `help` parameter:
68

79
```swift

‎Documentation/02 Arguments, Options, and Flags.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Use the `@Argument`, `@Option` and `@Flag` property wrappers to declare the command-line interface for your command.
44

5+
## Overview
6+
57
When creating commands, you can define three primary kinds of command-line inputs:
68

79
- *Arguments* are values given by a user and are read in order from first to last. For example, this command is called with three file names as arguments:

‎Documentation/01 Getting Started.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/GettingStarted.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
# Getting Started with `ArgumentParser`
1+
# Getting Started with ArgumentParser
22

33
Learn to set up and customize a simple command-line tool.
44

5+
## Overview
6+
57
This guide walks through building an example command. You'll learn about the different tools that `ArgumentParser` provides for defining a command's options, customizing the interface, and providing help text for your user.
68

7-
## Adding `ArgumentParser` as a Dependency
9+
## Adding ArgumentParser as a Dependency
810

911
Let's write a tool called `count` that reads an input file, counts the words, and writes the result to an output file.
1012

@@ -19,7 +21,7 @@ import PackageDescription
1921
let package = Package(
2022
name: "random",
2123
dependencies: [
22-
.package(url: "https://github.com/apple/swift-argument-parser.git", from: "0.5.0"),
24+
.package(url: "https://github.com/apple/swift-argument-parser.git", from: "0.4.0"),
2325
],
2426
targets: [
2527
.target(

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Generating and Installing Completion Scripts
2+
3+
Install shell completion scripts generated by your command-line tool.
4+
5+
## Overview
6+
7+
Command-line tools that you build with `ArgumentParser` include a built-in option for generating completion scripts, with support for Bash, Z shell, and Fish. To generate completions, run your command with the `--generate-completion-script` option to generate completions for your specific shell.
8+
9+
```
10+
$ example --generate-completion-script bash
11+
#compdef example
12+
local context state state_descr line
13+
_example_commandname="example"
14+
typeset -A opt_args
15+
16+
_example() {
17+
integer ret=1
18+
local -a args
19+
...
20+
}
21+
22+
_example
23+
```
24+
25+
The correct method of installing a completion script can depend on both your shell and your configuration.
26+
27+
### Installing Zsh Completions
28+
29+
If you have [`oh-my-zsh`](https://ohmyz.sh) installed, you already have a directory of automatically loading completion scripts — `.oh-my-zsh/completions`. Copy your new completion script to that directory.
30+
31+
```
32+
$ example --generate-completion-script zsh > ~/.oh-my-zsh/completions/_example
33+
```
34+
35+
> Your completion script must have the following filename format: `_example`.
36+
37+
Without `oh-my-zsh`, you'll need to add a path for completion scripts to your function path, and turn on completion script autoloading. First, add these lines to `~/.zshrc`:
38+
39+
```
40+
fpath=(~/.zsh/completion $fpath)
41+
autoload -U compinit
42+
compinit
43+
```
44+
45+
Next, create a directory at `~/.zsh/completion` and copy the completion script to the new directory.
46+
47+
### Installing Bash Completions
48+
49+
If you have [`bash-completion`](https://github.com/scop/bash-completion) installed, you can just copy your new completion script to the `/usr/local/etc/bash_completion.d` directory.
50+
51+
Without `bash-completion`, you'll need to source the completion script directly. Copy it to a directory such as `~/.bash_completions/`, and then add the following line to `~/.bash_profile` or `~/.bashrc`:
52+
53+
```
54+
source ~/.bash_completions/example.bash
55+
```
56+
57+
### Installing Fish Completions
58+
59+
Copy the completion script to any path listed in the environment variable `$fish_completion_path`. For example, a typical location is `~/.config/fish/completions/your_script.fish`.

‎Documentation/06 Manual Parsing and Testing.md‎ renamed to ‎Sources/ArgumentParser/Documentation.docc/Articles/ManualParsing.md‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Provide your own array of command-line inputs and work with parsed results by calling alternatives to `main()`.
44

5+
## Overview
6+
57
For most programs, calling the static `main()` method on the root command type is all that's necessary. That single call parses the command-line arguments to find the correct command from your tree of nested subcommands, instantiates and validates the result, and executes the chosen command. For more control, however, you can perform each of those steps manually.
68

79
## Parsing Arguments
@@ -28,7 +30,7 @@ The static `parseOrExit()` method either returns a fully initialized instance of
2830
We can perform validation on the inputs and exit the script if necessary:
2931

3032
```swift
31-
guard options.elements.count >= options.count else {
33+
guard let options.elements.count >= options.count else {
3234
let error = ValidationError("Please specify a 'count' less than the number of elements.")
3335
SelectOptions.exit(withError: error)
3436
}
@@ -101,12 +103,3 @@ howdy
101103
howdy
102104
hi
103105
```
104-
105-
106-
107-
108-
109-
110-
111-
112-

0 commit comments

Comments
 (0)