More powerful shell completion

[bartekpacia]

Checklist

• Are you running the latest v3 release? The list of releases is here.
• Did you check the manual for your release? The v3 manual is here.
• Did you perform a search about this feature? Here's the GitHub guide about searching.

What problems are there currenty?

• shell completions is only possible for commands - not for flags

• ShellCompletionFunc does not provide what the user has already entered in the prompt

What problem does this solve?

Currently urfave/cli allows for customizing shell completion only for commands.

The Go module that does the best job at shell completions is cobra. Here are docs for it. urfave/cli is not Cobra and I hope it will never become one – it's much more lightweight, minimal, and fun - but I strongly believe that shell completions are a very useful feature.

Proposed solution

ShellComplete func for flags, for example:

cli.StringFlag{
	Name:    "region-id",
	Aliases: []string{"id"},
	Value:   "",
	Usage:   "region to upload data to",
	ShellComplete: func(ctx context.Context, c *cli.Command) {
		fmt.Println("us-central1")
		fmt.Println("us-east1")
		fmt.Println("eu-west1")
	},
},

Additionally, both ShellComplete on flags and on command should provide the content of the prompt, so the developer can e.g. filter out duplicated completions:

cli.Command{
	Name:      "run",
	ShellComplete: func(ctx context.Context, c *cli.Command, args []string) []string {
		options := []string{"alpha", "bravo", "charlie", "delta"}
		if err != nil {
			return
		}

                completions := []string{}
		for _, option := range options {
			if slices.Contains(args, option) {
				continue
			}

			completions = append(completions, option)
		}

                return completions
	},
}

To avoid reinventing the wheel, completion shell scripts could be taken from Cobra (link). Deep dive & research is required to see if it fits into urfave/cli.

Summary of proposed changes

• change type of ShellCompleteFunc from:

  type ShellCompleteFunc func(ctx context.Context, c *Command)

  to:

  type ShellCompleteFunc func(ctx context.Context, c *Command, args []string, toComplete string) ([]string, ShellCompDirective)

  The presence and name of ShellCompDirective is tentative – but it's useful in Cobra.

  This ideally should be done before v3 stable gets released.

• add ShellComplete field to all the flags – StringFlag, IntFlag. (What about BoolFlag?)

Describe alternatives you've considered

None.

See also

• my other investigation into shell completions
• Cobra shell completion docs
• Cobra zsh completion implementation

[meatballhat]

@bartekpacia I love this! Most of my recent programmable completion experience has been with click so the signature changes you are recommending make perfect sense to me.

[meatballhat]

oh, and to answer your question about BoolFlag: idk offhand, so try out an implementation and see how it feels?