swift-argument-parser
swift-argument-parser copied to clipboard
apple
[GSoC] Interactive mode for swift CLI tool ArgumentParser
Introduction
ArgumentParser provides a straightforward way to declare command-line interfaces in Swift, with the dual goals of making it (1) fast and easy to create (2) high-quality, user-friendly CLI tools.
In order to further achieve these two goals, for this project, we designed and implemented an interactive mode for tools built using ArgumentParser. This mode can prompt for required arguments not given in the initial command, suggest possible corrections when user input is invalid, help users learn to use unfamiliar command line tools by trial and error.
This project was also done as a GSoC (Google Summer of Code) project for which you can find here.
Motivation
With server side swift gaining more and more traction, command line apps built with ArgumentParser can be very useful for automating common tasks to boost developer productivity. But there are still many developers don’t want to bother with the command line, because the help text came in the form of thick manuals and error messages were opaque.
For example, in the past, users would get lengthy error messages when required arguments are not initialized:
$ repeat
Error: Missing expected argument '<phrase>'
USAGE: repeat [--count <count>] [--include-counter] <phrase>
ARGUMENTS:
<phrase> The phrase to repeat.
OPTIONS:
--count <count> The number of times to repeat 'phrase'.
--include-counter Include a counter with each repetition.
-h, --help Show help information.
$ repeat hello world
hello world
hello world
Introducing the conversational nature of interactive mode will be very helpful, it can reduce duplication and provide a conversational CLI which is both easier to write and easier to read:
$ repeat
? Please enter 'phrase': hello world
hello world
hello world
Achievements
Ask prompt the user for input
let age = ask("? Please enter your age: ", type: Int.self)
The above code will generate the following dialog:
? Please enter your age: keith
Error: The type of 'keith' is not Int.
? Please enter your age: 18
Check verifies key directives
guard
check("Are you sure you want to delete all?")
else { return }
print("---DELETE---")
The above code will generate the following dialog:
Are you sure you want to delete all?
? Please enter [y]es or [n]o: y
---DELETE---
Choose provides possible input for the user to choose from
let selected = choose("Please pick your favorite colors: ",
from: ["pink", "purple", "silver"])
The above code will generate the following dialog:
1. pink
2. purple
3. silver
Please pick your favorite colors: pink
Error: 'pink' is not a serial number.
Please pick your favorite colors: 0 1
Error: '0' is not in the range 1 - 3.
Please pick your favorite colors: 1 2
Ask for required @Argument
When parameters similar to the following are not initialized:
@Argument var values: [Int]
The following dialog will be generated automatically:
? Please enter 'values': 1 2 3
Ask for required @Option
When parameters similar to the following are not initialized:
@Option var userName: String
The following dialog will be generated automatically:
? Please enter 'userName': keith
Ask for required @Flag: EnumerableFlag
When parameters similar to the following are not initialized:
enum ColorFlag: EnumerableFlag {
case pink, purple, silver
}
@Flag var color: ColorFlag
The following dialog will be generated automatically:
1. --pink
2. --purple
3. --silver
? Please select 'color': --silver
Error: '--silver' is not a serial number.
? Please select 'color': 4
Error: '4' is not in the range 1 - 3.
? Please select 'color': 3
You select '--silver'.
Asking to retype an invalid value
When parameters similar to the following are not initialized:
@Argument var values: [Int]
The following dialog will be generated automatically:
Please enter 'values': a
Error: The value 'a' is invalid for '<values>'.
? Please replace 'a': 0.1
Error: The value '0.1' is invalid for '<values>'.
? Please replace '0.1': 2
The above is just a partial display of the interfaces. For more details, please click the links in the implementation section.
Implementation
This project is implemented by the following subtasks, you can click to see more detailed API design:
-
#448
-
#450
-
#453
-
#467
-
#469
-
#459
-
#462
Future Work
Fixing misspelled arguments
If a user mistypes an option, flag, or command, the interactive mode should suggest possible correction:
% example --indx 5
Error: Unexpected argument '--indx', did you mean '--index'?
? Please enter [y]es or [n]o: y
Merge two canInteract() functions
Since the two canInteract() one modifies the SplitArguments and the other modifies the ParsedValues, it's not a good idea to merge them for now. But it could make more sense if there's only one path for interactively collecting additional input. So we need find a way to handle .missingValueForOption error without modifying the the original input, which is surely going to be more error prone than operating on the more structured parsed value data.
The discussion under the #451 provides more details.
Related Links
On the topic of future work, one thing I've done in other tools that's enabled by this is to automatically prefix-match options/subcommands when there is no ambiguity. This obviously requires interactive mode detection to ensure shell scripts aren't broken by new options/subcommands being added in the future.
