Option value (completion) providers not supported in spring shell 4

[georgmittendorfer]

As the @OptionValues annotation that did accept a provider is not available anymore in spring shell 4, it is not possible to provide the same completion behavior as in version 3.x. The possibility to define a completionProvider on command level makes it harder to differentiate between different completion options based on the option.

I would suggest to allow a completion provider on the option level, too (it could have priority over the one configured on command level).

[czpilar]

Completion provider for option values can be defined at Commad level following way:

package org.springframework.shell.samples.helloworld.boot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.shell.core.command.CommandOption;
import org.springframework.shell.core.command.annotation.Command;
import org.springframework.shell.core.command.annotation.Option;
import org.springframework.shell.core.command.completion.CompletionProposal;
import org.springframework.shell.core.command.completion.CompletionProvider;

import java.util.Collections;
import java.util.stream.Stream;

@SpringBootApplication
public class SpringShellApplication {

	public static void main(String[] args) {
		SpringApplication.run(SpringShellApplication.class, args);
	}

	@Command(name = "hello", completionProvider = "helloCompletionProvider")
	public void hello(@Option(longName = "first", shortName = 'f') String first,
					  @Option(longName = "last", shortName = 'l') String last) {
		System.out.println("Hello " + first + " " + last + "!");
	}

	@Bean
	public CompletionProvider helloCompletionProvider() {
		return completionContext -> {
			CommandOption option = completionContext.getCommandOption();
			if (option == null) {
				return Collections.emptyList();
			}

			Stream<String> options = Stream.empty();

			if ("first".equals(option.longName())) {
				options = Stream.of("Peter", "Paul", "Mary");
			} else if ("last".equals(option.longName())) {
				options = Stream.of("Chan", "Noris");
			}

			return options.map(CompletionProposal::new).toList();
		};
	}

}

[georgmittendorfer]

Completion provider for option values can be defined at Command level following way:
[...]

Yes, I am aware of this workaround but (a) you couple the provider with the option.longName and (b) provider = "xyzProvider" as it was possible in 3.x allows better composition when delegating to different providers in different classes.

In my case every provider is a spring bean and the option names are not always the same. I would have to do this dispatcher logic in every class where they are used or bind the composite provider to the naming of the option. It is doable but definitely a downgrade.

[georgmittendorfer]

@czpilar as the long name now is mandatory in 4.x I think I can live with the long name hard-coded in the beans atm. There are so many more important features, therefore I'll close this one.

[czpilar]

@georgmittendorfer
Just to be clear, I am not a maintainer of the repository - only someone who has helped with some contributions. I am willing to help resolve certain issues, but some of them require design decisions that I am not in a position to make.

[georgmittendorfer]

Ty, your help is highly appreciated. You are the only one that replied. Sorry, if I was sounding too demanding.

[piotrooo]

Completion at the option level is an interesting feature and should be added.

The precedence should be as follows:

1. Use the completion provider defined on @Option; if not available, then
2. Use the completion provider defined on @Command; if not available, then
3. (New feature) Use a global completion provider
4. Fallback to a global no-op completion provider

One open question is whether the completion provider should be bundled directly into the @Option or @Command annotation, or whether it should be defined as a separate annotation, e.g. @CompletionProvider.

What do you think about adding support for registering a global completion provider (point 3)? This could be useful for options where we want to implement, as @georgmittendorfer mentioned, a dispatcher for all unhandled options. This approach obviously comes with some downsides. It is just an idea and does not necessarily need to be implemented in the first iteration.

Additionally, how should the provided CompletionContext look, and what responsibilities should it have?

[georgmittendorfer]

I like 1. and 2.

[I don't need 3. and 4. personally (I think it wouldn't be a large overhead to add the provider per command). But someone might find it useful. But if you have so many commands that you would need this I am not sure, if binding it to the longName would be a good idea, imo there would need to be a mechanism to find the correct completion provider(s) for a certain option.]

[fmbenhassine]

Thank you for reporting this, @georgmittendorfer . And thank you @czpilar and @piotrooo for the follow up!

In my opinion, the problems in v3 WRT having a separate completer for each option are:

1. The need for a separate annotation to define the completer. One of the themes of v4 is API simplification
2. The need to define several beans and (mentally) map several beans names to OptionValues(provider="beanName")
3. Impossibility to provide cross-options completion. Here is an example:

enum Gender {
	MALE, FEMALE
}

@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
	help = "A command that greets the user with 'Hello ${name}!'. Usage: hello [-g | --gender]=<gender> [-n | --name]=<name>",
	completionProvider = "helloCompletionProvider")
public void sayHello(
	@Option(shortName = 'n', longName = "name", description = "the name of the person to greet", defaultValue = "World") String name,
	@Option(shortName = 'g', longName = "gender", description = "the gender of the person to greet") Gender gender) {
	String prefix = switch (gender) {
		case MALE -> "Mr. ";
		case FEMALE -> "Ms. ";
	};
	System.out.println("Hello " + prefix + name + "!");
}

@Bean
public CompletionProvider helloCompletionProvider() {
	// if gender is female, suggest "Alice" and "Eve", otherwise suggest "Bob" and "Charlie"
	return completionContext ->
	{
		CommandOption commandOption = completionContext.getCommandOption();
		// check option name and value and return appropriate proposals
		return List.of();
	};
}

The simpler, centralised approach of command completion (among other customisation options through attributes of @Command) in v4 is definitely easier to use and maintain, and I think it solves the 3 pain points with v3 that I mentioned above.

That said, I am open to improve things if possible, if that does not introduce additional complexity to the framework. Spring Shell has accumulated a LOT of accidental complexity over the years, and my goal is not only to simplify the framework itself, but also the code base behind it to ensure the long term sustainability of the project.

The precedence should be as follows

I am open to 1 & 2 in v4.1, if that does not introduce any confusion or an unreasonable amount of code complexity. We can discuss this in a PR.