From 6e007fbf5f72baf75cfcce76a49385939b508c1c Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Wed, 17 Aug 2022 17:37:05 +0100 Subject: [PATCH] Split builtin command docs - Fixes #505 - Backport #504 (cherry picked from commit 57b925970109263e34ef04088260dcb80d0293da) --- .../using-shell-commands-annotationmodel.adoc | 2 +- .../using-shell-commands-availability.adoc | 2 +- .../using-shell-components-builtin-clear.adoc | 4 + ...g-shell-components-builtin-completion.adoc | 8 + .../using-shell-components-builtin-exit.adoc | 6 + .../using-shell-components-builtin-help.adoc | 178 ++++++++++++ ...sing-shell-components-builtin-history.adoc | 16 ++ ...using-shell-components-builtin-script.adoc | 7 + ...g-shell-components-builtin-stacktrace.adoc | 9 + ...sing-shell-components-builtin-version.adoc | 37 +++ .../using-shell-components-builtin.adoc | 268 +----------------- .../asciidoc/using-shell-options-generic.adoc | 2 +- 12 files changed, 276 insertions(+), 263 deletions(-) create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-clear.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-completion.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-exit.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-help.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-history.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-script.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-stacktrace.adoc create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-version.adoc diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc index 086c5bda..14d8c9e2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-annotationmodel.adoc @@ -24,7 +24,7 @@ include::{snippets}/AnnotationRegistrationSnippets.java[tag=snippet1] The only required attribute of the `@ShellMethod` annotation is its `value` attribute, which should have a short, one-sentence, description of what the command does. This lets your users -get consistent help about your commands without having to leave the shell (see <>). +get consistent help about your commands without having to leave the shell (see <>). NOTE: The description of your command should be short -- no more than one or two sentences. For better consistency, it should start with a capital letter and end with a period. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc index 3bf09621..95d53721 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc @@ -57,7 +57,7 @@ Details of the error have been omitted. You can use the stacktrace command to pr ---- ==== -Information about currently unavailable commands is also used in the integrated help. See <>. +Information about currently unavailable commands is also used in the integrated help. See <>. [TIP] ==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-clear.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-clear.adoc new file mode 100644 index 00000000..f335f39f --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-clear.adoc @@ -0,0 +1,4 @@ +[[built-in-commands-clear]] +==== Clear +The `clear` command does what you would expect and clears the screen, resetting the prompt +in the top left corner. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-completion.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-completion.adoc new file mode 100644 index 00000000..e933aefe --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-completion.adoc @@ -0,0 +1,8 @@ +[[built-in-commands-completion]] +==== Completion + +The `completion` command set lets you create script files that can be used +with am OS shell implementations to provide completion. This is very useful when +working with non-interactive mode. + +Currently, the only implementation is for bash, which works with `bash` sub-command. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-exit.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-exit.adoc new file mode 100644 index 00000000..bb380f37 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-exit.adoc @@ -0,0 +1,6 @@ +[[built-in-commands-exit]] +==== Exit + +The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully +closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all +commands to disk, so that they are available again on the next launch. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-help.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-help.adoc new file mode 100644 index 00000000..162234ab --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-help.adoc @@ -0,0 +1,178 @@ +[[built-in-commands-help]] +==== Help + +Running a shell application often implies that the user is in a graphically limited +environment. Also, while we are nearly always connected in the era of mobile phones, +accessing a web browser or any other rich UI application (such as a PDF viewer) may not always +be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help` +command comes in. + +Typing `help` + `ENTER` lists all the commands known to the shell (including <> commands) +and a short description of what they do, similar to the following: + +==== +[source, bash] +---- +my-shell:>help +AVAILABLE COMMANDS + +Built-In Commands + exit: Exit the shell. + help: Display help about available commands + stacktrace: Display the full stacktrace of the last error. + clear: Clear the shell screen. + quit: Exit the shell. + history: Display or save the history of previously run commands + completion bash: Generate bash completion script + version: Show version info + script: Read and execute commands from a file. +---- +==== + +Typing `help ` shows more detailed information about a command, including the available parameters, their +type, whether they are mandatory or not, and other details. + +The following listing shows the `help` command applied to itself: + +==== +[source, bash] +---- +my-shell:>help help +NAME + help - Display help about available commands + +SYNOPSIS + help --command String + +OPTIONS + --command or -C String + The command to obtain help for. + [Optional] +---- +==== + +Help is templated and can be customized if needed. Settings are under `spring.shell.command.help` where you can use +`enabled` to disable command, `grouping-mode` taking `group` or `flat` if you want to hide groups by flattening +a structure, `command-template` to define your template for output of a command help, `commands-template` to define +output of a command list. + +If `spring.shell.command.help.grouping-mode=flat` is set, then help would show: + +==== +[source, bash] +---- +my-shell:>help help +AVAILABLE COMMANDS + +exit: Exit the shell. +help: Display help about available commands +stacktrace: Display the full stacktrace of the last error. +clear: Clear the shell screen. +quit: Exit the shell. +history: Display or save the history of previously run commands +completion bash: Generate bash completion script +version: Show version info +script: Read and execute commands from a file. +---- +==== + +Output from `help` and `help ` are both templated with a default implementation +which can be changed. + +Option `spring.shell.command.help.commands-template` defaults to +`classpath:template/help-commands-default.stg` and is passed `GroupsInfoModel` +as a model. + +Option `spring.shell.command.help.command-template` defaults to +`classpath:template/help-command-default.stg` and is passed `CommandInfoModel` +as a model. + +[[groupsinfomodel-variables]] +.GroupsInfoModel Variables +|=== +|Key |Description + +|`showGroups` +|`true` if showing groups is enabled. Otherwise, false. + +|`groups` +|The commands variables (see <>). + +|`commands` +|The commands variables (see <>). + +|`hasUnavailableCommands` +|`true` if there is unavailable commands. Otherwise, false. +|=== + +[[groupcommandinfomodel-variables]] +.GroupCommandInfoModel Variables +|=== +|Key |Description + +|`group` +|The name of a group, if set. Otherwise, empty. + +|`commands` +|The commands, if set. Otherwise, empty. Type is a multi value, see <>. +|=== + +[[commandinfomodel-variables]] +.CommandInfoModel Variables +|=== +|Key |Description + +|`name` +|The name of a command, if set. Otherwise, null. Type is string and contains full command. + +|`names` +|The names of a command, if set. Otherwise, null. Type is multi value essentially `name` splitted. + +|`aliases` +|The possible aliases, if set. Type is multi value with strings. + +|`description` +|The description of a command, if set. Otherwise, null. + +|`parameters` +|The parameters variables, if set. Otherwise empty. Type is a multi value, see <>. + +|`availability` +|The availability variables (see <>). +|=== + +[[commandparameterinfomodel-variables]] +.CommandParameterInfoModel Variables +|=== +|Key |Description + +|`type` +|The type of a parameter if set. Otherwise, null. + +|`arguments` +|The arguments, if set. Otherwise, null. Type is multi value with strings. + +|`required` +|`true` if required. Otherwise, false. + +|`description` +|The description of a parameter, if set. Otherwise, null. + +|`defaultValue` +|The default value of a parameter, if set. Otherwise, null. + +|`hasDefaultValue` +|`true` if defaultValue exists. Otherwise, false. +|=== + +[[commandavailabilityinfomodel-variables]] +.CommandAvailabilityInfoModel Variables +|=== +|Key |Description + +|`available` +|`true` if available. Otherwise, false. + +|`reason` +|The reason if not available if set. Otherwise, null. +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-history.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-history.adoc new file mode 100644 index 00000000..0e79d5cf --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-history.adoc @@ -0,0 +1,16 @@ +[[built-in-commands-history]] +==== History + +The `history` command shows the history of commands that has been executed. + +There are a few configuration options that you can use to configure behavior +of a history. History is kept in a log file, which is enabled by default and can +be turned off by setting `spring.shell.history.enabled`. The name of a log file +is resolved from `spring.application.name` and defaults to `spring-shell.log`, +which you can change by setting `spring.shell.history.name`. + +By default, a log file is generated to a current working directory, which you can dictate +by setting `spring.shell.config.location`. This property can contain +a placeholder (`{userconfig}`), which resolves to a common shared config directory. + +TIP: Run the Spring Shell application to see how the sample application works as it uses these options. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-script.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-script.adoc new file mode 100644 index 00000000..b87416af --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-script.adoc @@ -0,0 +1,7 @@ +[[built-in-commands-script]] +==== Script + +The `script` command accepts a local file as an argument and replays commands found there, one at a time. + +Reading from the file behaves exactly like inside the interactive shell, so lines starting with `//` are considered +to be comments and are ignored, while lines ending with `\` trigger line continuation. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-stacktrace.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-stacktrace.adoc new file mode 100644 index 00000000..ba9684ba --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-stacktrace.adoc @@ -0,0 +1,9 @@ +[[built-in-commands-stacktrace]] +==== Stacktrace + +When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed +so as not to overflow the user with too much information. +There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause). + +To this end, Spring Shell remembers the last exception that occurred, and the user can later use the `stacktrace` +command to print all the details on the console. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-version.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-version.adoc new file mode 100644 index 00000000..dc8339e6 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin-version.adoc @@ -0,0 +1,37 @@ +[[built-in-commands-version]] +==== Version + +The `version` command shows existing build and git info by integrating into +Boot's `BuildProperties` and `GitProperties` if those exist in the shell application. +By default, only version information is shown, and you can enable other information through configuration +options. + +The relevant settings are under `spring.shell.command.version`, where you can use `enabled` to +disable a command and, optionally, define your own template with `template`. You can use the +`show-build-artifact`, `show-build-group`, `show-build-name`, `show-build-time`, +`show-build-version`, `show-git-branch`, `show-git-commit-id`, +`show-git-short-commit-id` and `show-git-commit-time` commands to control +fields in a default template. + +The template defaults to `classpath:template/version-default.st`, and you can define +your own, as the following example shows: + +==== +[source] +---- + +---- +==== + +This setting would output something like the following: + +==== +[source] +---- +X.X.X +---- +==== + +You can add the following attributes to the default template rendering: `buildVersion`, `buildGroup`, +`buildGroup`, `buildName`, `buildTime`, `gitShortCommitId`, `gitCommitId`, +`gitBranch`, and `gitCommitTime`. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc index c8e2f3c8..9ac9752f 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-builtin.adoc @@ -1,270 +1,18 @@ [[built-in-commands]] === Built-In Commands -[[help-command]] -==== Help +include::using-shell-components-builtin-help.adoc[] -Running a shell application often implies that the user is in a graphically limited -environment. Also, while we are nearly always connected in the era of mobile phones, -accessing a web browser or any other rich UI application (such as a PDF viewer) may not always -be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help` -command comes in. +include::using-shell-components-builtin-clear.adoc[] -Typing `help` + `ENTER` lists all the commands known to the shell (including <> commands) -and a short description of what they do, similar to the following: +include::using-shell-components-builtin-exit.adoc[] -==== -[source, bash] ----- -my-shell:>help -AVAILABLE COMMANDS +include::using-shell-components-builtin-stacktrace.adoc[] -Built-In Commands - exit: Exit the shell. - help: Display help about available commands - stacktrace: Display the full stacktrace of the last error. - clear: Clear the shell screen. - quit: Exit the shell. - history: Display or save the history of previously run commands - completion bash: Generate bash completion script - version: Show version info - script: Read and execute commands from a file. ----- -==== +include::using-shell-components-builtin-script.adoc[] -Typing `help ` shows more detailed information about a command, including the available parameters, their -type, whether they are mandatory or not, and other details. +include::using-shell-components-builtin-history.adoc[] -The following listing shows the `help` command applied to itself: +include::using-shell-components-builtin-completion.adoc[] -==== -[source, bash] ----- -my-shell:>help help -NAME - help - Display help about available commands - -SYNOPSIS - help --command String - -OPTIONS - --command or -C String - The command to obtain help for. - [Optional] ----- -==== - -Help is templated and can be customized if needed. Settings are under `spring.shell.command.help` where you can use -`enabled` to disable command, `grouping-mode` taking `group` or `flat` if you want to hide groups by flattening -a structure, `command-template` to define your template for output of a command help, `commands-template` to define -output of a command list. - -If `spring.shell.command.help.grouping-mode=flat` is set, then help would show: - -==== -[source, bash] ----- -my-shell:>help help -AVAILABLE COMMANDS - -exit: Exit the shell. -help: Display help about available commands -stacktrace: Display the full stacktrace of the last error. -clear: Clear the shell screen. -quit: Exit the shell. -history: Display or save the history of previously run commands -completion bash: Generate bash completion script -version: Show version info -script: Read and execute commands from a file. ----- -==== - -Output from `help` and `help ` are both templated with a default implementation -which can be changed. - -Option `spring.shell.command.help.commands-template` defaults to -`classpath:template/help-commands-default.stg` and is passed `GroupsInfoModel` -as a model. - -Option `spring.shell.command.help.command-template` defaults to -`classpath:template/help-command-default.stg` and is passed `CommandInfoModel` -as a model. - -[[groupsinfomodel-variables]] -.GroupsInfoModel Variables -|=== -|Key |Description - -|`showGroups` -|`true` if showing groups is enabled. Otherwise, false. - -|`groups` -|The commands variables (see <>). - -|`commands` -|The commands variables (see <>). - -|`hasUnavailableCommands` -|`true` if there is unavailable commands. Otherwise, false. -|=== - -[[groupcommandinfomodel-variables]] -.GroupCommandInfoModel Variables -|=== -|Key |Description - -|`group` -|The name of a group, if set. Otherwise, empty. - -|`commands` -|The commands, if set. Otherwise, empty. Type is a multi value, see <>. -|=== - -[[commandinfomodel-variables]] -.CommandInfoModel Variables -|=== -|Key |Description - -|`name` -|The name of a command, if set. Otherwise, null. Type is string and contains full command. - -|`names` -|The names of a command, if set. Otherwise, null. Type is multi value essentially `name` splitted. - -|`aliases` -|The possible aliases, if set. Type is multi value with strings. - -|`description` -|The description of a command, if set. Otherwise, null. - -|`parameters` -|The parameters variables, if set. Otherwise empty. Type is a multi value, see <>. - -|`availability` -|The availability variables (see <>). -|=== - -[[commandparameterinfomodel-variables]] -.CommandParameterInfoModel Variables -|=== -|Key |Description - -|`type` -|The type of a parameter if set. Otherwise, null. - -|`arguments` -|The arguments, if set. Otherwise, null. Type is multi value with strings. - -|`required` -|`true` if required. Otherwise, false. - -|`description` -|The description of a parameter, if set. Otherwise, null. - -|`defaultValue` -|The default value of a parameter, if set. Otherwise, null. - -|`hasDefaultValue` -|`true` if defaultValue exists. Otherwise, false. -|=== - -[[commandavailabilityinfomodel-variables]] -.CommandAvailabilityInfoModel Variables -|=== -|Key |Description - -|`available` -|`true` if available. Otherwise, false. - -|`reason` -|The reason if not available if set. Otherwise, null. -|=== - -==== Clear -The `clear` command does what you would expect and clears the screen, resetting the prompt -in the top left corner. - -==== Exit - -The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully -closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all -commands to disk, so that they are available again on the next launch. - -==== Stacktrace - -When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed -so as not to overflow the user with too much information. -There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause). - -To this end, Spring Shell remembers the last exception that occurred, and the user can later use the `stacktrace` -command to print all the details on the console. - -[[script-command]] -==== Script - -The `script` command accepts a local file as an argument and replays commands found there, one at a time. - -Reading from the file behaves exactly like inside the interactive shell, so lines starting with `//` are considered -to be comments and are ignored, while lines ending with `\` trigger line continuation. - -==== History - -The `history` command shows the history of commands that has been executed. - -There are a few configuration options that you can use to configure behavior -of a history. History is kept in a log file, which is enabled by default and can -be turned off by setting `spring.shell.history.enabled`. The name of a log file -is resolved from `spring.application.name` and defaults to `spring-shell.log`, -which you can change by setting `spring.shell.history.name`. - -By default, a log file is generated to a current working directory, which you can dictate -by setting `spring.shell.config.location`. This property can contain -a placeholder (`{userconfig}`), which resolves to a common shared config directory. - -TIP: Run the Spring Shell application to see how the sample application works as it uses these options. - -[[built-in-commands-completion]] -==== Completion - -The `completion` command set lets you create script files that can be used -with am OS shell implementations to provide completion. This is very useful when -working with non-interactive mode. - -Currently, the only implementation is for bash, which works with `bash` sub-command. - -==== Version - -The `version` command shows existing build and git info by integrating into -Boot's `BuildProperties` and `GitProperties` if those exist in the shell application. -By default, only version information is shown, and you can enable other information through configuration -options. - -The relevant settings are under `spring.shell.command.version`, where you can use `enabled` to -disable a command and, optionally, define your own template with `template`. You can use the -`show-build-artifact`, `show-build-group`, `show-build-name`, `show-build-time`, -`show-build-version`, `show-git-branch`, `show-git-commit-id`, -`show-git-short-commit-id` and `show-git-commit-time` commands to control -fields in a default template. - -The template defaults to `classpath:template/version-default.st`, and you can define -your own, as the following example shows: - -==== -[source] ----- - ----- -==== - -This setting would output something like the following: - -==== -[source] ----- -X.X.X ----- -==== - -You can add the following attributes to the default template rendering: `buildVersion`, `buildGroup`, -`buildGroup`, `buildName`, `buildTime`, `gitShortCommitId`, `gitCommitId`, -`gitBranch`, and `gitCommitTime`. +include::using-shell-components-builtin-version.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc index e574408a..ad1dd5e2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc @@ -77,7 +77,7 @@ For such a setup, the possible parameter keys are `-a`, `-b` and `--third`. ===== You can specify several keys for a single parameter. If you do so, these keys are mutually exclusive (only one of them can be used) ways to specify the same parameter. The following example shows the signature of the -built-in <> command: +built-in <> command: ==== [source, java]