Spring/spring-shell
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More docs for option types

Browse Source 
- Relates #558
This commit is contained in:
Janne Valkealahti
2022-11-23 09:28:55 +00:00
parent 61ae11bf94
commit 331df77ed8
4 changed files with 445 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc Normal file
View File

@@ -0,0 +1,119 @@
[[using-shell-options-types]]
=== Types
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
This section talks about how particular data type is used as an option value.
==== String
`String` is a most simplest type as there's no conversion involved as what's
coming in from a user is always a string.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-anno]
----
====
While it's not strictly required to define type as a `String` it's always
adviced to do so.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-reg]
----
====
==== Boolean
Using boolean types is a bit more involved as there are `boolean` and
`Boolean` where latter can be _null_. Boolean types are usually used as
flags meaning argument value may not be needed.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-anno]
----
====
====
[source, bash]
----
shell:>example
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
shell:>example --arg4
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
----
====
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-reg]
----
====
====
[source, bash]
----
shell:>example
arg1=false arg2=true arg3=false arg4=null arg5=true arg6=false
shell:>example --arg4
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
----
====
==== Number
Numbers are converted as is.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-anno]
----
====
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-reg]
----
====
==== Enum
Conversion to enums is possible if given value is exactly matching enum itself.
Currently you can convert assuming case insensitivity.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-class]
----
====
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-anno]
----
====
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-reg]
----
====

2
spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
View File

@@ -20,3 +20,5 @@ include::using-shell-options-default.adoc[]
include::using-shell-options-validation.adoc[]
include::using-shell-options-label.adoc[]
include::using-shell-options-types.adoc[]

157
spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionTypesSnippets.java Normal file
View File

@@ -0,0 +1,157 @@
/*
* Copyright 2022 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.shell.docs;
import org.springframework.shell.command.CommandRegistration;
import org.springframework.shell.standard.ShellOption;
class OptionTypesSnippets {
class Dump1 {
// tag::option-type-boolean-anno[]
String example(
@ShellOption() boolean arg1,
@ShellOption(defaultValue = "true") boolean arg2,
@ShellOption(defaultValue = "false") boolean arg3,
@ShellOption() Boolean arg4,
@ShellOption(defaultValue = "true") Boolean arg5,
@ShellOption(defaultValue = "false") Boolean arg6
) {
return String.format("arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
arg1, arg2, arg3, arg4, arg5, arg6);
}
// end::option-type-boolean-anno[]
void dump() {
// tag::option-type-boolean-reg[]
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1").type(boolean.class).and()
.withOption()
.longNames("arg2").type(boolean.class).defaultValue("true").and()
.withOption()
.longNames("arg3").type(boolean.class).defaultValue("false").and()
.withOption()
.longNames("arg4").type(Boolean.class).and()
.withOption()
.longNames("arg5").type(Boolean.class).defaultValue("true").and()
.withOption()
.longNames("arg6").type(Boolean.class).defaultValue("false").and()
.withTarget()
.function(ctx -> {
boolean arg1 = ctx.hasMappedOption("arg1")
? ctx.getOptionValue("arg1")
: false;
boolean arg2 = ctx.getOptionValue("arg2");
boolean arg3 = ctx.getOptionValue("arg3");
Boolean arg4 = ctx.getOptionValue("arg4");
Boolean arg5 = ctx.getOptionValue("arg5");
Boolean arg6 = ctx.getOptionValue("arg6");
return String.format("Hello arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
arg1, arg2, arg3, arg4, arg5, arg6);
})
.and()
.build();
// end::option-type-boolean-reg[]
}
}
class Dump2 {
// tag::option-type-integer-anno[]
String example(@ShellOption(value = "arg1") int arg1) {
return "Hello " + arg1;
}
// end::option-type-integer-anno[]
void dump() {
// tag::option-type-integer-reg[]
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(int.class)
.required()
.and()
.withTarget()
.function(ctx -> {
boolean arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
// end::option-type-integer-reg[]
}
}
class Dump3 {
// tag::option-type-string-anno[]
String example(@ShellOption(value = "arg1") String arg1) {
return "Hello " + arg1;
}
// end::option-type-string-anno[]
void dump() {
// tag::option-type-string-reg[]
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(String.class)
.required()
.and()
.withTarget()
.function(ctx -> {
String arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
// end::option-type-string-reg[]
}
}
class Dump4 {
// tag::option-type-enum-class[]
enum OptionTypeEnum {
ONE,TWO,THREE
}
// end::option-type-enum-class[]
// tag::option-type-enum-anno[]
String example(@ShellOption(value = "arg1") OptionTypeEnum arg1) {
return "Hello " + arg1;
}
// end::option-type-enum-anno[]
void dump() {
// tag::option-type-enum-reg[]
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(OptionTypeEnum.class)
.required()
.and()
.withTarget()
.function(ctx -> {
OptionTypeEnum arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
// end::option-type-enum-reg[]
}
}
}

167
spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/OptionTypeCommands.java
View File

@@ -20,6 +20,8 @@ import java.io.PrintWriter;
import org.springframework.context.annotation.Bean;
import org.springframework.shell.command.CommandRegistration;
import org.springframework.shell.standard.ShellComponent;
import org.springframework.shell.standard.ShellMethod;
import org.springframework.shell.standard.ShellOption;
/**
* Commands used for e2e test.
@@ -62,4 +64,169 @@ public class OptionTypeCommands extends BaseE2ECommands {
.build();
}
//
// String
//
@ShellMethod(key = LEGACY_ANNO + "option-type-string", group = GROUP)
public String optionTypeStringAnnotation(
@ShellOption(help = "Desc arg1") String arg1
) {
return "Hello " + arg1;
}
@Bean
public CommandRegistration optionTypeStringRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-string")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(String.class)
.required()
.and()
.withTarget()
.function(ctx -> {
String arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
}
//
// Boolean
//
@ShellMethod(key = LEGACY_ANNO + "option-type-boolean", group = GROUP)
public String optionTypeBooleanAnnotation(
@ShellOption() boolean arg1,
@ShellOption(defaultValue = "true") boolean arg2,
@ShellOption(defaultValue = "false") boolean arg3,
@ShellOption() Boolean arg4,
@ShellOption(defaultValue = "true") Boolean arg5,
@ShellOption(defaultValue = "false") Boolean arg6
) {
return String.format("Hello arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s", arg1, arg2, arg3, arg4, arg5,
arg6);
}
@Bean
public CommandRegistration optionTypeBooleanRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-boolean")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(boolean.class)
.and()
.withOption()
.longNames("arg2")
.type(boolean.class)
.defaultValue("true")
.and()
.withOption()
.longNames("arg3")
.type(boolean.class)
.defaultValue("false")
.and()
.withOption()
.longNames("arg4")
.type(Boolean.class)
.and()
.withOption()
.longNames("arg5")
.type(Boolean.class)
.defaultValue("true")
.and()
.withOption()
.longNames("arg6")
.type(Boolean.class)
.defaultValue("false")
.and()
.withTarget()
.function(ctx -> {
boolean arg1 = ctx.hasMappedOption("arg1") ? ctx.getOptionValue("arg1") : false;
boolean arg2 = ctx.getOptionValue("arg2");
boolean arg3 = ctx.getOptionValue("arg3");
Boolean arg4 = ctx.getOptionValue("arg4");
Boolean arg5 = ctx.getOptionValue("arg5");
Boolean arg6 = ctx.getOptionValue("arg6");
return String.format("Hello arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s", arg1, arg2, arg3,
arg4, arg5, arg6);
})
.and()
.build();
}
//
// Integer
//
@ShellMethod(key = LEGACY_ANNO + "option-type-integer", group = GROUP)
public String optionTypeIntegerAnnotation(
@ShellOption int arg1,
@ShellOption Integer arg2
) {
return String.format("Hello '%s' '%s'", arg1, arg2);
}
@Bean
public CommandRegistration optionTypeIntegerRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-integer")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(int.class)
.required()
.and()
.withOption()
.longNames("arg2")
.type(Integer.class)
.required()
.and()
.withTarget()
.function(ctx -> {
int arg1 = ctx.getOptionValue("arg1");
Integer arg2 = ctx.getOptionValue("arg2");
return String.format("Hello '%s' '%s'", arg1, arg2);
})
.and()
.build();
}
//
// Enum
//
public static enum OptionTypeEnum {
ONE,TWO,THREE
}
@ShellMethod(key = LEGACY_ANNO + "option-type-enum", group = GROUP)
public String optionTypeEnumAnnotation(
@ShellOption(help = "Desc arg1") OptionTypeEnum arg1
) {
return "Hello " + arg1;
}
@Bean
public CommandRegistration optionTypeEnumRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-enum")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(OptionTypeEnum.class)
.required()
.and()
.withTarget()
.function(ctx -> {
OptionTypeEnum arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
}
}