More powerful shell completion

bartekpacia commented 1 month ago

Checklist

[x] Are you running the latest v3 release? The list of releases is here.
[x] Did you check the manual for your release? The v3 manual is here.
[x] 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.

meatballhat commented 1 month ago

@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 commented 1 month ago

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

urfave / cli