cmd: Add shell completion command & generate completion

Cobra (the CLI library) has an advanced support for generating shell
completion. It support Bash, Zsh, Fish and PowerShell. This offering
covers the majority of use cases with some exceptions, of course.

The generated completion scripts have one behavioral difference when
compared to the existing solution: flags (--xxx) are not shown by
default. User needs to type '-' first to get the completion.

containers#840

Co-authored-by: Ondřej Míchal <harrymichal@seznam.cz>

src/cmd/completion.go

@@ -0,0 +1,206 @@
+package cmd
+
+import (
+	"os"
+	"strings"
+
+	"github.com/containers/toolbox/pkg/utils"
+	"github.com/spf13/cobra"
+)
+
+var completionCmd = &cobra.Command{
+	Use:   "completion [bash|zsh|fish|powershell]",
+	Short: "Generate completion script",
+	Long: `To load completions:
+
+Bash:
+
+  $ source <(toolbox completion bash)
+
+  # To load completions for each session, execute once:
+  # Linux:
+  $ toolbox completion bash > /etc/bash_completion.d/toolbox
+  # macOS:
+  $ toolbox completion bash > /usr/local/etc/bash_completion.d/toolbox
+
+Zsh:
+
+  # If shell completion is not already enabled in your environment,
+  # you will need to enable it.  You can execute the following once:
+
+  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load completions for each session, execute once:
+  $ toolbox completion zsh > "${fpath[1]}/_toolbox"
+
+  # You will need to start a new shell for this setup to take effect.
+
+fish:
+
+  $ toolbox completion fish | source
+
+  # To load completions for each session, execute once:
+  $ toolbox completion fish > ~/.config/fish/completions/toolbox.fish
+
+`,
+	Hidden:                true,
+	DisableFlagsInUseLine: true,
+	ValidArgs:             []string{"bash", "zsh", "fish"},
+	Args:                  cobra.ExactValidArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		switch args[0] {
+		case "bash":
+			cmd.Root().GenBashCompletion(os.Stdout)
+		case "zsh":
+			cmd.Root().GenZshCompletion(os.Stdout)
+		case "fish":
+			cmd.Root().GenFishCompletion(os.Stdout, true)
+		}
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(completionCmd)
+}
+
+func completionEmpty(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return nil, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionCommands(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	commandNames := []string{}
+	commands := cmd.Root().Commands()
+	for _, command := range commands {
+		if strings.Contains(command.Name(), "complet") {
+			continue
+		}
+		commandNames = append(commandNames, command.Name())
+	}
+
+	return commandNames, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionContainerNames(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	containerNames := []string{}
+	if containers, err := getContainers(); err == nil {
+		for _, container := range containers {
+			containerNames = append(containerNames, container.Names[0])
+		}
+	}
+
+	if len(containerNames) == 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	return containerNames, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionContainerNamesFiltered(cmd *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {
+	if cmd.Name() == "enter" && len(args) >= 1 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	containerNames := []string{}
+	if containers, err := getContainers(); err == nil {
+		for _, container := range containers {
+			skip := false
+			for _, arg := range args {
+				if container.Names[0] == arg {
+					skip = true
+					break
+				}
+			}
+
+			if skip {
+				continue
+			}
+
+			containerNames = append(containerNames, container.Names[0])
+		}
+	}
+
+	if len(containerNames) == 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	return containerNames, cobra.ShellCompDirectiveNoFileComp
+
+}
+
+func completionDistroNames(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	imageFlag := cmd.Flag("image")
+	if imageFlag != nil && imageFlag.Changed {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	distros := []string{}
+	supportedDistros := utils.GetSupportedDistros()
+	for key := range supportedDistros {
+		distros = append(distros, key)
+	}
+
+	return distros, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionImageNames(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	distroFlag := cmd.Flag("distro")
+	if distroFlag != nil && distroFlag.Changed {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	imageNames := []string{}
+	if images, err := getImages(); err == nil {
+		for _, image := range images {
+			if len(image.Names) > 0 {
+				imageNames = append(imageNames, image.Names[0])
+			} else {
+				imageNames = append(imageNames, image.ID)
+			}
+		}
+	}
+
+	if len(imageNames) == 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	return imageNames, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionImageNamesFiltered(_ *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {
+	imageNames := []string{}
+	if images, err := getImages(); err == nil {
+		for _, image := range images {
+			skip := false
+			var imageName string
+
+			if len(image.Names) > 0 {
+				imageName = image.Names[0]
+			} else {
+				imageName = image.ID
+			}
+
+			for _, arg := range args {
+				if arg == imageName {
+					skip = true
+					break
+				}
+			}
+
+			if skip {
+				continue
+			}
+
+			imageNames = append(imageNames, imageName)
+		}
+	}
+
+	if len(imageNames) == 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	return imageNames, cobra.ShellCompDirectiveNoFileComp
+}
+
+func completionLogLevels(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return []string{"trace", "debug", "info", "warn", "error", "fatal", "panic"}, cobra.ShellCompDirectiveNoFileComp
+}

src/cmd/create.go

@@ -58,9 +58,10 @@ var (
 )
 
 var createCmd = &cobra.Command{
-	Use:   "create",
-	Short: "Create a new toolbox container",
-	RunE:  create,
+	Use:               "create",
+	Short:             "Create a new toolbox container",
+	RunE:              create,
+	ValidArgsFunction: completionEmpty,
 }
 
 func init() {
@@ -91,6 +92,10 @@ func init() {
 		"Create a toolbox container for a different operating system release than the host")
 
 	createCmd.SetHelpFunc(createHelp)
+
+	createCmd.RegisterFlagCompletionFunc("distro", completionDistroNames)
+	createCmd.RegisterFlagCompletionFunc("image", completionImageNames)
+
 	rootCmd.AddCommand(createCmd)
 }
 

src/cmd/enter.go

@@ -35,9 +35,10 @@ var (
 )
 
 var enterCmd = &cobra.Command{
-	Use:   "enter",
-	Short: "Enter a toolbox container for interactive use",
-	RunE:  enter,
+	Use:               "enter",
+	Short:             "Enter a toolbox container for interactive use",
+	RunE:              enter,
+	ValidArgsFunction: completionContainerNamesFiltered,
 }
 
 func init() {
@@ -61,6 +62,9 @@ func init() {
 		"",
 		"Enter a toolbox container for a different operating system release than the host")
 
+	enterCmd.RegisterFlagCompletionFunc("container", completionContainerNames)
+	enterCmd.RegisterFlagCompletionFunc("distro", completionDistroNames)
+
 	enterCmd.SetHelpFunc(enterHelp)
 	rootCmd.AddCommand(enterCmd)
 }

src/cmd/help.go

@@ -26,9 +26,10 @@ import (
 )
 
 var helpCmd = &cobra.Command{
-	Use:   "help",
-	Short: "Display help information about Toolbox",
-	RunE:  help,
+	Use:               "help",
+	Short:             "Display help information about Toolbox",
+	RunE:              help,
+	ValidArgsFunction: completionCommands,
 }
 
 func init() {

src/cmd/list.go

@@ -60,9 +60,10 @@ var (
 )
 
 var listCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List existing toolbox containers and images",
-	RunE:  list,
+	Use:               "list",
+	Short:             "List existing toolbox containers and images",
+	RunE:              list,
+	ValidArgsFunction: completionEmpty,
 }
 
 func init() {

src/cmd/rm.go

@@ -35,9 +35,10 @@ var (
 )
 
 var rmCmd = &cobra.Command{
-	Use:   "rm",
-	Short: "Remove one or more toolbox containers",
-	RunE:  rm,
+	Use:               "rm",
+	Short:             "Remove one or more toolbox containers",
+	RunE:              rm,
+	ValidArgsFunction: completionContainerNamesFiltered,
 }
 
 func init() {

src/cmd/rmi.go

@@ -35,9 +35,10 @@ var (
 )
 
 var rmiCmd = &cobra.Command{
-	Use:   "rmi",
-	Short: "Remove one or more toolbox images",
-	RunE:  rmi,
+	Use:               "rmi",
+	Short:             "Remove one or more toolbox images",
+	RunE:              rmi,
+	ValidArgsFunction: completionImageNamesFiltered,
 }
 
 func init() {

src/cmd/root.go

@@ -95,6 +95,8 @@ func init() {
 
 	persistentFlags.CountVarP(&rootFlags.verbose, "verbose", "v", "Set log-level to 'debug'")
 
+	rootCmd.RegisterFlagCompletionFunc("log-level", completionLogLevels)
+
 	rootCmd.SetHelpFunc(rootHelp)
 
 	usageTemplate := fmt.Sprintf(`Run '%s --help' for usage.`, executableBase)

src/cmd/run.go

@@ -42,9 +42,10 @@ var (
 )
 
 var runCmd = &cobra.Command{
-	Use:   "run",
-	Short: "Run a command in an existing toolbox container",
-	RunE:  run,
+	Use:               "run",
+	Short:             "Run a command in an existing toolbox container",
+	RunE:              run,
+	ValidArgsFunction: completionEmpty,
 }
 
 func init() {
@@ -70,6 +71,10 @@ func init() {
 		"Run command inside a toolbox container for a different operating system release than the host")
 
 	runCmd.SetHelpFunc(runHelp)
+
+	runCmd.RegisterFlagCompletionFunc("container", completionContainerNames)
+	runCmd.RegisterFlagCompletionFunc("distro", completionDistroNames)
+
 	rootCmd.AddCommand(runCmd)
 }
 

src/meson.build

@@ -3,6 +3,7 @@ go_build_wrapper_program = find_program('go-build-wrapper')
 
 sources = files(
   'toolbox.go',
+  'cmd/completion.go',
   'cmd/create.go',
   'cmd/enter.go',
   'cmd/help.go',

src/pkg/utils/utils.go

@@ -446,6 +446,15 @@ func GetRuntimeDirectory(targetUser *user.User) (string, error) {
 	return toolboxRuntimeDirectory, nil
 }
 
+// GetSupportedDistros returns the names of all supported distributions
+//
+// The form of the names is as found in VARIANT_ID in os-release[0]
+//
+// [0] https://www.freedesktop.org/software/systemd/man/os-release.html
+func GetSupportedDistros() map[string]Distro {
+	return supportedDistros
+}
+
 // HumanDuration accepts a Unix time value and converts it into a human readable
 // string.
 //