Clarify command parsing rules and how to customize them

Author: fmbenhassine

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

@@ -16,13 +16,16 @@
 package org.springframework.shell.core.command;
 
 /**
- * Interface parsing arguments for a {@link Command}. A command is always identified by a
- * set of words like {@code command subcommand1 subcommand2} and remaining part of it are
- * options which this interface intercepts and translates into format we can understand.
+ * Interface for parsing input for a {@link Command}. A command is always identified by a
+ * set of words like {@code command subcommand1 subcommand2} and where the remaining part
+ * is expected to be a set of arguments and/or key/value pairs of options. The
+ * {@link ParsedInput} API holds the parsed result.
  *
  * @author Janne Valkealahti
  * @author Piotr Olaszewski
  * @author Mahmoud Ben Hassine
+ * @since 4.0.0
+ * @see ParsedInput
  */
 public interface CommandParser {
 

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

@@ -41,11 +41,26 @@ For example:
 $>mycommand mysubcommand --option1=value1 arg1 -o2=value2 arg2
 ----
 
-If your command defines subcommands and a subcommand is used without options, then arguments must be separated using "--" (POSIX style):
+IMPORTANT: Options cannot be specified using the `--option value` or `-o value` syntax. Only the `=` syntax is supported. Moreover, short options cannot be grouped (e.g., `-abc` is not supported).
+
+If your command does not have options, then arguments must be separated using "--" (POSIX style) to avoid ambiguity between arguments and subcommands:
+
+[source,shell]
+----
+$>mycommand -- arg1 arg2
+----
+
+Similarly, if your command defines subcommands that are used without options, then arguments must also be separated using "--" (POSIX style) to avoid ambiguity between arguments and subcommands:
 
 [source,shell]
 ----
 $>mycommand mysubcommand -- arg1 arg2
 ----
 
-This is required to avoid ambiguity between options and arguments.
+TIP: To avoid ambiguity, named options should be preferred over positional arguments whenever possible, especially when subcommands are involved (see https://clig.dev/#arguments-and-flags[Command Line Interface Guidelines]).
+
+== Customizing parsing rules
+
+Spring Shell 4 provides a new API called `CommandParser` that allows you to customize the command parsing rules.
+If the default parsing rules do not fit your needs, you can implement your own parser by implementing the `CommandParser` interface.
+Once the custom parser is implemented, you can register it as a bean in the application context, and Spring Shell will use it for parsing commands.