Add ability to specify argument arity for multi-valued input

Resolves #1263

Author: fmbenhassine

spring-shell-core/src/main/java/org/springframework/shell/core/command/adapter/MethodInvokerCommandAdapter.java

@@ -117,6 +117,7 @@ private List<Object> prepareArguments(CommandContext commandContext) {
 		List<Object> args = new ArrayList<>();
 		Parameter[] parameters = this.method.getParameters();
 		Class<?>[] parameterTypes = this.method.getParameterTypes();
+		int processedArgumentsCount = 0;
 		for (int i = 0; i < parameters.length; i++) {
 			// Handle CommandContext injection
 			if (parameterTypes[i].equals(CommandContext.class)) {
@@ -192,21 +193,26 @@ private List<Object> prepareArguments(CommandContext commandContext) {
 				Class<?> parameterType = parameterTypes[i];
 				Object value = this.conversionService.convert(rawValue, parameterType);
 				args.add(value);
+				processedArgumentsCount++;
 				continue;
 			}
 			// Handle Arguments list injection
 			Arguments argumentsAnnotation = parameters[i].getAnnotation(Arguments.class);
 			if (argumentsAnnotation != null) {
 				log.debug("Processing arguments for parameter: " + parameters[i].getName());
+				int arity = argumentsAnnotation.arity();
 				List<String> rawValues = commandContext.parsedInput()
 					.arguments()
 					.stream()
+					.skip(processedArgumentsCount)
+					.limit(arity)
 					.map(CommandArgument::value)
 					.toList();
 				Class<?> parameterType = parameterTypes[i];
 				// TODO check for collection types
 				Object value = this.conversionService.convert(rawValues, parameterType);
 				args.add(value);
+				processedArgumentsCount += rawValues.size();
 			}
 
 		}

spring-shell-core/src/main/java/org/springframework/shell/core/command/annotation/Arguments.java

@@ -33,4 +33,12 @@
 @Documented
 public @interface Arguments {
 
+	/**
+	 * Define the maximum number of arguments to be collected. By default, all remaining
+	 * arguments are collected.
+	 * @return the maximum number of arguments to be collected
+	 * @since 4.0.2
+	 */
+	int arity() default Integer.MAX_VALUE;
+
 }

spring-shell-core/src/test/java/org/springframework/shell/core/command/adapter/MethodInvokerCommandAdapterDefaultValueTests.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.core.command.adapter;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.lang.reflect.Method;
+
+import jakarta.validation.Validation;
+import jakarta.validation.Validator;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+import org.springframework.core.convert.support.DefaultConversionService;
+import org.springframework.shell.core.command.CommandArgument;
+import org.springframework.shell.core.command.CommandContext;
+import org.springframework.shell.core.command.CommandOption;
+import org.springframework.shell.core.command.ExitStatus;
+import org.springframework.shell.core.command.annotation.Arguments;
+import org.springframework.shell.core.command.annotation.Command;
+import org.springframework.shell.core.command.annotation.Option;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * @author Andrey Litvitski
+ * @author Mahmoud Ben Hassine
+ */
+class MethodInvokerCommandAdapterTests {
+
+	static class Target {
+
+		int seen;
+
+		public void run(@Option(longName = "retries", defaultValue = "3") int retries) {
+			this.seen = retries;
+		}
+
+	}
+
+	static class ArgumentsCommand {
+
+		float base;
+
+		Float[] numbers;
+
+		Float[] moreNumbers;
+
+		@Command(name = "add", description = "Add numbers together", group = "Math commands",
+				help = "A command that adds numbers together. Example usage: add --base 10 1 2 3 4 5 6 7 8 9 10")
+		public void add(
+				@Option(shortName = 'b', longName = "base", description = "the base number to add to") float base,
+				@Arguments(arity = 2) Float[] numbers, @Arguments(arity = 3) Float[] moreNumbers) {
+			this.base = base;
+			this.numbers = numbers;
+			this.moreNumbers = moreNumbers;
+		}
+
+	}
+
+	@Test
+	void optionDefaultValueIsUsedForPrimitiveWhenOptionMissing() throws Exception {
+		Target target = new Target();
+		Method method = Target.class.getDeclaredMethod("run", int.class);
+
+		DefaultConversionService conversionService = new DefaultConversionService();
+		Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
+
+		CommandContext ctx = Mockito.mock(CommandContext.class);
+		Mockito.when(ctx.getOptionByLongName("retries")).thenReturn(null);
+
+		StringWriter out = new StringWriter();
+		Mockito.when(ctx.outputWriter()).thenReturn(new PrintWriter(out));
+
+		MethodInvokerCommandAdapter adapter = new MethodInvokerCommandAdapter("name", "desc", "group", "help", false,
+				method, target, conversionService, validator);
+
+		ExitStatus status = adapter.doExecute(ctx);
+
+		assertThat(status).isEqualTo(ExitStatus.OK);
+		assertThat(target.seen).isEqualTo(3);
+	}
+
+	@Test
+	void argumentsAreParsed() throws Exception {
+		// given
+		ArgumentsCommand target = new ArgumentsCommand();
+		Method method = ArgumentsCommand.class.getDeclaredMethod("add", float.class, Float[].class, Float[].class);
+		DefaultConversionService conversionService = new DefaultConversionService();
+		Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
+		CommandContext ctx = Mockito.mock(CommandContext.class, Mockito.RETURNS_DEEP_STUBS);
+		Mockito.when(ctx.getOptionByLongName("base"))
+			.thenReturn(CommandOption.with().longName("base").value("10").build());
+		StringWriter out = new StringWriter();
+		Mockito.when(ctx.parsedInput().arguments())
+			.thenReturn(java.util.List.of(new CommandArgument(0, "1"), new CommandArgument(1, "2"),
+					new CommandArgument(2, "3"), new CommandArgument(3, "4"), new CommandArgument(4, "5"),
+					new CommandArgument(5, "6"), new CommandArgument(6, "7"), new CommandArgument(7, "8"),
+					new CommandArgument(8, "9"), new CommandArgument(9, "10")));
+		Mockito.when(ctx.outputWriter()).thenReturn(new PrintWriter(out));
+		MethodInvokerCommandAdapter adapter = new MethodInvokerCommandAdapter("name", "desc", "group", "help", false,
+				method, target, conversionService, validator);
+
+		// when
+		ExitStatus status = adapter.doExecute(ctx);
+
+		// then
+		assertThat(status).isEqualTo(ExitStatus.OK);
+		assertThat(target.base).isEqualTo(10f);
+		assertThat(target.numbers).containsExactly(1f, 2f);
+		assertThat(target.moreNumbers).containsExactly(3f, 4f, 5f);
+	}
+
+}

spring-shell-core/src/test/java/org/springframework/shell/core/command/adapter/MethodInvokerCommandAdapterTests.java

@@ -17,6 +17,22 @@ Options are named, while arguments are positional. Options can have short names
 
 Options can be validated using the Bean Validation API by adding validation annotations to the method parameters, see the xref:commands/validation.adoc[Validating Command Options] section for more details.
 
+Multi-valued arguments can be defined by using the `@Arguments` annotation on an array or a collection type (e.g., `List`, `Set`) as the method parameter type. In this case, all the remaining command line tokens will be collected into the collection:
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=multi-valued-argument]
+----
+
+The `@Arguments` annotation provides an attribute called `arity` that allows you to specify the number of arguments to be collected into the collection.
+By default, the arity is not bound, which means that all remaining tokens will be collected. If you set the arity to a specific number, only that many tokens will be collected, and the rest will be treated as separate arguments or options.
+Here is an example of using the `arity` attribute:
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=multi-valued-argument-with-arity]
+----
+
 == Parsing rules
 
 Spring Shell follows the same parsing rules as Spring Boot, with enhanced capabilities following the POSIX style.

spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

@@ -15,10 +15,7 @@
  */
 package org.springframework.shell.docs;
 
-import org.springframework.shell.core.command.annotation.Command;
-import org.springframework.shell.core.command.annotation.Option;
-import org.springframework.shell.core.command.annotation.Argument;
-import org.springframework.shell.core.command.annotation.EnableCommand;
+import org.springframework.shell.core.command.annotation.*;
 import org.springframework.stereotype.Component;
 
 class CommandAnnotationSnippets {
@@ -61,6 +58,39 @@ public void sayHi(
 		}
 		// end::command-option-arg[]
 
+		// tag::multi-valued-argument[]
+		@Component
+		class ArgumentsCommands {
+
+			@Command(name = "hi", description = "Say hi to given names", group = "greetings",
+					help = "A command that greets users with a configurable suffix. Example usage: hi -s=! Foo Bar")
+			public void sayHi(@Option(shortName = 's', longName = "suffix",
+					description = "the suffix of the greeting message", defaultValue = "!") String suffix,
+					@Arguments String[] names) {
+				System.out.println("Hi " + String.join(", ", names) + suffix);
+			}
+
+		}
+		// end::multi-valued-argument[]
+
+		// tag::multi-valued-argument-with-arity[]
+		@Component
+		class ArgumentsWithArityCommands {
+
+			/**
+			 * Real part of (a + bi)(c + di) = ac − bd.
+			 */
+			@Command(name = "real-part", description = "Calculate the real part of the product of two complex numbers",
+					group = "math",
+					help = "Calculate the real part of the product of two complex numbers. Example usage: real-part 1 2 3 4")
+			public double realPartOfComplexProduct(@Arguments(arity = 2) double[] realParts,
+					@Arguments(arity = 2) double[] imaginaryParts) {
+				return realParts[0] * realParts[1] - imaginaryParts[0] * imaginaryParts[1];
+			}
+
+		}
+		// end::multi-valued-argument-with-arity[]
+
 	}
 
 }