Refactor bash completions to use ToolInfoV0.

Signed-off-by: Ross Goldberg <[email protected]>

Author: rgoldberg

Sources/ArgumentParser/Completions/BashCompletionsGenerator.swift

@@ -9,6 +9,12 @@
 //
 //===----------------------------------------------------------------------===//
 
+#if swift(>=6.0)
+internal import ArgumentParserToolInfo
+#else
+import ArgumentParserToolInfo
+#endif
+
 /// A shell for which the parser can generate a completion script.
 public struct CompletionShell: RawRepresentable, Hashable, CaseIterable {
   public var rawValue: String
@@ -136,7 +142,7 @@ struct CompletionsGenerator {
     case .zsh:
       return [command].zshCompletionScript
     case .bash:
-      return [command].bashCompletionScript
+      return ToolInfoV0(commandStack: [command]).bashCompletionScript
     case .fish:
       return [command].fishCompletionScript
     default:
@@ -215,3 +221,58 @@ extension String {
     replacingOccurrences(of: "-", with: "_")
   }
 }
+
+extension CommandInfoV0 {
+  var commandContext: [String] {
+    (superCommands ?? []) + [commandName]
+  }
+
+  var initialCommand: String {
+    superCommands?.first ?? commandName
+  }
+
+  var positionalArguments: [ArgumentInfoV0] {
+    (arguments ?? []).filter { $0.kind == .positional }
+  }
+
+  var completionFunctionName: String {
+    "_" + commandContext.joined(separator: "_")
+  }
+
+  var completionFunctionPrefix: String {
+    "__\(initialCommand)"
+  }
+}
+
+extension ArgumentInfoV0 {
+  /// Returns a string with the arguments for the callback to generate custom
+  /// completions for this argument.
+  func commonCustomCompletionCall(command: CommandInfoV0) -> String {
+    let subcommandNames =
+      command.commandContext.dropFirst().map { "\($0) " }.joined()
+
+    let argumentName: String
+    switch kind {
+    case .positional:
+      if let index = command.positionalArguments.firstIndex(of: self) {
+        argumentName = "positional@\(index)"
+      } else {
+        argumentName = "---"
+      }
+    default:
+      argumentName = preferredName?.commonCompletionSynopsisString() ?? "---"
+    }
+    return "---completion \(subcommandNames)-- \(argumentName)"
+  }
+}
+
+extension ArgumentInfoV0.NameInfoV0 {
+  func commonCompletionSynopsisString() -> String {
+    switch kind {
+    case .long:
+      return "--\(name)"
+    case .short, .longWithSingleDash:
+      return "-\(name)"
+    }
+  }
+}

Sources/ArgumentParser/Completions/CompletionsGenerator.swift

@@ -235,6 +235,14 @@ extension ArgumentSet {
   ) -> ArgumentDefinition? {
     first(where: { $0.help.keys.contains(key) })
   }
+
+  func positional(
+    at index: Int
+  ) -> ArgumentDefinition? {
+    let positionals = content.filter { $0.isPositional }
+    guard positionals.count > index else { return nil }
+    return positionals[index]
+  }
 }
 
 /// A parser for a given input and set of arguments defined by the given

Sources/ArgumentParser/Parsing/ArgumentSet.swift

@@ -414,14 +414,29 @@ extension CommandParser {
       }
       try customComplete(matchedArgument, forArguments: Array(args))
 
-    case .value(let str):
-      guard
-        let key = InputKey(fullPathString: str),
-        let matchedArgument = argset.firstPositional(withKey: key)
-      else {
-        throw ParserError.invalidState
+    case .value(let value):
+      // Legacy completion script generators use internal key paths to identify
+      // positional args, e.g. optionGroupA.optionGroupB.property. Newer
+      // generators based on ToolInfo use the `positional@<index>` syntax which
+      // avoids leaking implementation details of the tool.
+      let toolInfoPrefix = "positional@"
+      if value.hasPrefix(toolInfoPrefix) {
+        guard
+          let index = Int(value.dropFirst(toolInfoPrefix.count)),
+          let matchedArgument = argset.positional(at: index)
+        else {
+          throw ParserError.invalidState
+        }
+        try customComplete(matchedArgument, forArguments: Array(args))
+      } else {
+        guard
+          let key = InputKey(fullPathString: value),
+          let matchedArgument = argset.firstPositional(withKey: key)
+        else {
+          throw ParserError.invalidState
+        }
+        try customComplete(matchedArgument, forArguments: Array(args))
       }
-      try customComplete(matchedArgument, forArguments: Array(args))
 
     case .terminator:
       throw ParserError.invalidState

Sources/ArgumentParser/Parsing/CommandParser.swift

@@ -53,7 +53,7 @@ extension BidirectionalCollection where Element == ParsableCommand.Type {
 }
 
 extension ToolInfoV0 {
-  fileprivate init(commandStack: [ParsableCommand.Type]) {
+  init(commandStack: [ParsableCommand.Type]) {
     self.init(command: CommandInfoV0(commandStack: commandStack))
     // FIXME: This is a hack to inject the help command into the tool info
     // instead we should try to lift this into the parseable command tree

Sources/ArgumentParser/Usage/DumpHelpGenerator.swift

@@ -215,9 +215,9 @@ public struct ArgumentInfoV0: Codable, Hashable {
   /// Mapping of valid values to descriptions of the value.
   public var allValueDescriptions: [String: String]?
 
-  /// The type of completion to use for an argument or option.
+  /// The type of completion to use for an argument or an option value.
   ///
-  /// `nil` if the tool use use the default completion kind.
+  /// `nil` if the tool uses the default completion kind.
   public var completionKind: CompletionKindV0?
 
   /// Short description of the argument's functionality.

Sources/ArgumentParserToolInfo/ToolInfo.swift

@@ -267,11 +267,11 @@ _math_stats_quantiles() {
         return
         ;;
     2)
-        __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- customArg "${COMP_CWORD}" "$(__math_cursor_index_in_current_word)")"
+        __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- positional@1 "${COMP_CWORD}" "$(__math_cursor_index_in_current_word)")"
         return
         ;;
     3)
-        __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- customDeprecatedArg)"
+        __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- positional@2)"
         return
         ;;
     esac

Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-__base_test_cursor_index_in_current_word() {
+__base-test_cursor_index_in_current_word() {
     local remaining="${COMP_LINE}"
 
     local word
@@ -33,7 +33,7 @@ __base_test_cursor_index_in_current_word() {
 # - options: remove options for this (sub)command that are already on the command line
 # - positional_number: set to the current positional number
 # - unparsed_words: remove all flags, options, and option values for this (sub)command
-__base_test_offer_flags_options() {
+__base-test_offer_flags_options() {
     local -ir positional_count="${1}"
     positional_number=0
 
@@ -125,14 +125,14 @@ __base_test_offer_flags_options() {
     fi
 }
 
-__base_test_add_completions() {
+__base-test_add_completions() {
     local completion
     while IFS='' read -r completion; do
         COMPREPLY+=("${completion}")
     done < <(IFS=$'\n' compgen "${@}" -- "${cur}")
 }
 
-__base_test_custom_complete() {
+__base-test_custom_complete() {
     if [[ -n "${cur}" || -z ${COMP_WORDS[${COMP_CWORD}]} || "${COMP_LINE:${COMP_POINT}:1}" != ' ' ]]; then
         local -ar words=("${COMP_WORDS[@]}")
     else
@@ -142,7 +142,7 @@ __base_test_custom_complete() {
     "${COMP_WORDS[0]}" "${@}" "${words[@]}"
 }
 
-_base_test() {
+_base-test() {
     trap "$(shopt -p);$(shopt -po)" RETURN
     shopt -s extglob
     set +o history +o posix
@@ -160,31 +160,31 @@ _base_test() {
 
     local -a flags=(--one --two --three --kind-counter -h --help)
     local -a options=(--name --kind --other-kind --path1 --path2 --path3 --rep1 -r --rep2)
-    __base_test_offer_flags_options 2
+    __base-test_offer_flags_options 2
 
     # Offer option value completions
     case "${prev}" in
     --name)
         return
         ;;
     --kind)
-        __base_test_add_completions -W 'one'$'\n''two'$'\n''custom-three'
+        __base-test_add_completions -W 'one'$'\n''two'$'\n''custom-three'
         return
         ;;
     --other-kind)
-        __base_test_add_completions -W 'b1_bash'$'\n''b2_bash'$'\n''b3_bash'
+        __base-test_add_completions -W 'b1_bash'$'\n''b2_bash'$'\n''b3_bash'
         return
         ;;
     --path1)
-        __base_test_add_completions -f
+        __base-test_add_completions -f
         return
         ;;
     --path2)
-        __base_test_add_completions -f
+        __base-test_add_completions -f
         return
         ;;
     --path3)
-        __base_test_add_completions -W 'c1_bash'$'\n''c2_bash'$'\n''c3_bash'
+        __base-test_add_completions -W 'c1_bash'$'\n''c2_bash'$'\n''c3_bash'
         return
         ;;
     --rep1)
@@ -198,11 +198,11 @@ _base_test() {
     # Offer positional completions
     case "${positional_number}" in
     1)
-        __base_test_add_completions -W "$(__base_test_custom_complete ---completion -- argument "${COMP_CWORD}" "$(__base_test_cursor_index_in_current_word)")"
+        __base-test_add_completions -W "$(__base-test_custom_complete ---completion -- positional@0 "${COMP_CWORD}" "$(__base-test_cursor_index_in_current_word)")"
         return
         ;;
     2)
-        __base_test_add_completions -W "$(__base_test_custom_complete ---completion -- nested.nestedArgument "${COMP_CWORD}" "$(__base_test_cursor_index_in_current_word)")"
+        __base-test_add_completions -W "$(__base-test_custom_complete ---completion -- positional@1 "${COMP_CWORD}" "$(__base-test_cursor_index_in_current_word)")"
         return
         ;;
     esac
@@ -214,7 +214,7 @@ _base_test() {
     case "${subcommand}" in
     sub-command|escaped-command|help)
         # Offer subcommand argument completions
-        "_base_test_${subcommand}"
+        "_base-test_${subcommand}"
         ;;
     *)
         # Offer subcommand completions
@@ -223,16 +223,16 @@ _base_test() {
     esac
 }
 
-_base_test_sub_command() {
+_base-test_sub-command() {
     flags=(-h --help)
     options=()
-    __base_test_offer_flags_options 0
+    __base-test_offer_flags_options 0
 }
 
-_base_test_escaped_command() {
+_base-test_escaped-command() {
     flags=(-h --help)
     options=(--one)
-    __base_test_offer_flags_options 1
+    __base-test_offer_flags_options 1
 
     # Offer option value completions
     case "${prev}" in
@@ -244,14 +244,14 @@ _base_test_escaped_command() {
     # Offer positional completions
     case "${positional_number}" in
     1)
-        __base_test_add_completions -W "$(__base_test_custom_complete ---completion escaped-command -- two "${COMP_CWORD}" "$(__base_test_cursor_index_in_current_word)")"
+        __base-test_add_completions -W "$(__base-test_custom_complete ---completion escaped-command -- positional@0 "${COMP_CWORD}" "$(__base-test_cursor_index_in_current_word)")"
         return
         ;;
     esac
 }
 
-_base_test_help() {
+_base-test_help() {
     :
 }
 
-complete -o filenames -F _base_test base-test
+complete -o filenames -F _base-test base-test