diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc new file mode 100644 index 00000000..227217f5 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc @@ -0,0 +1,13 @@ +[[using-shell-options-basics-annotation]] +==== Annotation +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] + +`Option` annotation can be used to define an option name if you +don't want it to be same as argument name. + +==== +[source, java, indent=0] +---- +include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation] +---- +==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc similarity index 54% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc rename to spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc index 7a5dea65..3558bc84 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-definition.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc @@ -1,10 +1,7 @@ -[[using-shell-options-definition]] -=== Definition +[[using-shell-options-basics-legacyannotation]] +==== Legacy Annotation ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] -Options can be defined within a target method as annotations in a method arguments -or with programmatically with `CommandRegistration`. - Having a target method with argument is automatically registered with a matching argument name. @@ -15,16 +12,6 @@ include::{snippets}/OptionSnippets.java[tag=option-without-annotation] ---- ==== -`Option` annotation can be used to define an option name if you -don't want it to be same as argument name. - -==== -[source, java, indent=0] ----- -include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation] ----- -==== - `@ShellOption` annotation can be used to define an option name if you don't want it to be same as argument name. @@ -44,12 +31,3 @@ from _ShellMethod#prefix_. include::{snippets}/OptionSnippets.java[tag=option-with-annotation-without-prefix] ---- ==== - -Programmatic way with `CommandRegistration` is to use method adding a long name. - -==== -[source, java, indent=0] ----- -include::{snippets}/OptionSnippets.java[tag=option-registration-longarg] ----- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-registration.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-registration.adoc new file mode 100644 index 00000000..1b002181 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-registration.adoc @@ -0,0 +1,18 @@ +[[using-shell-options-basics-registration]] +==== Registration +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] + +Programmatic way with `CommandRegistration` is to use `withOption` to define +an option. + +==== +[source, java, indent=0] +---- +include::{snippets}/OptionSnippets.java[tag=option-registration-longarg] +---- +==== + +`CommandRegistration` can be defined as a bean or manually registered +with a `CommandCatalog`. + +NOTE: Check below sections for other option types, i.e. short format. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc new file mode 100644 index 00000000..1cc895b9 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc @@ -0,0 +1,13 @@ +[[using-shell-options-basics]] +=== Basics +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] + +This section gives a generic idea how an option can be defined. Following +sections, beyond basics, discuss more about how various option behaviour +can be accomplished for a particular use case. + +include::using-shell-options-basics-annotation.adoc[] + +include::using-shell-options-basics-registration.adoc[] + +include::using-shell-options-basics-legacyannotation.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc index 05bf1305..09b9289b 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc @@ -3,9 +3,21 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Command line arguments can be separated into options and positional parameters. -Following sections describes features how options are defined and used. +Following sections describes features how options are defined and used. We first +go through some basics about using options and then go into details about +various ways how options and arguments works. -include::using-shell-options-definition.adoc[] +Generally speaking an _option_ is something after a commands prefixed with +either `-` or `--`. An _option_ can either have a value or not depending +on its context. + +Options can be defined with a target method using annotations with a method +arguments or with programmatically using `CommandRegistration`. + +NOTE: In below sections `@ShellOption` refer to a _legacy annotation model_ +and `@Option` refer to an _annotation model_. + +include::using-shell-options-basics.adoc[] include::using-shell-options-short.adoc[] diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java index 6aeed7b1..22ff3edf 100644 --- a/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java +++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java @@ -21,6 +21,7 @@ import org.springframework.context.annotation.Bean; import org.springframework.shell.command.CommandRegistration; import org.springframework.shell.command.CommandRegistration.OptionArity; import org.springframework.shell.command.CommandRegistration.OptionNameModifier; +import org.springframework.shell.command.annotation.Command; import org.springframework.shell.command.annotation.Option; import org.springframework.shell.standard.ShellMethod; import org.springframework.shell.standard.ShellOption; @@ -29,7 +30,8 @@ public class OptionSnippets { class Dump1Legacy { // tag::option-with-annotation[] - public String example(@ShellOption(value = { "--argx" }) String arg1) { + @ShellMethod + public String example(@ShellOption(value = { "--arg" }) String arg1) { return "Hello " + arg1; } // end::option-with-annotation[] @@ -37,7 +39,8 @@ public class OptionSnippets { class Dump1 { // tag::option-with-option-annotation[] - public String example(@Option(longNames = "argx") String arg1) { + @Command + public String example(@Option(longNames = "arg") String arg1) { return "Hello " + arg1; } // end::option-with-option-annotation[] @@ -45,7 +48,8 @@ public class OptionSnippets { class Dump7 { // tag::option-with-annotation-without-prefix[] - public String example(@ShellOption(value = { "argx" }) String arg1) { + @ShellMethod + public String example(@ShellOption(value = { "arg" }) String arg1) { return "Hello " + arg1; } // end::option-with-annotation-without-prefix[] @@ -53,6 +57,7 @@ public class OptionSnippets { class Dump2 { // tag::option-without-annotation[] + @ShellMethod public String example(String arg1) { return "Hello " + arg1; } @@ -99,10 +104,11 @@ public class OptionSnippets { // end::option-with-annotation-default[] } + @SuppressWarnings("unused") public void dump1() { // tag::option-registration-longarg[] - CommandRegistration.builder() + CommandRegistration registration = CommandRegistration.builder() .withOption() .longNames("arg1") .and()