Skip to content

Commit 57b9259

Browse files
jvalkealjvalkeal
committed
Split builtin command docs
- Fixes #504
1 parent 6749ec2 commit 57b9259

12 files changed

+276
-263
lines changed

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ include::{snippets}/AnnotationRegistrationSnippets.java[tag=snippet1]
2424

2525
The only required attribute of the `@ShellMethod` annotation is its `value` attribute, which should have
2626
a short, one-sentence, description of what the command does. This lets your users
27-
get consistent help about your commands without having to leave the shell (see <<help-command>>).
27+
get consistent help about your commands without having to leave the shell (see <<built-in-commands-help>>).
2828

2929
NOTE: The description of your command should be short -- no more than one or two sentences. For better
3030
consistency, it should start with a capital letter and end with a period.

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Details of the error have been omitted. You can use the stacktrace command to pr
5757
----
5858
====
5959

60-
Information about currently unavailable commands is also used in the integrated help. See <<help-command>>.
60+
Information about currently unavailable commands is also used in the integrated help. See <<built-in-commands-help>>.
6161

6262
[TIP]
6363
====

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-clear.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[[built-in-commands-clear]]
2+
==== Clear
3+
The `clear` command does what you would expect and clears the screen, resetting the prompt
4+
in the top left corner.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-completion.adoc

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[[built-in-commands-completion]]
2+
==== Completion
3+
4+
The `completion` command set lets you create script files that can be used
5+
with am OS shell implementations to provide completion. This is very useful when
6+
working with non-interactive mode.
7+
8+
Currently, the only implementation is for bash, which works with `bash` sub-command.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-exit.adoc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[[built-in-commands-exit]]
2+
==== Exit
3+
4+
The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully
5+
closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all
6+
commands to disk, so that they are available again on the next launch.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-help.adoc

+178
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
[[built-in-commands-help]]
2+
==== Help
3+
4+
Running a shell application often implies that the user is in a graphically limited
5+
environment. Also, while we are nearly always connected in the era of mobile phones,
6+
accessing a web browser or any other rich UI application (such as a PDF viewer) may not always
7+
be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help`
8+
command comes in.
9+
10+
Typing `help` + `ENTER` lists all the commands known to the shell (including <<dynamic-command-availability,unavailable>> commands)
11+
and a short description of what they do, similar to the following:
12+
13+
====
14+
[source, bash]
15+
----
16+
my-shell:>help
17+
AVAILABLE COMMANDS
18+
19+
Built-In Commands
20+
exit: Exit the shell.
21+
help: Display help about available commands
22+
stacktrace: Display the full stacktrace of the last error.
23+
clear: Clear the shell screen.
24+
quit: Exit the shell.
25+
history: Display or save the history of previously run commands
26+
completion bash: Generate bash completion script
27+
version: Show version info
28+
script: Read and execute commands from a file.
29+
----
30+
====
31+
32+
Typing `help <command>` shows more detailed information about a command, including the available parameters, their
33+
type, whether they are mandatory or not, and other details.
34+
35+
The following listing shows the `help` command applied to itself:
36+
37+
====
38+
[source, bash]
39+
----
40+
my-shell:>help help
41+
NAME
42+
help - Display help about available commands
43+
44+
SYNOPSIS
45+
help --command String
46+
47+
OPTIONS
48+
--command or -C String
49+
The command to obtain help for.
50+
[Optional]
51+
----
52+
====
53+
54+
Help is templated and can be customized if needed. Settings are under `spring.shell.command.help` where you can use
55+
`enabled` to disable command, `grouping-mode` taking `group` or `flat` if you want to hide groups by flattening
56+
a structure, `command-template` to define your template for output of a command help, `commands-template` to define
57+
output of a command list.
58+
59+
If `spring.shell.command.help.grouping-mode=flat` is set, then help would show:
60+
61+
====
62+
[source, bash]
63+
----
64+
my-shell:>help help
65+
AVAILABLE COMMANDS
66+
67+
exit: Exit the shell.
68+
help: Display help about available commands
69+
stacktrace: Display the full stacktrace of the last error.
70+
clear: Clear the shell screen.
71+
quit: Exit the shell.
72+
history: Display or save the history of previously run commands
73+
completion bash: Generate bash completion script
74+
version: Show version info
75+
script: Read and execute commands from a file.
76+
----
77+
====
78+
79+
Output from `help` and `help <commmand>` are both templated with a default implementation
80+
which can be changed.
81+
82+
Option `spring.shell.command.help.commands-template` defaults to
83+
`classpath:template/help-commands-default.stg` and is passed `GroupsInfoModel`
84+
as a model.
85+
86+
Option `spring.shell.command.help.command-template` defaults to
87+
`classpath:template/help-command-default.stg` and is passed `CommandInfoModel`
88+
as a model.
89+
90+
[[groupsinfomodel-variables]]
91+
.GroupsInfoModel Variables
92+
|===
93+
|Key |Description
94+
95+
|`showGroups`
96+
|`true` if showing groups is enabled. Otherwise, false.
97+
98+
|`groups`
99+
|The commands variables (see <<groupcommandinfomodel-variables>>).
100+
101+
|`commands`
102+
|The commands variables (see <<commandinfomodel-variables>>).
103+
104+
|`hasUnavailableCommands`
105+
|`true` if there is unavailable commands. Otherwise, false.
106+
|===
107+
108+
[[groupcommandinfomodel-variables]]
109+
.GroupCommandInfoModel Variables
110+
|===
111+
|Key |Description
112+
113+
|`group`
114+
|The name of a group, if set. Otherwise, empty.
115+
116+
|`commands`
117+
|The commands, if set. Otherwise, empty. Type is a multi value, see <<commandinfomodel-variables>>.
118+
|===
119+
120+
[[commandinfomodel-variables]]
121+
.CommandInfoModel Variables
122+
|===
123+
|Key |Description
124+
125+
|`name`
126+
|The name of a command, if set. Otherwise, null. Type is string and contains full command.
127+
128+
|`names`
129+
|The names of a command, if set. Otherwise, null. Type is multi value essentially `name` splitted.
130+
131+
|`aliases`
132+
|The possible aliases, if set. Type is multi value with strings.
133+
134+
|`description`
135+
|The description of a command, if set. Otherwise, null.
136+
137+
|`parameters`
138+
|The parameters variables, if set. Otherwise empty. Type is a multi value, see <<commandparameterinfomodel-variables>>.
139+
140+
|`availability`
141+
|The availability variables (see <<commandavailabilityinfomodel-variables>>).
142+
|===
143+
144+
[[commandparameterinfomodel-variables]]
145+
.CommandParameterInfoModel Variables
146+
|===
147+
|Key |Description
148+
149+
|`type`
150+
|The type of a parameter if set. Otherwise, null.
151+
152+
|`arguments`
153+
|The arguments, if set. Otherwise, null. Type is multi value with strings.
154+
155+
|`required`
156+
|`true` if required. Otherwise, false.
157+
158+
|`description`
159+
|The description of a parameter, if set. Otherwise, null.
160+
161+
|`defaultValue`
162+
|The default value of a parameter, if set. Otherwise, null.
163+
164+
|`hasDefaultValue`
165+
|`true` if defaultValue exists. Otherwise, false.
166+
|===
167+
168+
[[commandavailabilityinfomodel-variables]]
169+
.CommandAvailabilityInfoModel Variables
170+
|===
171+
|Key |Description
172+
173+
|`available`
174+
|`true` if available. Otherwise, false.
175+
176+
|`reason`
177+
|The reason if not available if set. Otherwise, null.
178+
|===

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-history.adoc

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[[built-in-commands-history]]
2+
==== History
3+
4+
The `history` command shows the history of commands that has been executed.
5+
6+
There are a few configuration options that you can use to configure behavior
7+
of a history. History is kept in a log file, which is enabled by default and can
8+
be turned off by setting `spring.shell.history.enabled`. The name of a log file
9+
is resolved from `spring.application.name` and defaults to `spring-shell.log`,
10+
which you can change by setting `spring.shell.history.name`.
11+
12+
By default, a log file is generated to a current working directory, which you can dictate
13+
by setting `spring.shell.config.location`. This property can contain
14+
a placeholder (`{userconfig}`), which resolves to a common shared config directory.
15+
16+
TIP: Run the Spring Shell application to see how the sample application works as it uses these options.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-script.adoc

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[[built-in-commands-script]]
2+
==== Script
3+
4+
The `script` command accepts a local file as an argument and replays commands found there, one at a time.
5+
6+
Reading from the file behaves exactly like inside the interactive shell, so lines starting with `//` are considered
7+
to be comments and are ignored, while lines ending with `\` trigger line continuation.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-stacktrace.adoc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[[built-in-commands-stacktrace]]
2+
==== Stacktrace
3+
4+
When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed
5+
so as not to overflow the user with too much information.
6+
There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause).
7+
8+
To this end, Spring Shell remembers the last exception that occurred, and the user can later use the `stacktrace`
9+
command to print all the details on the console.

‎spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-version.adoc

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[[built-in-commands-version]]
2+
==== Version
3+
4+
The `version` command shows existing build and git info by integrating into
5+
Boot's `BuildProperties` and `GitProperties` if those exist in the shell application.
6+
By default, only version information is shown, and you can enable other information through configuration
7+
options.
8+
9+
The relevant settings are under `spring.shell.command.version`, where you can use `enabled` to
10+
disable a command and, optionally, define your own template with `template`. You can use the
11+
`show-build-artifact`, `show-build-group`, `show-build-name`, `show-build-time`,
12+
`show-build-version`, `show-git-branch`, `show-git-commit-id`,
13+
`show-git-short-commit-id` and `show-git-commit-time` commands to control
14+
fields in a default template.
15+
16+
The template defaults to `classpath:template/version-default.st`, and you can define
17+
your own, as the following example shows:
18+
19+
====
20+
[source]
21+
----
22+
<buildVersion>
23+
----
24+
====
25+
26+
This setting would output something like the following:
27+
28+
====
29+
[source]
30+
----
31+
X.X.X
32+
----
33+
====
34+
35+
You can add the following attributes to the default template rendering: `buildVersion`, `buildGroup`,
36+
`buildGroup`, `buildName`, `buildTime`, `gitShortCommitId`, `gitCommitId`,
37+
`gitBranch`, and `gitCommitTime`.

0 commit comments

Comments
 (0)