Add Fish Shell Completions (#601)

* Add fish completion script

* Add support for fish completions

* Add documentation for use of fish shell completions

* Fix fish completion empty value check

* Fix isOwnCommand when command descriptions are present

* Fix restic command forwarding with profile prefix

Author: gr1da

commands.go

@@ -79,6 +79,7 @@ func getOwnCommands() []ownCommand {
 				"--json-schema [--version 0.15] [v1|v2]":         "generate a JSON schema that validates resticprofile configuration files in YAML or JSON format",
 				"--bash-completion":                              "generate a shell completion script for bash",
 				"--zsh-completion":                               "generate a shell completion script for zsh",
+				"--fish-completion":                              "generate a shell completion script for fish",
 			},
 		},
 		// commands that need the configuration
@@ -200,7 +201,7 @@ func completeCommand(output io.Writer, ctx commandContext) error {
 
 	// Parse requester as first argument. Format "[kind]:v[version]", e.g. "bash:v1"
 	if len(args) > 0 {
-		matcher := regexp.MustCompile(`^(bash|zsh):v(\d+)$`)
+		matcher := regexp.MustCompile(`^(bash|zsh|fish):v(\d+)$`)
 		if matches := matcher.FindStringSubmatch(args[0]); matches != nil {
 			requester = matches[1]
 			if v, err := strconv.Atoi(matches[2]); err == nil {
@@ -220,7 +221,12 @@ func completeCommand(output io.Writer, ctx commandContext) error {
 		return nil
 	}
 
-	completions := NewCompleter(ctx.ownCommands.All(), DefaultFlagsLoader).Complete(args)
+	includeDescription := false
+	if requester == "fish" {
+		includeDescription = true
+	}
+
+	completions := NewCompleter(ctx.ownCommands.All(), DefaultFlagsLoader, includeDescription).Complete(args)
 	if len(completions) > 0 {
 		for _, completion := range completions {
 			fmt.Fprintln(output, completion)

commands_generate.go

@@ -26,6 +26,9 @@ var bashCompletionScript string
 //go:embed contrib/completion/zsh-completion.sh
 var zshCompletionScript string
 
+//go:embed contrib/completion/fish-completion.fish
+var fishCompletionScript string
+
 func generateCommand(output io.Writer, ctx commandContext) (err error) {
 	args := ctx.request.arguments
 	// enforce no-log
@@ -44,6 +47,8 @@ func generateCommand(output io.Writer, ctx commandContext) (err error) {
 		err = randomKey(output, ctx)
 	} else if slices.Contains(args, "--zsh-completion") {
 		_, err = fmt.Fprintln(output, zshCompletionScript)
+	} else if slices.Contains(args, "--fish-completion") {
+		_, err = fmt.Fprintln(output, fishCompletionScript)
 	} else {
 		err = fmt.Errorf("nothing to generate for: %s", strings.Join(args, ", "))
 	}

commands_test.go

@@ -168,7 +168,7 @@ _ = 0
 }
 
 func TestCompleteCall(t *testing.T) {
-	completer := NewCompleter(ownCommands.All(), DefaultFlagsLoader)
+	completer := NewCompleter(ownCommands.All(), DefaultFlagsLoader, false)
 	completer.init(nil)
 	newline := fmt.Sprintln("")
 	expectedFlags := strings.Join(completer.completeFlagSet(""), newline) + newline
@@ -180,13 +180,18 @@ func TestCompleteCall(t *testing.T) {
 	expectedCommands := strings.Join(commandNames, newline) + newline +
 		RequestResticCompletion + newline
 
+	completerWithDescriptions := NewCompleter(ownCommands.All(), DefaultFlagsLoader, true)
+	completerWithDescriptions.init(nil)
+	expectedFlagsWithDescriptions := strings.Join(completerWithDescriptions.completeFlagSet(""), newline) + newline
+
 	testTable := []struct {
 		args     []string
 		expected string
 	}{
 		{args: []string{"--"}, expected: expectedFlags},
 		{args: []string{"--config=does-not-exist", ""}, expected: expectedCommands},
 		{args: []string{"bash:v1", "--"}, expected: expectedFlags},
+		{args: []string{"fish:v1", "--"}, expected: expectedFlagsWithDescriptions},
 		{args: []string{"bash:v10", "--"}, expected: ""},
 		{args: []string{"zsh:v1", "--"}, expected: ""},
 	}
@@ -225,6 +230,13 @@ func TestGenerateCommand(t *testing.T) {
 		assert.Contains(t, zshCompletionScript, "#!/usr/bin/env zsh")
 	})
 
+	t.Run("--fish-completion", func(t *testing.T) {
+		buffer.Reset()
+		assert.Nil(t, generateCommand(buffer, contextWithArguments([]string{"--fish-completion"})))
+		assert.Equal(t, strings.TrimSpace(fishCompletionScript), strings.TrimSpace(buffer.String()))
+		assert.Contains(t, fishCompletionScript, "#!/usr/bin/env fish")
+	})
+
 	t.Run("--config-reference", func(t *testing.T) {
 		buffer.Reset()
 		assert.NoError(t, generateCommand(buffer, contextWithArguments([]string{"--config-reference", "--to", t.TempDir()})))

complete.go

@@ -29,6 +29,7 @@ type Completer struct {
 	ownCommands           []ownCommand
 	profiles              []string
 	enableProfilePrefixes bool
+	includeDescription    bool
 }
 
 type FlagsLoader func(args []string) *pflag.FlagSet
@@ -38,8 +39,8 @@ func DefaultFlagsLoader(args []string) (flags *pflag.FlagSet) {
 	return
 }
 
-func NewCompleter(commands []ownCommand, loader FlagsLoader) *Completer {
-	return &Completer{ownCommands: commands, loader: loader}
+func NewCompleter(commands []ownCommand, loader FlagsLoader, includeDescription bool) *Completer {
+	return &Completer{ownCommands: commands, loader: loader, includeDescription: includeDescription}
 }
 
 func (c *Completer) init(args []string) {
@@ -63,10 +64,15 @@ func (c *Completer) init(args []string) {
 }
 
 func (c *Completer) formatFlag(flag *pflag.Flag, shorthand bool) string {
+	description := ""
+	if c.includeDescription {
+		description = fmt.Sprintf("\t%s", flag.Usage)
+	}
+
 	if shorthand {
-		return fmt.Sprintf("-%s", flag.Shorthand)
+		return fmt.Sprintf("-%s%s", flag.Shorthand, description)
 	} else {
-		return fmt.Sprintf("--%s", flag.Name)
+		return fmt.Sprintf("--%s%s", flag.Name, description)
 	}
 }
 
@@ -169,7 +175,10 @@ func (c *Completer) completeProfileNamePrefixes(word string) (completions []stri
 }
 
 func (c *Completer) formatOwnCommand(command ownCommand) string {
-	return command.name
+	if !c.includeDescription {
+		return command.name
+	}
+	return fmt.Sprintf("%s\t%s", command.name, command.description)
 }
 
 func (c *Completer) completeOwnCommands(word string) (completions []string) {
@@ -258,8 +267,11 @@ func (c *Completer) toCompletionsWithProfilePrefix(completions []string, profile
 }
 
 func (c *Completer) isOwnCommand(command string, configurationLoaded bool) bool {
+	//strip description, if any
+	commandName := strings.SplitN(command, "\t", 2)[0]
+
 	for _, commandDef := range c.ownCommands {
-		if commandDef.name == command && commandDef.needConfiguration == configurationLoaded {
+		if commandDef.name == commandName && commandDef.needConfiguration == configurationLoaded {
 			return true
 		}
 	}

complete_test.go

@@ -13,7 +13,7 @@ import (
 )
 
 func TestCompleter(t *testing.T) {
-	completer := NewCompleter(ownCommands.All(), DefaultFlagsLoader)
+	completer := NewCompleter(ownCommands.All(), DefaultFlagsLoader, false)
 	completer.init(nil)
 
 	expectedProfiles := func() []string {

contrib/completion/fish-completion.fish

@@ -0,0 +1,84 @@
+#!/usr/bin/env fish
+#
+# resticprofile fish completion script
+# Usage: see https://fishshell.com/docs/current/completions.html#where-to-put-completions
+
+function __resticprofile_completion
+    set --local full_cmdline (commandline -x)
+    set --local cmdline_to_cursor \
+        (string split -- " " (string escape -- (commandline -cx; commandline -ct)))
+    set --local current_token_pos (math (count $cmdline_to_cursor) - 1)
+
+    #send commandline to 'resticprofile complete' in the format it expects
+    set --local completions ("$full_cmdline[1]" complete "fish:v1" "__POS:$current_token_pos" "$full_cmdline[2..]")
+
+    if test (count $completions) = 0
+        return
+    end
+    
+    #handle the directive returned from resticprofile
+    switch $completions[-1]
+    case "__complete_file"
+        set --erase completions[-1]
+
+        set --local file $full_cmdline[-1]
+        #if file starts with '-', remove it
+        test (string sub --length 1 -- "$file") = "-"; and set file ""
+
+        #do path completion
+        set --append completions (__fish_complete_path "$file")
+
+    case "*__complete_restic"
+        #string match --regex returns list where first element is the whole string
+        #and the rest are capture group matches.
+        set --local prefix (string match --regex '^(.*)\.' -- "$completions[-1]")[2]
+        set --local suffix (string match --regex '\.([^.]+)$' -- "$completions[-1]")[2]
+        set --erase completions[-1]
+
+        #This removes profile prefixes before forwarding the completion to restic
+        set --local restic_words
+        for word in $cmdline_to_cursor[2..]
+            if test (string match --regex ".*\/.*" -- "$word")
+                set --append restic_words (string unescape -- "$word")
+            else
+                #take everything after last dot, if there is one
+                set --append restic_words (string match --regex '([^.]+)$' -- $word)[2] 
+            end
+        end
+        
+        #Add a space if the cursor is past the last token so that 'complete' doesn't
+        #return a command that's already fully typed out
+        if test "$restic_words[-1]" = "''"
+            set restic_words[-1] " "
+        end
+
+        #get restic completions
+        set --local restic_values (complete --do-complete "restic $restic_words")
+
+        if test (count $restic_values) = 0
+            for x in $completions
+                echo $x
+            end       
+            return
+        end
+
+        for value in $restic_values
+            #remove empty values
+            string match --quiet --regex '^[\r\n\t ]+$' -- "$value"; and continue
+
+            #add prefix back to completion if applicable
+            if test -n $prefix && test "$prefix" != "$suffix"
+                set --append completions "$prefix.$value"
+            else
+                set --append completions "$value"
+            end
+        end
+    end
+    
+    for x in $completions
+        echo $x
+    end
+   
+end
+
+complete --command resticprofile --no-files --arguments "(__resticprofile_completion)"

docs/content/configuration/getting_started/index.md

@@ -344,6 +344,7 @@ Flags:
   --json-schema [--version 0.15] [v1|v2]          generate a JSON schema that validates resticprofile configuration files in YAML or JSON format
   --random-key [size]                             generate a cryptographically secure random key to use as a restic keyfile (size defaults to 1024 when omitted)
   --zsh-completion                                generate a shell completion script for zsh
+  --fish-completion                               generate a shell completion script for fish
 
 ```
 

docs/content/installation/shell.md

@@ -4,14 +4,17 @@ weight: 100
 ---
 
 
-Shell command line completions are provided for `bash` and `zsh`. 
+Shell command line completions are provided for `bash`, `fish`, and `zsh`. 
 
 To load the command completions in shell, use:
 
 ```shell
 # bash
 eval "$(resticprofile generate --bash-completion)"
 
+# fish
+resticprofile generate --fish-completion | source
+
 # zsh
 eval "$(resticprofile generate --zsh-completion)"
 ```
@@ -21,4 +24,7 @@ To install them permanently:
 ```shell
 resticprofile generate --bash-completion > /etc/bash_completion.d/resticprofile
 chmod +x /etc/bash_completion.d/resticprofile
+
+resticprofile generate --fish-completion > /etc/fish/completions/resticprofile.fish
+chmod +x /etc/fish/completions/resticprofile.fish
 ```