Skip to content

Commit 331df77

Browse files
jvalkealjvalkeal
committed
More docs for option types
- Relates #558
1 parent 61ae11b commit 331df77

File tree

4 files changed

+445
-0
lines changed

4 files changed

+445
-0
lines changed

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

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
[[using-shell-options-types]]
2+
=== Types
3+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
4+
5+
This section talks about how particular data type is used as an option value.
6+
7+
==== String
8+
9+
`String` is a most simplest type as there's no conversion involved as what's
10+
coming in from a user is always a string.
11+
12+
====
13+
[source, java, indent=0]
14+
----
15+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-anno]
16+
----
17+
====
18+
19+
While it's not strictly required to define type as a `String` it's always
20+
adviced to do so.
21+
22+
====
23+
[source, java, indent=0]
24+
----
25+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-reg]
26+
----
27+
====
28+
29+
==== Boolean
30+
31+
Using boolean types is a bit more involved as there are `boolean` and
32+
`Boolean` where latter can be _null_. Boolean types are usually used as
33+
flags meaning argument value may not be needed.
34+
35+
====
36+
[source, java, indent=0]
37+
----
38+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-anno]
39+
----
40+
====
41+
42+
====
43+
[source, bash]
44+
----
45+
shell:>example
46+
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
47+
48+
shell:>example --arg4
49+
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
50+
51+
shell:>example --arg4 false
52+
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
53+
----
54+
====
55+
56+
====
57+
[source, java, indent=0]
58+
----
59+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-reg]
60+
----
61+
====
62+
63+
====
64+
[source, bash]
65+
----
66+
shell:>example
67+
arg1=false arg2=true arg3=false arg4=null arg5=true arg6=false
68+
69+
shell:>example --arg4
70+
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
71+
72+
shell:>example --arg4 false
73+
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
74+
----
75+
====
76+
77+
==== Number
78+
79+
Numbers are converted as is.
80+
81+
====
82+
[source, java, indent=0]
83+
----
84+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-anno]
85+
----
86+
====
87+
88+
====
89+
[source, java, indent=0]
90+
----
91+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-reg]
92+
----
93+
====
94+
95+
==== Enum
96+
97+
Conversion to enums is possible if given value is exactly matching enum itself.
98+
Currently you can convert assuming case insensitivity.
99+
100+
====
101+
[source, java, indent=0]
102+
----
103+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-class]
104+
----
105+
====
106+
107+
====
108+
[source, java, indent=0]
109+
----
110+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-anno]
111+
----
112+
====
113+
114+
====
115+
[source, java, indent=0]
116+
----
117+
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-reg]
118+
----
119+
====

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,5 @@ include::using-shell-options-default.adoc[]
2020
include::using-shell-options-validation.adoc[]
2121

2222
include::using-shell-options-label.adoc[]
23+
24+
include::using-shell-options-types.adoc[]

‎spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionTypesSnippets.java

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/*
2+
* Copyright 2022 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package org.springframework.shell.docs;
17+
18+
import org.springframework.shell.command.CommandRegistration;
19+
import org.springframework.shell.standard.ShellOption;
20+
21+
class OptionTypesSnippets {
22+
23+
class Dump1 {
24+
// tag::option-type-boolean-anno[]
25+
String example(
26+
@ShellOption() boolean arg1,
27+
@ShellOption(defaultValue = "true") boolean arg2,
28+
@ShellOption(defaultValue = "false") boolean arg3,
29+
@ShellOption() Boolean arg4,
30+
@ShellOption(defaultValue = "true") Boolean arg5,
31+
@ShellOption(defaultValue = "false") Boolean arg6
32+
) {
33+
return String.format("arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
34+
arg1, arg2, arg3, arg4, arg5, arg6);
35+
}
36+
// end::option-type-boolean-anno[]
37+
void dump() {
38+
// tag::option-type-boolean-reg[]
39+
CommandRegistration.builder()
40+
.command("example")
41+
.withOption()
42+
.longNames("arg1").type(boolean.class).and()
43+
.withOption()
44+
.longNames("arg2").type(boolean.class).defaultValue("true").and()
45+
.withOption()
46+
.longNames("arg3").type(boolean.class).defaultValue("false").and()
47+
.withOption()
48+
.longNames("arg4").type(Boolean.class).and()
49+
.withOption()
50+
.longNames("arg5").type(Boolean.class).defaultValue("true").and()
51+
.withOption()
52+
.longNames("arg6").type(Boolean.class).defaultValue("false").and()
53+
.withTarget()
54+
.function(ctx -> {
55+
boolean arg1 = ctx.hasMappedOption("arg1")
56+
? ctx.getOptionValue("arg1")
57+
: false;
58+
boolean arg2 = ctx.getOptionValue("arg2");
59+
boolean arg3 = ctx.getOptionValue("arg3");
60+
Boolean arg4 = ctx.getOptionValue("arg4");
61+
Boolean arg5 = ctx.getOptionValue("arg5");
62+
Boolean arg6 = ctx.getOptionValue("arg6");
63+
return String.format("Hello arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
64+
arg1, arg2, arg3, arg4, arg5, arg6);
65+
})
66+
.and()
67+
.build();
68+
// end::option-type-boolean-reg[]
69+
}
70+
}
71+
72+
class Dump2 {
73+
// tag::option-type-integer-anno[]
74+
String example(@ShellOption(value = "arg1") int arg1) {
75+
return "Hello " + arg1;
76+
}
77+
// end::option-type-integer-anno[]
78+
void dump() {
79+
// tag::option-type-integer-reg[]
80+
CommandRegistration.builder()
81+
.command("example")
82+
.withOption()
83+
.longNames("arg1")
84+
.type(int.class)
85+
.required()
86+
.and()
87+
.withTarget()
88+
.function(ctx -> {
89+
boolean arg1 = ctx.getOptionValue("arg1");
90+
return "Hello " + arg1;
91+
})
92+
.and()
93+
.build();
94+
// end::option-type-integer-reg[]
95+
}
96+
}
97+
98+
class Dump3 {
99+
// tag::option-type-string-anno[]
100+
String example(@ShellOption(value = "arg1") String arg1) {
101+
return "Hello " + arg1;
102+
}
103+
// end::option-type-string-anno[]
104+
void dump() {
105+
// tag::option-type-string-reg[]
106+
CommandRegistration.builder()
107+
.command("example")
108+
.withOption()
109+
.longNames("arg1")
110+
.type(String.class)
111+
.required()
112+
.and()
113+
.withTarget()
114+
.function(ctx -> {
115+
String arg1 = ctx.getOptionValue("arg1");
116+
return "Hello " + arg1;
117+
})
118+
.and()
119+
.build();
120+
// end::option-type-string-reg[]
121+
}
122+
}
123+
124+
class Dump4 {
125+
126+
// tag::option-type-enum-class[]
127+
enum OptionTypeEnum {
128+
ONE,TWO,THREE
129+
}
130+
// end::option-type-enum-class[]
131+
132+
// tag::option-type-enum-anno[]
133+
String example(@ShellOption(value = "arg1") OptionTypeEnum arg1) {
134+
return "Hello " + arg1;
135+
}
136+
// end::option-type-enum-anno[]
137+
void dump() {
138+
// tag::option-type-enum-reg[]
139+
CommandRegistration.builder()
140+
.command("example")
141+
.withOption()
142+
.longNames("arg1")
143+
.type(OptionTypeEnum.class)
144+
.required()
145+
.and()
146+
.withTarget()
147+
.function(ctx -> {
148+
OptionTypeEnum arg1 = ctx.getOptionValue("arg1");
149+
return "Hello " + arg1;
150+
})
151+
.and()
152+
.build();
153+
// end::option-type-enum-reg[]
154+
}
155+
}
156+
157+
}

0 commit comments

Comments
 (0)