Migrate Structure

spring-shell-docs/modules/ROOT/pages/using-shell-options-positional.adoc

@@ -0,0 +1,70 @@
+[[using-shell-options-positional]]
+=== Positional
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+Positional information is mostly related to a command target method:
+
+====
+[source, java, indent=0]
+----
+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]
+----
+====