search

apple / swift-argument-parser

Straightforward, type-safe argument parsing for Swift
Apache License 2.0
3.31k stars 311 forks source link

[GSoC] Interactive mode for swift CLI tool ArgumentParser #449

Open KeithBird opened 2 years ago

KeithBird commented 2 years ago

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:

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

100mango commented 1 year ago

👍👍👍 When will the feature be released?

numist commented 6 months ago

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.

lionel-alves commented 2 months ago

This is great, any plan to merge this feature/interactive branch?