Dynamic Completions: Filter and order completions based on input and importance

[ModProg]

While there are some shell specific behaviors for options, e.g. for zsh and fish:

In zsh, options are completed if at least one - is present.

In fish options are completed if the exact number of dashes is present, i.e. one - for a short option and two -- for a long option.

This had an initial implementation at #5057.

We believe that with the additional knowledge available, clap can do better.

Filtering

On an empty current token, complete:

1. Subcommands
2. Required Options (prefer long)
3. Positional arguments

On a single - complete all options, prefer short options where available (this is a candidate for a shell specific (fish) behavior).

On a double -- complete long options, this would happen either way, so not really a feature. If escaping makes sense (positionals exist), then include just --

In general, aliases are hidden, and only shown if they are the only name of an argument matching the current input.

Sorting

Currently, sorting is probably alphabetic, could be improved to use importance of argument.

Customization

In the future, it could make sense to make both filtering and sorting customizable by the developer.

[epage]

I wonder if we should generalize this to all shells.

In particular, I think it is useful to guess the reason and decide how we want to move forward more generally based on that reason.

My guess is to not flood the screen, overwhelming the user, but try to provide more targeted information. I think that is a worthwhile cause and should be applied to all shells uniformly.

This also gets me thinking of more concrete semantics

• Only show required options, arguments, and subcommands for an empty string
  • Maybe we relax this for positional arguments and subcommands much like usage strings
  • Another reason to relax it for those cases is there isn't a general prefix for them
• Only show one way of referencing any item in any completion
  • e.g. if someone has written enough that only the alias applies, show the alias
  • Prefer long over short
  • Prefer normal name over alias

Thoughts?

[epage]

Another way of putting this is: can we provide a richer experience with the extra semantic information we have?

[ModProg]

Probably, e.g. if someone is currently in the process of rebasing, it would be a good idea to complete --continue and --abort right away as that are the most likely next steps.

We could even go as far as having some form of score users can give options at a later stage, promoting them to be shown earlier.

But it is probably a good idea to e.g. not flood the screen with aliases.

On long vs short that is probably more difficult to decide, and could be shell dependent to, e.g., match the single dash -> short options behavior in fish.

[epage]

On long vs short that is probably more difficult to decide, and could be shell dependent to, e.g., match the single dash -> short options behavior in fish.

At least for a blank screen, I think showing longs for required arguments would be better since that will be more descriptive (in case the descriptions from #5056 aren't sufficient)

But for - I can see preferring shorts. Should we still show a long if it is required and doesn't have a short?

[ModProg]

On long vs short that is probably more difficult to decide, and could be shell dependent to, e.g., match the single dash -> short options behavior in fish.

At least for a blank screen, I think showing longs for required arguments would be better since that will be more descriptive (in case the descriptions from #5056 aren't sufficient)

But for - I can see preferring shorts. Should we still show a long if it is required and doesn't have a short?

yeah, I think preferring short, but falling back to long makes total sense.

Also, fish has a feature where it shows the long flags, for short flags, i.e. it completes the short flag, but shows the long flag as a hint, while we cannot currently use that exact feature for completions, we could emulate something like that i.e. showing the long flag as a fallback for missing descriptions or as a prefix for descriptions of short flags.

[ModProg]

Oh and it also does exactly what you proposed concerning completing long flags if they do not have a short flag. Something I totally missed in my attempt at implementing this hastily.

[epage]

Unless I'm missing something, we've come to a consensus and this is ready to move forward?

[ModProg]

@epage I updated the description

[epage]

Made some minor tweaks. Good to go!