Fix alias handling with @Command annotation

- Revisit how alias commands are added using
  @Command annotation when using if/or on class
  and/or method level.
- With this change alias handling is more logical
  and there's better tests and docs.
- Backport #945
- Fixes #973

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-2024 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.
@@ -69,8 +69,8 @@ public @interface Command {
 	 * {@code alias1 sub1} it can be defined as:
 	 *
 	 * <pre class="code">
-	 * command = { "alias1", "sub1" }
-	 * command = "alias1 sub1"
+	 * alias = { "alias1", "sub1" }
+	 * alias = "alias1 sub1"
 	 * </pre>
 	 *
 	 * Values are split and trimmed meaning spaces doesn't matter.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-2024 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.
@@ -159,10 +159,11 @@ class CommandAnnotationUtils {
 			.collect(Collectors.toList());
 
 		return Stream.of(right.getStringArray(field))
-			.flatMap(command -> Stream.of(command.split(" ")))
-			.filter(command -> StringUtils.hasText(command))
 			.map(command -> command.strip())
-			.map(command -> Stream.concat(prefix.stream(), Stream.of(command)).collect(Collectors.toList()))
+			.map(command -> Stream.concat(
+					prefix.stream(),
+					Stream.of(command).filter(c -> StringUtils.hasText(c)))
+				.collect(Collectors.toList()))
 			.map(arr -> arr.toArray(String[]::new))
 			.toArray(String[][]::new);
 	}

spring-shell-core/src/test/java/org/springframework/shell/command/annotation/support/CommandAnnotationUtilsTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-2024 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.
@@ -108,6 +108,10 @@ class CommandAnnotationUtilsTests {
 			.get(Command.class);
 	private static MergedAnnotation<Command> aliasValues4 = MergedAnnotations.from(AliasValues4.class)
 			.get(Command.class);
+	private static MergedAnnotation<Command> aliasValues5 = MergedAnnotations.from(AliasValues5.class)
+			.get(Command.class);
+	private static MergedAnnotation<Command> aliasValues6 = MergedAnnotations.from(AliasValues6.class)
+			.get(Command.class);
 
 	@Command
 	private static class AliasDefault {
@@ -129,6 +133,14 @@ class CommandAnnotationUtilsTests {
 	private static class AliasValues4 {
 	}
 
+	@Command(alias = { "one" })
+	private static class AliasValues5 {
+	}
+
+	@Command(alias = { "" })
+	private static class AliasValues6 {
+	}
+
 	@Test
 	void testAlias() {
 		assertThat(CommandAnnotationUtils.deduceAlias(aliasDefault, aliasDefault)).isEmpty();
@@ -139,7 +151,9 @@ class CommandAnnotationUtilsTests {
 		assertThat(CommandAnnotationUtils.deduceAlias(aliasDefault, aliasValues3))
 				.isEqualTo(new String[][] { { "five" }, { "six" }, { "seven" } });
 		assertThat(CommandAnnotationUtils.deduceAlias(aliasDefault, aliasValues4))
-				.isEqualTo(new String[][] { { "eight" }, { "nine" } });
+				.isEqualTo(new String[][] { { "eight nine" } });
+		assertThat(CommandAnnotationUtils.deduceAlias(aliasValues5, aliasValues6))
+				.isEqualTo(new String[][] { { "one" } });
 	}
 
 	private static MergedAnnotation<Command> groupValue1 = MergedAnnotations.from(GroupValues1.class)

spring-shell-core/src/test/java/org/springframework/shell/command/annotation/support/CommandRegistrationFactoryBeanTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-2024 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.
@@ -17,6 +17,7 @@ package org.springframework.shell.command.annotation.support;
 
 import java.util.Collections;
 
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 
 import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -375,4 +376,186 @@ class CommandRegistrationFactoryBeanTests {
 					bd.getPropertyValues().add(CommandRegistrationFactoryBean.COMMAND_METHOD_PARAMETERS, parameters);
 				});
 	}
+
+	@Nested
+	class Aliases {
+
+		@Test
+		void aliasOnlyOnMethod() {
+			configCommon(AliasOnlyOnMethod.class, new AliasOnlyOnMethod(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("four");
+					});
+		}
+
+		@Command(command = "one")
+		private static class AliasOnlyOnMethod {
+
+			@Command(command = "two", alias = "four")
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasOnlyOnClass() {
+			configCommon(AliasOnlyOnClass.class, new AliasOnlyOnClass(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(0);
+					});
+		}
+
+		@Command(command = "one", alias = "three")
+		private static class AliasOnlyOnClass {
+
+			@Command(command = "two")
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasOnlyOnMethodMultiCommandString() {
+			configCommon(AliasOnlyOnMethodMultiCommandString.class, new AliasOnlyOnMethodMultiCommandString(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("four five");
+					});
+		}
+
+		@Command(command = "one")
+		private static class AliasOnlyOnMethodMultiCommandString {
+
+			@Command(command = "two", alias = "four five")
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasOnlyOnMethodMultiCommandArray() {
+			configCommon(AliasOnlyOnMethodMultiCommandArray.class, new AliasOnlyOnMethodMultiCommandArray(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(2);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("four");
+						assertThat(registration.getAliases().get(1).getCommand()).isEqualTo("five");
+					});
+		}
+
+		@Command(command = "one")
+		private static class AliasOnlyOnMethodMultiCommandArray {
+
+			@Command(command = "two", alias = {"four", "five"})
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasOnBothMethodStringEmpty() {
+			configCommon(AliasOnBothMethodStringEmpty.class, new AliasOnBothMethodStringEmpty(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("three");
+					});
+		}
+
+		@Command(command = "one", alias = "three")
+		private static class AliasOnBothMethodStringEmpty {
+
+			@Command(command = "two", alias = "")
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasOnBoth() {
+			configCommon(AliasOnBoth.class, new AliasOnBoth(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("three four");
+					});
+		}
+
+		@Command(command = "one", alias = "three")
+		private static class AliasOnBoth {
+
+			@Command(command = "two", alias = "four")
+			void command1(){
+			}
+		}
+
+		@Test
+		void aliasWithCommandOnBothMethodStringEmpty() {
+			configCommon(AliasWithCommandOnBothMethodStringEmpty.class, new AliasWithCommandOnBothMethodStringEmpty(), "command1", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("ten");
+					});
+			configCommon(AliasWithCommandOnBothMethodStringEmpty.class, new AliasWithCommandOnBothMethodStringEmpty(), "command2", new Class[] { })
+					.run((context) -> {
+						CommandRegistrationFactoryBean fb = context.getBean(FACTORYBEANREF,
+								CommandRegistrationFactoryBean.class);
+						assertThat(fb).isNotNull();
+						CommandRegistration registration = fb.getObject();
+						assertThat(registration).isNotNull();
+						assertThat(registration.getCommand()).isEqualTo("one two");
+						assertThat(registration.getAliases()).hasSize(1);
+						assertThat(registration.getAliases().get(0).getCommand()).isEqualTo("ten twelve");
+					});
+		}
+
+		@Command(command = "one", alias = "ten")
+		private static class AliasWithCommandOnBothMethodStringEmpty {
+
+			@Command(command = "", alias = "")
+			void command1(){
+			}
+
+			@Command(command = "two", alias = "twelve")
+			void command2(){
+			}
+		}
+
+	}
+
 }

spring-shell-docs/modules/ROOT/nav.adoc

@@ -13,6 +13,7 @@
 *** xref:commands/exceptionhandling/resolving.adoc[]
 *** xref:commands/exceptionhandling/mappings.adoc[]
 *** xref:commands/exceptionhandling/annotation.adoc[]
+** xref:commands/alias.adoc[]
 ** xref:commands/hidden.adoc[]
 ** xref:commands/helpoptions.adoc[]
 ** xref:commands/interactionmode.adoc[]

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

@@ -0,0 +1,71 @@
+[[commands-alias]]
+= Alias
+
+ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs]
+
+It is possible to define an _alias_ for a command. This is convenient for
+cases where you want to create a shorter version of a command or going
+through a complete command rename while keeping old one temporarily in
+place.
+
+Format for _alias_ is slighly different than a _command_. When _command_
+is defined as an array it's concatenated together into a single command.
+When _alias_ is defined as an array it's used to create a separate
+aliases.
+
+Aliases with a plain `CommandRegistration` is simple and clear as you
+get exactly what you define as there's no "magic" in it.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=builder]
+----
+
+Defining alias with `@Command` annotation is a bit more involved as it
+can exist on a both class and method levels. Here are examples how it
+works.
+
+Alias just on a method gives you _myalias_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command1]
+----
+
+Or _myalias1_ and _myalias2_ if defined as an array.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command2]
+----
+
+Alias only on a class level does nothing as it's simply an instruction
+for annotation on a *method level if defined*.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command3]
+----
+
+Alias on both class and method level combines those two together where
+class level works as an prefix and method level as combination of aliases.
+Alias on a class level is usually used together with a _command_ prefix
+to keep aliases on a same command level.
+
+Here you'd get alias _myalias1 myalias2_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command4]
+----
+
+On a method level there's a special format, that being an *empty string*
+which allows you to create an alias but it only uses prefix from a
+class level.
+
+Here you'd get alias _myalias1_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command5]
+----

spring-shell-docs/src/test/java/org/springframework/shell/docs/CommandRegistrationAliasSnippets.java

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2024 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.docs;
+
+import org.springframework.shell.command.CommandRegistration;
+import org.springframework.shell.command.annotation.Command;
+
+class CommandRegistrationAliasSnippets {
+
+	// tag::builder[]
+	CommandRegistration commandRegistration() {
+		return CommandRegistration.builder()
+			.command("mycommand")
+			// define alias as myalias
+			.withAlias()
+				.command("myalias")
+				.and()
+			// define alias as myalias1 and myalias2
+			.withAlias()
+				.command("myalias1", "myalias2")
+				.and()
+			.build();
+	}
+	// end::builder[]
+
+	class Dump1 {
+
+		// tag::command1[]
+		@Command
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = "myalias")
+			void myCommand() {
+			}
+		}
+		// end::command1[]
+	}
+
+	class Dump2 {
+
+		// tag::command2[]
+		@Command
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = { "myalias1", "myalias2" })
+			void myCommand() {
+			}
+		}
+		// end::command2[]
+	}
+
+	class Dump3 {
+
+		// tag::command3[]
+		@Command(alias = "myalias")
+		class MyCommands {
+
+			@Command(command = "mycommand")
+			void myCommand() {
+			}
+		}
+		// end::command3[]
+	}
+
+	class Dump4 {
+
+		// tag::command4[]
+		@Command(alias = "myalias1")
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = "myalias2")
+			void myCommand() {
+			}
+		}
+		// end::command4[]
+	}
+
+	class Dump5 {
+
+		// tag::command5[]
+		@Command(command = "mycommand", alias = "myalias")
+		class MyCommands {
+
+			@Command(command = "", alias = "")
+			void myMainCommand() {
+			}
+
+			@Command(command = "mysubcommand", alias = "mysubalias")
+			void mySubCommand() {
+			}
+		}
+		// end::command5[]
+	}
+}

spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/AliasCommands.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-2024 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.
@@ -50,6 +50,11 @@ public class AliasCommands {
 		public String testAlias2Annotation() {
 			return "Hello from alias command";
 		}
+
+		@Command(command = "alias-3 alias-31", alias = "alias-32 alias-33")
+		public String testAlias3Annotation() {
+			return "Hello from alias3 command";
+		}
 	}
 
 	@Component
@@ -89,6 +94,22 @@ public class AliasCommands {
 					.and()
 				.build();
 		}
+
+		@Bean
+		public CommandRegistration testAlias3Registration(CommandRegistration.BuilderSupplier builder) {
+			return builder.get()
+				.command(REG, "alias-3 alias-31")
+				.group(GROUP)
+				.withAlias()
+					.command(REG, "alias-32 alias-33")
+					.and()
+				.withTarget()
+					.function(ctx -> {
+						return "Hello from alias3 command";
+					})
+					.and()
+				.build();
+		}
 	}
 
 }