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 @@
 	 * {@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 @@ private static String[][] deduceStringArrayLeftPrefixes(String field, MergedAnno
 			.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 @@ void testCommand() {
 			.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 @@ private static class AliasValues3 {
 	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 @@ void testAlias() {
 		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 @@
 
 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 @@ private <T> ApplicationContextRunner configCommon(Class<T> type, T bean, String
 					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]
+----