Skip to content

Commit 5a4a241

Browse files
jvalkealjvalkeal
committed
Refactor short option docs
- Add e2e samples - Add short option snippets as tabs content(to get later converted to an actual tabs). - Relates #637
1 parent 62e469b commit 5a4a241

File tree

3 files changed

+309
-12
lines changed

3 files changed

+309
-12
lines changed

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

Lines changed: 34 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,57 @@
22
=== Short Format
33
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
44

5-
Short style _POSIX_ option in most is just a synonym to long format but
6-
adds additional feature to combine those options together. Having short
7-
options _a_, _b_, _c_ can be used as `-abc`.
8-
9-
Programmatically short option is defined by using short name function.
5+
Short style _POSIX_ option is usually just a synonym to long format. As
6+
shown below option `--arg` is equal to `-a`.
107

8+
[tabs]
119
====
10+
Programmatic::
11+
+
12+
[source, java, indent=0]
13+
----
14+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-programmatic]
15+
----
16+
17+
Annotation::
18+
+
19+
[source, java, indent=0]
20+
----
21+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-annotation]
22+
----
23+
24+
Legacy Annotation::
25+
+
1226
[source, java, indent=0]
1327
----
14-
include::{snippets}/OptionSnippets.java[tag=option-registration-shortarg]
28+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-legacyannotation]
1529
----
1630
====
1731

1832
Short option with combined format is powerful if type is defined as a flag
19-
which means type is a _boolean_. That way you can define a presense of a flags
33+
which means type is a _boolean_. That way you can define a presence of a flags
2034
as `-abc`, `-abc true` or `-abc false`.
2135

36+
[tabs]
2237
====
38+
Programmatic::
39+
+
2340
[source, java, indent=0]
2441
----
25-
include::{snippets}/OptionSnippets.java[tag=option-registration-shortargbooleans]
42+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-programmatic]
2643
----
27-
====
2844
29-
With annotation model you can define short argument directly.
45+
Annotation::
46+
+
47+
[source, java, indent=0]
48+
----
49+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-annotation]
50+
----
3051
31-
====
52+
Legacy Annotation::
53+
+
3254
[source, java, indent=0]
3355
----
34-
include::{snippets}/OptionSnippets.java[tag=option-with-annotation-shortarg]
56+
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-legacyannotation]
3557
----
3658
====

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

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
/*
2+
* Copyright 2023 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.context.annotation.Bean;
19+
import org.springframework.shell.command.CommandRegistration;
20+
import org.springframework.shell.command.annotation.Command;
21+
import org.springframework.shell.command.annotation.Option;
22+
import org.springframework.shell.standard.ShellMethod;
23+
import org.springframework.shell.standard.ShellOption;
24+
25+
public class ShortOptionSnippets {
26+
27+
static class LegacyAnnotation {
28+
29+
// tag::option-type-string-legacyannotation[]
30+
@ShellMethod(key = "example")
31+
String stringWithShortOption(
32+
@ShellOption(value = { "--arg", "-a" }) String arg) {
33+
return String.format("Hi '%s'", arg);
34+
}
35+
// end::option-type-string-legacyannotation[]
36+
37+
// tag::option-type-multiple-booleans-legacyannotation[]
38+
@ShellMethod(key = "example")
39+
public String multipleBooleans(
40+
@ShellOption(value = "-a") boolean a,
41+
@ShellOption(value = "-b") boolean b,
42+
@ShellOption(value = "-c") boolean c)
43+
{
44+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
45+
}
46+
// end::option-type-multiple-booleans-legacyannotation[]
47+
}
48+
49+
// @Command(command = BaseE2ECommands.ANNO, group = BaseE2ECommands.GROUP)
50+
static class Annotation {
51+
52+
// tag::option-type-string-annotation[]
53+
@Command(command = "example")
54+
String stringWithShortOption(
55+
@Option(longNames = "arg", shortNames = 'a', required = true) String arg) {
56+
return String.format("Hi '%s'", arg);
57+
}
58+
// end::option-type-string-annotation[]
59+
60+
// tag::option-type-multiple-booleans-annotation[]
61+
@Command(command = "example")
62+
public String multipleBooleans(
63+
@Option(shortNames = 'a') boolean a,
64+
@Option(shortNames = 'b') boolean b,
65+
@Option(shortNames = 'c') boolean c) {
66+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
67+
}
68+
// end::option-type-multiple-booleans-annotation[]
69+
}
70+
71+
static class Registration {
72+
73+
// tag::option-type-string-programmatic[]
74+
CommandRegistration stringWithShortOption() {
75+
return CommandRegistration.builder()
76+
.command("example")
77+
.withTarget()
78+
.function(ctx -> {
79+
String arg = ctx.hasMappedOption("arg") ? ctx.getOptionValue("arg") : null;
80+
return String.format("Hi arg='%s'", arg);
81+
})
82+
.and()
83+
.withOption()
84+
.longNames("arg")
85+
.shortNames('a')
86+
.required()
87+
.and()
88+
.build();
89+
}
90+
// end::option-type-string-programmatic[]
91+
92+
// tag::option-type-multiple-booleans-programmatic[]
93+
CommandRegistration multipleBooleans() {
94+
return CommandRegistration.builder()
95+
.command("example")
96+
.withTarget()
97+
.function(ctx -> {
98+
Boolean a = ctx.hasMappedOption("a") ? ctx.getOptionValue("a") : null;
99+
Boolean b = ctx.hasMappedOption("b") ? ctx.getOptionValue("b") : null;
100+
Boolean c = ctx.hasMappedOption("c") ? ctx.getOptionValue("c") : null;
101+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
102+
})
103+
.and()
104+
.withOption()
105+
.shortNames('a')
106+
.type(boolean.class)
107+
.defaultValue("false")
108+
.and()
109+
.withOption()
110+
.shortNames('b')
111+
.type(boolean.class)
112+
.defaultValue("false")
113+
.and()
114+
.withOption()
115+
.shortNames('c')
116+
.type(boolean.class)
117+
.defaultValue("false")
118+
.and()
119+
.build();
120+
}
121+
// end::option-type-multiple-booleans-programmatic[]
122+
}
123+
124+
}

‎spring-shell-samples/src/main/java/org/springframework/shell/samples/e2e/ShortOptionTypeCommands.java

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
/*
2+
* Copyright 2023 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.samples.e2e;
17+
18+
import org.springframework.context.annotation.Bean;
19+
import org.springframework.shell.command.CommandRegistration;
20+
import org.springframework.shell.command.annotation.Command;
21+
import org.springframework.shell.command.annotation.Option;
22+
import org.springframework.shell.standard.ShellComponent;
23+
import org.springframework.shell.standard.ShellMethod;
24+
import org.springframework.shell.standard.ShellOption;
25+
import org.springframework.stereotype.Component;
26+
27+
public class ShortOptionTypeCommands {
28+
29+
@ShellComponent
30+
public static class LegacyAnnotation extends BaseE2ECommands {
31+
32+
@ShellMethod(key = LEGACY_ANNO + "short-option-type-string", group = GROUP)
33+
public String shortOptionTypeStringLegacyAnnotation(
34+
@ShellOption(value = { "--arg", "-a" }) String arg) {
35+
return String.format("Hi '%s'", arg);
36+
}
37+
38+
@ShellMethod(key = LEGACY_ANNO + "short-option-type-single-boolean", group = GROUP)
39+
public String shortOptionTypeSingleBooleanLegacyAnnotation(
40+
@ShellOption(value = "-a") boolean a)
41+
{
42+
return String.format("Hi '%s'", a);
43+
}
44+
45+
@ShellMethod(key = LEGACY_ANNO + "short-option-type-multi-boolean", group = GROUP)
46+
public String shortOptionTypeMultiBooleanLegacyAnnotation(
47+
@ShellOption(value = "-a") boolean a,
48+
@ShellOption(value = "-b") boolean b,
49+
@ShellOption(value = "-c") boolean c)
50+
{
51+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
52+
}
53+
}
54+
55+
@Command(command = BaseE2ECommands.ANNO, group = BaseE2ECommands.GROUP)
56+
public static class Annotation extends BaseE2ECommands {
57+
58+
@Command(command = "short-option-type-string")
59+
public String shortOptionTypeStringAnnotation(
60+
@Option(longNames = "arg", shortNames = 'a', required = true) String arg) {
61+
return String.format("Hi '%s'", arg);
62+
}
63+
64+
@Command(command = "short-option-type-single-boolean")
65+
public String shortOptionTypeSingleBooleanAnnotation(
66+
@Option(shortNames = 'a') boolean a) {
67+
return String.format("Hi '%s'", a);
68+
}
69+
70+
@Command(command = "short-option-type-multi-boolean")
71+
public String shortOptionTypeMultiBooleanAnnotation(
72+
@Option(shortNames = 'a') boolean a,
73+
@Option(shortNames = 'b') boolean b,
74+
@Option(shortNames = 'c') boolean c) {
75+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
76+
}
77+
}
78+
79+
@Component
80+
public static class Registration extends BaseE2ECommands {
81+
82+
@Bean
83+
public CommandRegistration shortOptionTypeStringRegistration() {
84+
return getBuilder()
85+
.command(REG, "short-option-type-string")
86+
.group(GROUP)
87+
.withTarget()
88+
.function(ctx -> {
89+
String arg = ctx.hasMappedOption("arg") ? ctx.getOptionValue("arg") : null;
90+
return String.format("Hi arg='%s'", arg);
91+
})
92+
.and()
93+
.withOption()
94+
.longNames("arg")
95+
.shortNames('a')
96+
.required()
97+
.and()
98+
.build();
99+
}
100+
101+
@Bean
102+
public CommandRegistration shortOptionTypeSingleBooleanRegistration() {
103+
return getBuilder()
104+
.command(REG, "short-option-type-single-boolean")
105+
.group(GROUP)
106+
.withTarget()
107+
.function(ctx -> {
108+
Boolean a = ctx.hasMappedOption("a") ? ctx.getOptionValue("a") : null;
109+
return String.format("Hi a='%s'", a);
110+
})
111+
.and()
112+
.withOption()
113+
.shortNames('a')
114+
.type(boolean.class)
115+
.defaultValue("false")
116+
.and()
117+
.build();
118+
}
119+
120+
@Bean
121+
public CommandRegistration shortOptionTypeMultiBooleanRegistration() {
122+
return getBuilder()
123+
.command(REG, "short-option-type-multi-boolean")
124+
.group(GROUP)
125+
.withTarget()
126+
.function(ctx -> {
127+
Boolean a = ctx.hasMappedOption("a") ? ctx.getOptionValue("a") : null;
128+
Boolean b = ctx.hasMappedOption("b") ? ctx.getOptionValue("b") : null;
129+
Boolean c = ctx.hasMappedOption("c") ? ctx.getOptionValue("c") : null;
130+
return String.format("Hi a='%s' b='%s' c='%s'", a, b, c);
131+
})
132+
.and()
133+
.withOption()
134+
.shortNames('a')
135+
.type(boolean.class)
136+
.defaultValue("false")
137+
.and()
138+
.withOption()
139+
.shortNames('b')
140+
.type(boolean.class)
141+
.defaultValue("false")
142+
.and()
143+
.withOption()
144+
.shortNames('c')
145+
.type(boolean.class)
146+
.defaultValue("false")
147+
.and()
148+
.build();
149+
}
150+
}
151+
}

0 commit comments

Comments
 (0)