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

Document String array option type

Browse Source 
- Backport #558 as it brings missing option type docs
- Backport #628
- Fixes #629
This commit is contained in:
Janne Valkealahti
2023-01-19 11:32:37 +00:00
parent b853112e0b
commit 78da071e86
5 changed files with 600 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,137 @@
[[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]
----
====
==== Array
Arrays can be used as is with strings and primitive types.
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-array-anno]
----
====
====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-array-reg]
----
====

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

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

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

@@ -0,0 +1,182 @@
/*
* 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[]
}
}
static 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[]
}
}
class Dump5 {
// tag::option-type-string-array-anno[]
String example(@ShellOption(value = "arg1") String[] arg1) {
return "Hello " + arg1;
}
// end::option-type-string-array-anno[]
void dump() {
// tag::option-type-string-array-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-array-reg[]
}
}
}

29
spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/BaseE2ECommands.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2022 the original author or authors.
* Copyright 2022-2023 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.
@@ -15,6 +15,11 @@
*/
package org.springframework.shell.samples.e2e;
import java.util.stream.Collectors;
import java.util.stream.IntStream;
import org.springframework.util.StringUtils;
/**
* Base class for all e2e commands.
*
@@ -25,4 +30,26 @@ abstract class BaseE2ECommands {
static final String GROUP = "E2E Commands";
static final String REG = "e2e reg";
static final String LEGACY_ANNO = "e2e anno ";
static String stringOfStrings(String[] values) {
return String.format("[%s]", StringUtils.arrayToCommaDelimitedString(values));
}
static String stringOfInts(int[] values) {
String joined = IntStream.range(0, values.length)
.mapToLong(i -> values[i])
.boxed()
.map(d -> d.toString())
.collect(Collectors.joining(","));
return String.format("[%s]", joined);
}
static String stringOfFloats(float[] values) {
String joined = IntStream.range(0, values.length)
.mapToDouble(i -> values[i])
.boxed()
.map(d -> d.toString())
.collect(Collectors.joining(","));
return String.format("[%s]", joined);
}
}

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

@@ -1,5 +1,5 @@
/*
* Copyright 2022 the original author or authors.
* Copyright 2022-2023 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.
@@ -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,250 @@ 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();
}
//
// String[]
//
@ShellMethod(key = LEGACY_ANNO + "option-type-string-array", group = GROUP)
public String optionTypeStringArrayAnnotation(
@ShellOption(help = "Desc arg1") String[] arg1
) {
return "Hello " + stringOfStrings(arg1);
}
@Bean
public CommandRegistration optionTypeStringArrayRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-string-array")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(String[].class)
.required()
.and()
.withTarget()
.function(ctx -> {
String[] arg1 = ctx.getOptionValue("arg1");
return "Hello " + stringOfStrings(arg1);
})
.and()
.build();
}
//
// int[]
//
@ShellMethod(key = LEGACY_ANNO + "option-type-int-array", group = GROUP)
public String optionTypeIntArrayAnnotation(
@ShellOption(help = "Desc arg1") int[] arg1
) {
return "Hello " + stringOfInts(arg1);
}
@Bean
public CommandRegistration optionTypeIntArrayRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-int-array")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(int[].class)
.required()
.and()
.withTarget()
.function(ctx -> {
int[] arg1 = ctx.getOptionValue("arg1");
return "Hello " + stringOfInts(arg1);
})
.and()
.build();
}
//
// Void
//
@Bean
public CommandRegistration optionTypeVoidRegistration() {
return CommandRegistration.builder()
.command(REG, "option-type-void")
.group(GROUP)
.withOption()
.longNames("arg1")
.type(void.class)
.and()
.withTarget()
.function(ctx -> {
return "Hello ";
})
.and()
.build();
}
}