Arity (元數)

Arity (元數) 定義選項解析需要多少參數。

相較於 annotation 和 programmatic 使用元數設定，legacy annotation 在使用元數設定方面存在限制。這些限制在以下範例的註記中提及。

程式化
註解
舊版註解

CommandRegistration zeroOrOne() {
	return CommandRegistration.builder()
		.command("example")
		.withOption()
			.longNames("arg")
			.arity(OptionArity.ZERO_OR_ONE)
			.and()
		.build();
}

@Command(command = "example")
String zeroOrOne(
	@Option(arity = OptionArity.ZERO_OR_ONE) String arg)
{
	return String.format("Hi '%s'", arg);
}

@ShellMethod(key = "example")
String zeroOrOne(
	@ShellOption(arity = 1) String arg)
{
	return String.format("Hi '%s'", arg);
}

表 1. OptionArity (選項元數)
值	最小值/最大值
ZERO (零)	0 / 0
ZERO_OR_ONE (零或一)	0 / 1
EXACTLY_ONE (恰好一)	1 / 1
ZERO_OR_MORE (零或多個)	0 / Integer MAX
ONE_OR_MORE (一或多個)	1 / Integer MAX

legacy annotation 不支援定義最小元數。

程式化
註解
舊版註解

CommandRegistration zeroOrOneWithMinMax() {
	return CommandRegistration.builder()
		.command("example")
		.withOption()
			.longNames("arg")
			.arity(0, 1)
			.and()
		.build();
}

@Command(command = "example")
String zeroOrOneWithMinMax(
	@Option(arityMin = 0, arityMax = 1) String arg)
{
	return String.format("Hi '%s'", arg);
}

@ShellMethod(key = "example")
String zeroOrOneWithMinMax(
	@ShellOption(arity = 1) String arg)
{
	return String.format("Hi '%s'", arg);
}

在以下範例中，我們有一個選項 arg1，其類型定義為 String[]。Arity (元數) 定義它需要至少 1 個參數，但不超過 2 個。如下所示，會拋出特定的例外 TooManyArgumentsOptionException 和 NotEnoughArgumentsOptionException，以指示元數不符。

shell:>e2e reg arity-errors --arg1
Not enough arguments --arg1 requires at least 1.

shell:>e2e reg arity-errors --arg1 one
Hello [one]

shell:>e2e reg arity-errors --arg1 one two
Hello [one, two]

shell:>e2e reg arity-errors --arg1 one two three
Too many arguments --arg1 requires at most 2.