Filter and order completions based on input and importance for native completions

[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:

• If subcommands or positionals are present
  • Subcommands
  • Positional arguments
  • Required pptions (prefer long)
• else
  • All options (prefer long)

On a single - complete all options, prefer short options where available.

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.

In all cases, aliases should only show up if the main argument is not being shown

Sorting

Either

• Alphabetical
• Display order

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!

[epage]

With #3951 nearly done, I've reviewed the plan for this again and made a couple of tweaks.

[epage]

I think we've got this covered between

• feat(clap_complete): Support hiding long flags and their long aliases #5583
• feat(clap_complete): Support hiding subcommands and their aliases #5584
• fix(complete): Prioritize subcommands, positionals over flags #5739
• fix(complete): De-duplicate built-in candidates #5740
• fix(complete): When completing -[TAB], prioritize shorts #5741
• fix(complete): Sort by display order #5743

While we don't hide optional flags. I'm a bit mixed on that. If there is interest in moving forward on that, we likely should have a dedicated issue exploring the trade offs.