Allow filtering custom completions by description

[kiil]

Description

Allow filtering custom completions by description

When a custom completer returns suggestions with descriptions, only the value field was matched against the user's prefix. This made it impossible to narrow down a list by typing a fragment of the human-readable description — e.g. completing an email like lk446763made-up@gmx.net by typing the user's name "Lennart".

Add a new match_description option (default false) to the custom completion options record. When enabled, CustomCompletion::fetch also checks each suggestion's description against the active prefix using the configured match_algorithm, keeping a suggestion if either its value or description matches. The completed value remains the suggestion's value — only filtering is affected. Default behavior is unchanged.

Per review feedback, the option lives on the CompletionOptions struct rather than being threaded around as a separate bool, keeping completion configuration in one place.

User-facing changes (Release notes)

Custom completers can now opt into matching the user's prefix against suggestion descriptions in addition to values, by setting match_description: true in the returned options record. The inserted completion is still the suggestion's value.

def "nu-complete users" [] {
  {
    options: { match_description: true, completion_algorithm: "substring" }
    completions: [
      { value: "lk446763@example.com", description: "Lennart Kiil" }
      { value: "ab123456@example.com", description: "Alice Bob" }
    ]
  }
}

Additional notes

Addresses #18139

[fdncred]

I'm not sure how I feel about this. Completions are for completing commands not for completing descriptions.

[kiil]

@fdncred only the command (value) is completed. This simply allows for filtering both by value and description in the UI (where you use characters to filter and tab to complete).

Let's say the value is lk446763made-up@gmx.net and the description is "Some Full Name". Then you can filter by either, but only lk446763made-up@gmx.net ( the value that is sent to the command ) is completed.

I explain a use case in more detail here: #18139

[fdncred]

I feel like this should be a completion option vs working all the time.

nushell/crates/nu-cli/tests/completions/mod.rs

Line 133 in de614f1

{{ completions: [{}], options: {{ {} }} }}

nushell/crates/nu-cli/tests/completions/mod.rs

Line 342 in de614f1

options: { completion_algorithm: "substring" }

[kiil]

@fdncred I agree it would be best to make it optional, eventhough I feel it should be the default, because as long as the description is shown alongside the value, people will intuitively expect to be able to filter on the description also.

I do not really know how to make it configurable, though.

[fdncred]

I can see how it would be helpful. Lemme see what others think.

[kiil]

I amended the commit to include a bool completion config option for description.

[fdncred]

I think adding match_description is fine but that only works for custom completions written in nushell script, not for the built-in.

One way to get it to work for built-in menus is to change reedline to add another menu item bool.

This is how the default completion menu is defined:

const DEFAULT_COMPLETION_MENU: &str = r#"
{
  name: completion_menu
  only_buffer_difference: false
  marker: "| "
  type: {
      layout: columnar
      columns: 4
      col_width: 20
      col_padding: 2
      tab_traversal: "horizontal"
  }
  style: {
      text: green,
      selected_text: green_reverse
      description_text: yellow
  }
}"#;

Something could be added under tab_traversal, this way people could enable it or disable it pretty easily.

[kiil]

@fdncred

Do you think we can land this for custom completions first?

I am not too familiar with reedline functionality, but this PR for custom completions works regardless.

[fdncred]

I think we should be updating the completion_options struct here instead of passing around a new bool. Although not your changes, I think the same is true for should_sort and should_filter. Having options spread all over the place and not in the struct makes it very difficult to track what's going on.

[fdncred]

Let's maybe try and clean this up with the struct changes I suggested.

[kiil]

@fdncred - I'll have a look later today or tomorrow in the morning. Your comments and help are much appreciated.

[kiil]

@fdncred I think I managed to do what you asked for.

[fdncred]

I can land this when the CI is green and the Description is updated and in compliance with our default PR request template. Maybe look at others if you're not sure what that means. We use the template to create release notes and either you or your LLM created this PR request template out of spec.

[kiil]

I updated the PR according to the template.

[fdncred]

Thanks @kiil

[blindFS]

@kiil Sorry for intervening after the merge. But it feels weird to me that such global option in config only works for custom completion.

Do you plan to enable it for all kinds of completion tasks in the future?

[kiil]

@blindFS Are there any other completions you had in mind specifically, where filtering on description makes sense?

[blindFS]

@blindFS Are there any other completions you had in mind specifically, where filtering on description makes sense?

All of them make sense IMO, if I enable an option named match_description in $env.config.completion, I would expect consistent completion behaviour.

If you think different treatments for them lead to a better UX, I'm afraid we need a more complex option setup, or simply mention the idea of custom completion only in the name of the option.

[kiil]

You are right.

Otherwise the option should be in $env.config.completion.custom.

I need to think this over.

[kiil]

Come to think of it, description filtering could be useful for flag completions (probably not for command completions, though).

[blindFS]

IIRC, there're special keys in the custom completion return record that control different aspects of the completion behavior. I think match_description could be one of them so that we can configure it in a finer grain.

As for the global option, I would suggest to remove it for now, and maybe come back to it when we decide to add such feature for all kinds of completions.

[blindFS]

Personally I would like to have a global toggle keybinding (new reedline event) so that I can temporarily enable such feature if needed.

But this requires a major refactoring of nu-cli/completion and reedline according to my understanding, because the matching is actually handled on the nushell side (something I'd like to change personally)

[kiil]

Personally I would like to have a global toggle keybinding (new reedline event) so that I can temporarily enable such feature if needed.

That would be nice, indeed.

[kiil]

IIRC, there're special keys in the custom completion return record that control different aspects of the completion behavior. I think match_description could be one of them so that we can configure it in a finer grain.

I thought this was already done locally:

{ case_sensitive: false, completion_algorithm: fuzzy, match_description: true }

Maybe the docs need an update.

[blindFS]

IIRC, there're special keys in the custom completion return record that control different aspects of the completion behavior. I think match_description could be one of them so that we can configure it in a finer grain.

I thought this was already done locally:

{ case_sensitive: false, completion_algorithm: fuzzy, match_description: true }

Maybe the docs need an update.

Oh, my bad. I thought the option was added to $env.config. Never mind, it seems perfectly fine to introduce a custom completion specific option.

[kiil]

@blindFS

It seems match_description is not mentioned in the docs:

https://www.nushell.sh/book/custom_completions.html#options-for-custom-completions

Do you know where the docs pages are sourced from?

[blindFS]

@kiil https://github.com/nushell/nushell.github.io/blob/e275fbbe1f60be2c710805ab208715317c463c5c/book/custom_completions.md?plain=1#L39

Do we miss anything else other than match_description?

[kiil]

Thanks, @blindFS !

In addition to mentioning the option, I should probably include a small example of the functionality?

[kiil]

I've submitted a PR to resolve this confusion here: nushell/nushell.github.io#2185