Positional

Positional information is mostly related to a command target method:

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.

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.

Let’s look what happens when we don’t define a position.

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.

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

Now let’s define a position 0.

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.

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]