Add Fish completion generator (#226)

dduan · web-flow · commit 2104b1a314c7 · 2020-08-13T12:11:08.000-05:00
diff --git a/Documentation/07 Completion Scripts.md b/Documentation/07 Completion Scripts.md
@@ -4,7 +4,7 @@ Generate customized completion scripts for your shell of choice.
 
 ## Generating and Installing Completion Scripts
 
-Command-line tools that you build with `ArgumentParser` include a built-in option for generating completion scripts, with support for Bash and Z shell. 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.
+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.
 
 ```
 $ example --generate-completion-script bash
@@ -54,6 +54,10 @@ Without `bash-completion`, you'll need to source the completion script directly.
 source ~/.bash_completions/example.bash
 ```
 
+### Installing Fish Completions
+
+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`.
+
 ## Customizing Completions
 
 `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.
diff --git a/Sources/ArgumentParser/CMakeLists.txt b/Sources/ArgumentParser/CMakeLists.txt
@@ -1,6 +1,7 @@
 add_library(ArgumentParser
   Completions/BashCompletionsGenerator.swift
   Completions/CompletionsGenerator.swift
+  Completions/FishCompletionsGenerator.swift
   Completions/ZshCompletionsGenerator.swift
 
   "Parsable Properties/Argument.swift"
diff --git a/Sources/ArgumentParser/Completions/CompletionsGenerator.swift b/Sources/ArgumentParser/Completions/CompletionsGenerator.swift
@@ -24,7 +24,7 @@ public struct CompletionShell: RawRepresentable, Hashable, CaseIterable {
   /// Creates a new instance from the given string.
   public init?(rawValue: String) {
     switch rawValue {
-    case "zsh", "bash":
+    case "zsh", "bash", "fish":
       self.rawValue = rawValue
     default:
       return nil
@@ -37,6 +37,9 @@ public struct CompletionShell: RawRepresentable, Hashable, CaseIterable {
   /// An instance representing `bash`.
   public static var bash: CompletionShell { CompletionShell(rawValue: "bash")! }
 
+  /// An instance representing `fish`.
+  public static var fish: CompletionShell { CompletionShell(rawValue: "fish")! }
+
   /// Returns an instance representing the current shell, if recognized.
   public static func autodetected() -> CompletionShell? {
     // FIXME: This retrieves the user's preferred shell, not necessarily the one currently in use.
@@ -47,7 +50,7 @@ public struct CompletionShell: RawRepresentable, Hashable, CaseIterable {
   
   /// An array of all supported shells for completion scripts.
   public static var allCases: [CompletionShell] {
-    [.zsh, .bash]
+    [.zsh, .bash, .fish]
   }
 }
 
@@ -82,6 +85,8 @@ struct CompletionsGenerator {
       return ZshCompletionsGenerator.generateCompletionScript(command)
     case .bash:
       return BashCompletionsGenerator.generateCompletionScript(command)
+    case .fish:
+      return FishCompletionsGenerator.generateCompletionScript(command)
     default:
       fatalError("Invalid CompletionShell: \(shell)")
     }
diff --git a/Sources/ArgumentParser/Completions/FishCompletionsGenerator.swift b/Sources/ArgumentParser/Completions/FishCompletionsGenerator.swift
@@ -0,0 +1,151 @@
+struct FishCompletionsGenerator {
+  static func generateCompletionScript(_ type: ParsableCommand.Type) -> String {
+    let programName = type._commandName
+    let helper = """
+    function __fish_\(programName)_using_command
+        set cmd (commandline -opc)
+        if [ (count $cmd) -eq (count $argv) ]
+            for i in (seq (count $argv))
+                if [ $cmd[$i] != $argv[$i] ]
+                    return 1
+                end
+            end
+            return 0
+        end
+        return 1
+    end
+
+    """
+
+    let completions = generateCompletions(commandChain: [programName], [type])
+        .joined(separator: "\n")
+
+    return helper + completions
+  }
+
+  static func generateCompletions(commandChain: [String], _ commands: [ParsableCommand.Type])
+      -> [String]
+  {
+    let type = commands.last!
+    let isRootCommand = commands.count == 1
+    let programName = commandChain[0]
+    var subcommands = type.configuration.subcommands
+
+    if !subcommands.isEmpty {
+      if isRootCommand {
+        subcommands.append(HelpCommand.self)
+      }
+    }
+
+    let prefix = "complete -c \(programName) -n '__fish_\(programName)_using_command"
+    /// We ask each suggestion to produce 2 pieces of information
+    /// - Parameters
+    ///   - ancestors: a list of "ancestor" which must be present in the current shell buffer for
+    ///                this suggetion to be considered. This could be a combination of (nested)
+    ///                subcommands and flags.
+    ///   - suggestion: text for the actual suggestion
+    /// - Returns: A completion expression
+    func complete(ancestors: [String], suggestion: String) -> String {
+      "\(prefix) \(ancestors.joined(separator: " "))' \(suggestion)"
+    }
+
+    let subcommandCompletions = subcommands.map { (subcommand: ParsableCommand.Type) -> String in
+      let escapedAbstract = subcommand.configuration.abstract.fishEscape()
+      let suggestion = "-f -a '\(subcommand._commandName)' -d '\(escapedAbstract)'"
+      return complete(ancestors: commandChain, suggestion: suggestion)
+    }
+
+    let argumentCompletions = ArgumentSet(type)
+      .flatMap { $0.argumentSegments(commandChain) }
+      .map { complete(ancestors: $0, suggestion: $1) }
+
+    let completionsFromSubcommands = subcommands.flatMap { subcommand in
+      generateCompletions(commandChain: commandChain + [subcommand._commandName], [subcommand])
+    }
+
+    return argumentCompletions + subcommandCompletions + completionsFromSubcommands
+  }
+}
+
+extension String {
+  fileprivate func fishEscape() -> String {
+    self.replacingOccurrences(of: "'", with: #"\'"#)
+  }
+}
+
+extension Name {
+  fileprivate var asFishSuggestion: String {
+    switch self {
+    case .long(let longName):
+      return "-l \(longName)"
+    case .short(let shortName):
+      return "-s \(shortName)"
+    case .longWithSingleDash(let dashedName):
+      return "-o \(dashedName)"
+    }
+  }
+
+  fileprivate var asFormattedFlag: String {
+    switch self {
+    case .long(let longName):
+      return "--\(longName)"
+    case .short(let shortName):
+      return "-\(shortName)"
+    case .longWithSingleDash(let dashedName):
+      return "-\(dashedName)"
+    }
+  }
+}
+
+extension ArgumentDefinition {
+  fileprivate func argumentSegments(_ commandChain: [String]) -> [([String], String)] {
+    var results = [([String], String)]()
+    var formattedFlags = [String]()
+    var flags = [String]()
+    switch self.kind {
+    case .positional:
+      break
+    case .named(let names):
+      flags = names.map { $0.asFishSuggestion }
+      formattedFlags = names.map { $0.asFormattedFlag }
+      if !flags.isEmpty {
+        // add these flags to suggestions
+        var suggestion = "-f\(isNullary ? "" : " -r") \(flags.joined(separator: " "))"
+        if let abstract = help.help?.abstract, !abstract.isEmpty {
+          suggestion += " -d '\(abstract.fishEscape())'"
+        }
+
+        results.append((commandChain, suggestion))
+      }
+    }
+
+    if isNullary {
+      return results
+    }
+
+    // each flag alternative gets its own completion suggestion
+    for flag in formattedFlags {
+      let ancestors = commandChain + [flag]
+      switch self.completion.kind {
+      case .default:
+        break
+      case .list(let list):
+        results.append((ancestors, "-f -k -a '\(list.joined(separator: " "))'"))
+      case .file(let extensions):
+        let pattern = "*.{\(extensions.joined(separator: ","))}"
+        results.append((ancestors, "-f -a '(for i in \(pattern); echo $i;end)'"))
+      case .directory:
+        results.append((ancestors, "-f -a '(__fish_complete_directories)'"))
+      case .shellCommand(let shellCommand):
+        results.append((ancestors, "-f -a '(\(shellCommand))'"))
+      case .custom:
+        let program = commandChain[0]
+        let subcommands = commandChain.dropFirst().joined(separator: " ")
+        let suggestion = "-f -a '(command \(program) ---completion \(subcommands) -- --custom (commandline -opc)[1..-1])'"
+        results.append((ancestors, suggestion))
+      }
+    }
+
+    return results
+  }
+}
diff --git a/Tests/ArgumentParserExampleTests/MathExampleTests.swift b/Tests/ArgumentParserExampleTests/MathExampleTests.swift
@@ -184,6 +184,12 @@ extension MathExampleTests {
     AssertExecuteCommand(
       command: "math --generate-completion-script zsh",
       expected: zshCompletionScriptText)
+    AssertExecuteCommand(
+      command: "math --generate-completion-script=fish",
+      expected: fishCompletionScriptText)
+    AssertExecuteCommand(
+      command: "math --generate-completion-script fish",
+      expected: fishCompletionScriptText)
   }
   
   func testMath_CustomCompletion() {
@@ -526,3 +532,42 @@ _custom_completion() {
 
 _math
 """
+
+private let fishCompletionScriptText = """
+function __fish_math_using_command
+    set cmd (commandline -opc)
+    if [ (count $cmd) -eq (count $argv) ]
+        for i in (seq (count $argv))
+            if [ $cmd[$i] != $argv[$i] ]
+                return 1
+            end
+        end
+        return 0
+    end
+    return 1
+end
+complete -c math -n '__fish_math_using_command math' -f -a 'add' -d 'Print the sum of the values.'
+complete -c math -n '__fish_math_using_command math' -f -a 'multiply' -d 'Print the product of the values.'
+complete -c math -n '__fish_math_using_command math' -f -a 'stats' -d 'Calculate descriptive statistics.'
+complete -c math -n '__fish_math_using_command math' -f -a 'help' -d 'Show subcommand help information.'
+complete -c math -n '__fish_math_using_command math add' -f -l hex-output -s x -d 'Use hexadecimal notation for the result.'
+complete -c math -n '__fish_math_using_command math multiply' -f -l hex-output -s x -d 'Use hexadecimal notation for the result.'
+complete -c math -n '__fish_math_using_command math stats' -f -a 'average' -d 'Print the average of the values.'
+complete -c math -n '__fish_math_using_command math stats' -f -a 'stdev' -d 'Print the standard deviation of the values.'
+complete -c math -n '__fish_math_using_command math stats' -f -a 'quantiles' -d 'Print the quantiles of the values (TBD).'
+complete -c math -n '__fish_math_using_command math stats' -f -a 'help' -d 'Show subcommand help information.'
+complete -c math -n '__fish_math_using_command math stats average' -f -r -l kind -d 'The kind of average to provide.'
+complete -c math -n '__fish_math_using_command math stats average --kind' -f -k -a 'mean median mode'
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -l test-success-exit-code
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -l test-failure-exit-code
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -l test-validation-exit-code
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -r -l test-custom-exit-code
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -r -l file
+complete -c math -n '__fish_math_using_command math stats quantiles --file' -f -a '(for i in *.{txt,md}; echo $i;end)'
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -r -l directory
+complete -c math -n '__fish_math_using_command math stats quantiles --directory' -f -a '(__fish_complete_directories)'
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -r -l shell
+complete -c math -n '__fish_math_using_command math stats quantiles --shell' -f -a '(head -100 /usr/share/dict/words | tail -50)'
+complete -c math -n '__fish_math_using_command math stats quantiles' -f -r -l custom
+complete -c math -n '__fish_math_using_command math stats quantiles --custom' -f -a '(command math ---completion stats quantiles -- --custom (commandline -opc)[1..-1])'
+"""
diff --git a/Tests/ArgumentParserUnitTests/CompletionScriptTests.swift b/Tests/ArgumentParserUnitTests/CompletionScriptTests.swift
@@ -69,6 +69,19 @@ extension CompletionScriptTests {
     let script3 = Base.completionScript(for: .bash)
     XCTAssertEqual(bashBaseCompletions, script3)
   }
+
+  func testBase_Fish() throws {
+    let script1 = try CompletionsGenerator(command: Base.self, shell: .fish)
+          .generateCompletionScript()
+    XCTAssertEqual(fishBaseCompletions, script1)
+    
+    let script2 = try CompletionsGenerator(command: Base.self, shellName: "fish")
+          .generateCompletionScript()
+    XCTAssertEqual(fishBaseCompletions, script2)
+    
+    let script3 = Base.completionScript(for: .fish)
+    XCTAssertEqual(fishBaseCompletions, script3)
+  }
 }
 
 extension CompletionScriptTests {
@@ -224,4 +237,28 @@ _custom_completion() {
 _escaped
 """
 
-
+private let fishBaseCompletions = """
+function __fish_base_using_command
+    set cmd (commandline -opc)
+    if [ (count $cmd) -eq (count $argv) ]
+        for i in (seq (count $argv))
+            if [ $cmd[$i] != $argv[$i] ]
+                return 1
+            end
+        end
+        return 0
+    end
+    return 1
+end
+complete -c base -n '__fish_base_using_command base' -f -r -l name -d 'The user\\'s name.'
+complete -c base -n '__fish_base_using_command base' -f -r -l kind
+complete -c base -n '__fish_base_using_command base --kind' -f -k -a 'one two custom-three'
+complete -c base -n '__fish_base_using_command base' -f -r -l other-kind
+complete -c base -n '__fish_base_using_command base --other-kind' -f -k -a '1 2 3'
+complete -c base -n '__fish_base_using_command base' -f -r -l path1
+complete -c base -n '__fish_base_using_command base --path1' -f -a '(for i in *.{}; echo $i;end)'
+complete -c base -n '__fish_base_using_command base' -f -r -l path2
+complete -c base -n '__fish_base_using_command base --path2' -f -a '(for i in *.{}; echo $i;end)'
+complete -c base -n '__fish_base_using_command base' -f -r -l path3
+complete -c base -n '__fish_base_using_command base --path3' -f -k -a 'a b c'
+"""
