Improve zsh completion for repeatable options (#614)

Some commands allow an option to be repeated to provide multiple values.
For example, ssh allows the -L flag to be repeated to establish multiple
port forwardings.

ArgumentParser supports this style when the Option value is an Array
and the parsingStrategy is ArrayParsingStrategy.singleValue or
.unconditionalSingleValue.

Without this patch, ArgumentParser generates a zsh completion script
that does not handle repeatable options correctly. The generated script
suppresses completion of any option after that option's first use, even
if the option is repeatable.

With this patch, ArgumentParser generates a zsh completion script that
allows a repeatable option to be completed each time it is used.

The relevant zsh _arguments syntax is documented here:
https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Completion-Functions

Specifically, a repeatable option's optspec needs to start with '*'.
Furthermore, a repeatable argument must not list itself or its synonyms
in its own parenthesized suppression list. (This is not clearly
documented.)

fixes #564

* Add test for repeated flag completions

Author: mayoff

Sources/ArgumentParser/Completions/ZshCompletionsGenerator.swift

@@ -137,7 +137,7 @@ extension ArgumentDefinition {
   func zshCompletionString(_ commands: [ParsableCommand.Type]) -> String? {
     guard help.visibility.base == .default else { return nil }
 
-    var inputs: String
+    let inputs: String
     switch update {
     case .unary:
       inputs = ":\(valueName):\(zshActionString(commands))"
@@ -150,13 +150,15 @@ extension ArgumentDefinition {
     case 0:
       line = ""
     case 1:
+      let star = isRepeatableOption ? "*" : ""
       line = """
-      \(names[0].synopsisString)\(zshCompletionAbstract)
+      \(star)\(names[0].synopsisString)\(zshCompletionAbstract)
       """
     default:
       let synopses = names.map { $0.synopsisString }
+      let suppression = isRepeatableOption ? "*" : "(\(synopses.joined(separator: " ")))"
       line = """
-      (\(synopses.joined(separator: " ")))'\
+      \(suppression)'\
       {\(synopses.joined(separator: ","))}\
       '\(zshCompletionAbstract)
       """
@@ -165,6 +167,19 @@ extension ArgumentDefinition {
     return "'\(line)\(inputs)'"
   }
 
+  /// - returns: `true` if I'm an option and can be tab-completed multiple times in one command line. For example, `ssh` allows the `-L` option to be given multiple times, to establish multiple port forwardings.
+  private var isRepeatableOption: Bool {
+    guard
+      case .named(_) = kind,
+      help.options.contains(.isRepeating)
+    else { return false }
+
+    switch parsingStrategy {
+    case .default, .unconditional: return true
+    default: return false
+    }
+  }
+
   /// Returns the zsh "action" for an argument completion string.
   func zshActionString(_ commands: [ParsableCommand.Type]) -> String {
     switch completion.kind {

Tests/ArgumentParserUnitTests/CompletionScriptTests.swift

@@ -29,7 +29,7 @@ extension CompletionScriptTests {
     }
   }
 
-  enum Kind: String, ExpressibleByArgument, CaseIterable {
+  enum Kind: String, ExpressibleByArgument, EnumerableFlag {
     case one, two, three = "custom-three"
   }
 
@@ -48,6 +48,11 @@ extension CompletionScriptTests {
     @Option(completion: .list(["a", "b", "c"])) var path3: Path
 
     @Flag(help: .hidden) var verbose = false
+    @Flag var allowedKinds: [Kind] = []
+    @Flag var kindCounter: Int
+    
+    @Option() var rep1: [String]
+    @Option(name: [.short, .long]) var rep2: [String]
 
    struct SubCommand: ParsableCommand {
      static var configuration = CommandConfiguration(
@@ -164,6 +169,12 @@ _base-test() {
         '--path1:path1:_files'
         '--path2:path2:_files'
         '--path3:path3:(a b c)'
+        '--one'
+        '--two'
+        '--three'
+        '*--kind-counter'
+        '*--rep1:rep1:'
+        '*'{-r,--rep2}':rep2:'
         '(-h --help)'{-h,--help}'[Show help information.]'
         '(-): :->command'
         '(-)*:: :->arg'
@@ -231,7 +242,7 @@ _base_test() {
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
     COMPREPLY=()
-    opts="--name --kind --other-kind --path1 --path2 --path3 -h --help sub-command help"
+    opts="--name --kind --other-kind --path1 --path2 --path3 --one --two --three --kind-counter --rep1 -r --rep2 -h --help sub-command help"
     if [[ $COMP_CWORD == "1" ]]; then
         COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
         return
@@ -269,6 +280,14 @@ _base_test() {
             COMPREPLY=( $(compgen -W "a b c" -- "$cur") )
             return
         ;;
+        --rep1)
+
+            return
+        ;;
+        -r|--rep2)
+
+            return
+        ;;
     esac
     case ${COMP_WORDS[1]} in
         (sub-command)
@@ -370,12 +389,18 @@ function _swift_base-test_using_command
 end
 
 complete -c base-test -n '_swift_base-test_using_command "base-test sub-command"' -s h -l help -d 'Show help information.'
-complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l name -d 'The user\\\'s name.'
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l name -d 'The user\\'s name.'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l kind -r -f -k -a 'one two custom-three'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l other-kind -r -f -k -a '1 2 3'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l path1 -r -f -a '(for i in *.{}; echo $i;end)'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l path2 -r -f -a '(for i in *.{}; echo $i;end)'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l path3 -r -f -k -a 'a b c'
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l one
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l two
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l three
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l kind-counter
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -l rep1
+complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -s r -l rep2
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -s h -l help -d 'Show help information.'
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -f -a 'sub-command' -d ''
 complete -c base-test -n '_swift_base-test_using_command "base-test" "sub-command help"' -f -a 'help' -d 'Show subcommand help information.'