[#1125][#1538] DOC: Update "Option Names or Subcommands as Option Val…

…ues" section in user manual

RELEASE-NOTES.md

@@ -29,6 +29,7 @@ Picocli follows [semantic versioning](http://semver.org/).
 * [#1483] Enhancement: Improved `AbstractCommandSpecProcessor#isSubcommand`; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request.
 * [#1499] Enhancement: Improved `DefaultFactory#create(Class<T>)`. Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request.
 * [#1481] DOC: Removed repeated "whether" typo in JavaDoc; Thanks to [Ross Goldberg](https://github.com/rgoldberg) for the pull request.
+* [#1125][#1538] DOC: Update "Option Names or Subcommands as Option Values" section in user manual; Thanks to [Scott Turner](https://github.com/turnef) for raising this.
 * [#1474] Bugfix: Avoid `UnsupportedCharsetException: cp65001` on Microsoft Windows console when code page is set to UTF-8. Thanks to [epuni](https://github.com/epuni) for raising this.
 * [#1466][#1467] Bugfix/Enhancement: Autocomplete now shows subcommand aliases in the completion candidates. Thanks to [Ruud Senden](https://github.com/rsenden) for the pull request.
 * [#1458][#1473] Enhancement: autocompletion now supports file names containing spaces. Thanks to [zpater345](https://github.com/zpater345) for raising this and thanks to [NewbieOrange](https://github.com/NewbieOrange) for the pull request.

docs/index.adoc

@@ -4723,8 +4723,8 @@ This will throw an `UnmatchedArgumentException` with message:
 ----
 
 
-=== Option Names as Option Values
-Since picocli 4.4, the parser will no longer assign values that match an option name to options that take a parameter, unless the value is in quotes.
+=== Option Names or Subcommands as Option Values
+Since picocli 4.4, the parser will no longer assign values that match a subcommand name or an option name to options that take a parameter, unless the value is in quotes.
 For example:
 
 .Java
@@ -4775,6 +4775,92 @@ This will print the following output:
 x='-y', y='null'
 ----
 
+Another idea is to replace or augment picocli's parser by doing <<Custom Parameter Processing,custom parameter processing>> for such options. For example:
+
+.Java
+[source,java,role="primary"]
+----
+class App implements Runnable {
+    @Option(names = "-x", parameterConsumer = App.CustomConsumer.class)
+    String x;
+
+    @Option(names = "-y")
+    String y;
+
+    @Command
+    public void mySubcommand() {}
+
+    static class CustomConsumer implements IParameterConsumer {
+        @Override
+        public void consumeParameters(Stack<String> args, ArgSpec argSpec, CommandSpec cmdSpec) {
+            if (args.isEmpty()) {
+                throw new ParameterException(cmdSpec.commandLine(),
+                        "Error: option '-x' requires a parameter");
+            }
+            String arg = args.pop();
+            argSpec.setValue(arg);
+        }
+    }
+
+    public void run() {
+        System.out.printf("x='%s', y='%s'%n", x, y);
+    }
+
+    public static void main(String... args) {
+        new CommandLine(new App()).execute(args);
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+class App : Runnable {
+    @Option(names = ["-x"], parameterConsumer = CustomConsumer::class)
+    var x: String? = null
+
+    @Option(names = ["-y"])
+    var y: String? = null
+
+    @Command
+    fun mySubcommand() {}
+
+    internal class CustomConsumer : IParameterConsumer {
+        override fun consumeParameters(args: Stack<String>, argSpec: ArgSpec, cmdSpec: CommandSpec) {
+            if (args.isEmpty()) {
+                throw ParameterException(cmdSpec.commandLine(),
+                        "Error: option '-x' requires a parameter"
+                )
+            }
+            val arg = args.pop()
+            argSpec.setValue(arg)
+        }
+    }
+
+    override fun run() {
+        System.out.printf("x='%s', y='%s'%n", x, y)
+    }
+
+    companion object {
+        @JvmStatic
+        fun main(args: Array<String>) {
+            CommandLine(App()).execute(*args)
+        }
+    }
+}
+----
+
+The above code assigns whatever command line argument that follows the `-x` option to that option,
+and allows input like the following:
+
+[source,bash]
+----
+java App -x=mySubcommand
+java App -x mySubcommand
+java App -x=-y
+java App -x -y -y=123
+----
+
 
 === Toggle Boolean Flags
 When a flag option is specified on the command line picocli will set its value to the opposite of its _default_ value.