This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Shell 3.3.3!spring-doc.cn

Positional

Positional information is mostly related to a command target method:spring-doc.cn

CommandRegistration.builder()
	.withOption()
		.longNames("arg1")
		.position(0)
		.and()
	.build();

Be careful with positional parameters as it may soon become confusing which options those are mapped to.

Usually arguments are mapped to an option when those are defined in a command line whether it’s a long or short option. Generally speaking there are options, option arguments and arguments where latter are the ones which are not mapped to any spesific option.spring-doc.cn

Unrecognised arguments can then have a secondary mapping logic where positional information is important. With option position you’re essentially telling command parsing how to interpret plain raw ambiguous arguments.spring-doc.cn

Let’s look what happens when we don’t define a position.spring-doc.cn

CommandRegistration.builder()
	.command("arity-strings-1")
	.withOption()
		.longNames("arg1")
		.required()
		.type(String[].class)
		.arity(0, 2)
		.and()
	.withTarget()
		.function(ctx -> {
			String[] arg1 = ctx.getOptionValue("arg1");
			return "Hello " + Arrays.asList(arg1);
		})
		.and()
	.build();

Option arg1 is required and there is no info what to do with argument one resulting error for missing option.spring-doc.cn

shell:>arity-strings-1 one
Missing mandatory option --arg1.

Now let’s define a position 0.spring-doc.cn

CommandRegistration.builder()
	.command("arity-strings-2")
	.withOption()
		.longNames("arg1")
		.required()
		.type(String[].class)
		.arity(0, 2)
		.position(0)
		.and()
	.withTarget()
		.function(ctx -> {
			String[] arg1 = ctx.getOptionValue("arg1");
			return "Hello " + Arrays.asList(arg1);
		})
		.and()
	.build();

Arguments are processed until we get up to 2 arguments.spring-doc.cn

shell:>arity-strings-2 one
Hello [one]

shell:>arity-strings-2 one two
Hello [one, two]

shell:>arity-strings-2 one two three
Hello [one, two]