Revisit positional arguments

- Add better mapping logic
- Add better type conversion
- More docs for arity and positional option configuration
- Backport #616
- Fixes #617

spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc

@@ -4,7 +4,7 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Sometimes, you want to have more fine control of how many parameters with an option
 are processed when parsing operations happen. Arity is defined as min and max
-values, where min must be a positive integer and max has to be more or equal to min.
+values, where min must be zero or a positive integer and max has to be more or equal to min.
 
 ====
 [source, java, indent=0]
@@ -14,7 +14,7 @@ include::{snippets}/OptionSnippets.java[tag=option-registration-arityints]
 ====
 
 Arity can also be defined as an `OptionArity` enum, which are shortcuts
-within the following table:
+shown in below table <<using-shell-options-arity-optionarity-table>>.
 
 ====
 [source, java, indent=0]
@@ -23,6 +23,7 @@ include::{snippets}/OptionSnippets.java[tag=option-registration-arityenum]
 ----
 ====
 
+[[using-shell-options-arity-optionarity-table]]
 .OptionArity
 |===
 |Value |min/max
@@ -51,3 +52,35 @@ The annotation model supports defining only the max value of an arity.
 include::{snippets}/OptionSnippets.java[tag=option-with-annotation-arity]
 ----
 ====
+
+One of a use cases to manually define arity is to impose restrictions how
+many parameters option accepts.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-sample]
+----
+====
+
+In above example we have option _arg1_ and it's defined as type _String[]_. Arity
+defines that it needs at least 1 parameter and not more that 2. As seen in below
+spesific exceptions _TooManyArgumentsOptionException_ and
+_NotEnoughArgumentsOptionException_ are thrown to indicate arity mismatch.
+
+====
+[source, bash]
+----
+shell:>e2e reg arity-errors --arg1
+Not enough arguments --arg1 requires at least 1.
+
+shell:>e2e reg arity-errors --arg1 one
+Hello [one]
+
+shell:>e2e reg arity-errors --arg1 one two
+Hello [one, two]
+
+shell:>e2e reg arity-errors --arg1 one two three
+Too many arguments --arg1 requires at most 2.
+----
+====

spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc

@@ -10,3 +10,61 @@ Positional information is mostly related to a command target method:
 include::{snippets}/OptionSnippets.java[tag=option-registration-positional]
 ----
 ====
+
+NOTE: Be careful with positional parameters as it may soon
+become confusing which options those are mapped to.
+
+Usually arguments are mapped to an option when those are defined in a
+command line whether it's a long or short option. Generally speaking
+there are _options_, _option arguments_ and _arguments_ where latter
+are the ones which are not mapped to any spesific option.
+
+Unrecognised arguments can then have a secondary mapping logic where
+positional information is important. With option position you're
+essentially telling command parsing how to interpret plain raw
+ambiguous arguments.
+
+Let's look what happens when we don't define a position.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-noposition]
+----
+====
+
+Option _arg1_ is required and there is no info what to do with argument
+`one` resulting error for missing option.
+
+====
+[source, bash]
+----
+shell:>arity-strings-1 one
+Missing mandatory option --arg1.
+----
+====
+
+Now let's define a position `0`.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-position]
+----
+====
+
+Arguments are processed until we get up to 2 arguments.
+
+====
+[source, bash]
+----
+shell:>arity-strings-2 one
+Hello [one]
+
+shell:>arity-strings-2 one two
+Hello [one, two]
+
+shell:>arity-strings-2 one two three
+Hello [one, two]
+----
+====