diff --git a/spring-shell-docs/antora-playbook.yml b/spring-shell-docs/antora-playbook.yml new file mode 100644 index 00000000..60fc812f --- /dev/null +++ b/spring-shell-docs/antora-playbook.yml @@ -0,0 +1,43 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@springio/antora-extensions/partial-build-extension' + - require: '@springio/antora-extensions/latest-version-extension' + - require: '@springio/antora-extensions/inject-collector-cache-config-extension' + - '@antora/collector-extension' + - '@antora/atlas-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'shell' + - require: '@springio/antora-extensions/asciinema-extension' +site: + title: Spring Shell + url: https://docs.spring.io/spring-shell/reference/ +content: + sources: + - url: ./.. + branches: HEAD + start_path: spring-shell-docs + worktrees: true +asciidoc: + attributes: + page-stackoverflow-url: https://stackoverflow.com/tags/spring-shell + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip + snapshot: true diff --git a/spring-shell-docs/antora.yml b/spring-shell-docs/antora.yml new file mode 100644 index 00000000..9b34c10b --- /dev/null +++ b/spring-shell-docs/antora.yml @@ -0,0 +1,20 @@ +name: shell +version: true +title: Spring Shell +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-shell-docs:generateAntoraYml + local: true + scan: + dir: ./build/generated-antora-resources + +asciidoc: + attributes: + attribute-missing: 'warn' + # FIXME: the copyright is not removed + # FIXME: The package is not renamed + chomp: 'all' + snippets: example$docs-src/test/java/org/springframework/shell/docs \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-confirmation-1.cast b/spring-shell-docs/modules/ROOT/examples/component-confirmation-1.cast similarity index 95% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-confirmation-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-confirmation-1.cast index 084b89a6..d263c7ce 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-confirmation-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-confirmation-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 8, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.590847, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.590847, "o", "java -jar spring-shell-sample-commands.jar"] [2.774407, "o", "\r\n"] [4.560309, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [5.138757, "o", "\u001b[31mc\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-flow-conditional-1.cast b/spring-shell-docs/modules/ROOT/examples/component-flow-conditional-1.cast similarity index 96% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-flow-conditional-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-flow-conditional-1.cast index 600e59e0..b76a0494 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-flow-conditional-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-flow-conditional-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 11, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.590847, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.590847, "o", "java -jar spring-shell-sample-commands.jar"] [5.030349, "o", "\r\n"] [7.108752, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [7.604731, "o", "\u001b[31mf\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-flow-showcase-1.cast b/spring-shell-docs/modules/ROOT/examples/component-flow-showcase-1.cast similarity index 97% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-flow-showcase-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-flow-showcase-1.cast index 354bd5c8..71ce141a 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-flow-showcase-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-flow-showcase-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 15, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.590847, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.590847, "o", "java -jar spring-shell-sample-commands.jar"] [5.968022, "o", "\r\n"] [8.099727, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [11.261894, "o", "\u001b[1mflow showcase\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-multi-select-1.cast b/spring-shell-docs/modules/ROOT/examples/component-multi-select-1.cast similarity index 96% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-multi-select-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-multi-select-1.cast index a67305c0..a37a3f69 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-multi-select-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-multi-select-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 9, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.746447, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.746447, "o", "java -jar spring-shell-sample-commands.jar"] [2.881033, "o", "\r\n"] [4.603396, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [5.105471, "o", "\u001b[31mc\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-path-input-1.cast b/spring-shell-docs/modules/ROOT/examples/component-path-input-1.cast similarity index 95% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-path-input-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-path-input-1.cast index 79b21c8f..7c014093 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-path-input-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-path-input-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 6, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.276071, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.276071, "o", "java -jar spring-shell-sample-commands.jar"] [1.975169, "o", "\r\n"] [3.730642, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [4.157171, "o", "\u001b[31mc\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-path-search-1.cast b/spring-shell-docs/modules/ROOT/examples/component-path-search-1.cast similarity index 97% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-path-search-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-path-search-1.cast index 50f9047f..0ce13e66 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-path-search-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-path-search-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 10, "timestamp": 1666162443, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.881363, "o", "java -jar spring-shell-samples/build/libs/spring-shell-samples.jar"] +[1.881363, "o", "java -jar spring-shell-sample-commands.jar"] [2.630692, "o", "\r\n"] [6.50287, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [8.347165, "o", "\u001b[1mcomponent path search\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-single-select-1.cast b/spring-shell-docs/modules/ROOT/examples/component-single-select-1.cast similarity index 96% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-single-select-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-single-select-1.cast index e2c1c576..e4f83924 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-single-select-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-single-select-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 8, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[2.193321, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[2.193321, "o", "java -jar spring-shell-sample-commands.jar"] [3.11524, "o", "\r\n"] [4.904714, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [5.372714, "o", "\u001b[31mc\u001b[0m"] diff --git a/spring-shell-docs/src/main/asciidoc/asciinema/component-text-input-1.cast b/spring-shell-docs/modules/ROOT/examples/component-text-input-1.cast similarity index 94% rename from spring-shell-docs/src/main/asciidoc/asciinema/component-text-input-1.cast rename to spring-shell-docs/modules/ROOT/examples/component-text-input-1.cast index 2e9ea6e5..e773bc54 100644 --- a/spring-shell-docs/src/main/asciidoc/asciinema/component-text-input-1.cast +++ b/spring-shell-docs/modules/ROOT/examples/component-text-input-1.cast @@ -1,5 +1,5 @@ {"version": 2, "width": 85, "height": 6, "timestamp": 1645645867, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}} -[1.262977, "o", "java -jar spring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jar"] +[1.262977, "o", "java -jar spring-shell-sample-commands.jar"] [2.045105, "o", "\r\n"] [3.846992, "o", "\u001b[?1h\u001b=\u001b[?2004h\u001b[33mmy-shell:>\u001b[0m"] [4.717927, "o", "\u001b[31mc\u001b[0m"] diff --git a/spring-shell-docs/modules/ROOT/examples/docs-src b/spring-shell-docs/modules/ROOT/examples/docs-src new file mode 120000 index 00000000..dabb0e15 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/examples/docs-src @@ -0,0 +1 @@ +../../../src \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/code/getting-started-run-interactive.out b/spring-shell-docs/modules/ROOT/examples/getting-started-run-interactive.out similarity index 100% rename from spring-shell-docs/src/main/asciidoc/code/getting-started-run-interactive.out rename to spring-shell-docs/modules/ROOT/examples/getting-started-run-interactive.out diff --git a/spring-shell-docs/src/main/asciidoc/code/getting-started-run-noninteractive.out b/spring-shell-docs/modules/ROOT/examples/getting-started-run-noninteractive.out similarity index 100% rename from spring-shell-docs/src/main/asciidoc/code/getting-started-run-noninteractive.out rename to spring-shell-docs/modules/ROOT/examples/getting-started-run-noninteractive.out diff --git a/spring-shell-docs/modules/ROOT/nav.adoc b/spring-shell-docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..6685d36f --- /dev/null +++ b/spring-shell-docs/modules/ROOT/nav.adoc @@ -0,0 +1,74 @@ +* xref:index.adoc[Overview] +* xref:getting-started.adoc[] +* xref:basics/index.adoc[] +** xref:basics/reading.adoc[] +* xref:commands/index.adoc[] +** xref:commands/registration/index.adoc[] +** xref:commands/registration/programmatic.adoc[] +** xref:commands/registration/annotation.adoc[] +** xref:commands/registration/legacyannotation.adoc[] +** xref:commands/organize.adoc[] +** xref:commands/availability.adoc[] +** xref:commands/exceptionhandling/index.adoc[] +*** xref:commands/exceptionhandling/resolving.adoc[] +*** xref:commands/exceptionhandling/mappings.adoc[] +*** xref:commands/exceptionhandling/annotation.adoc[] +** xref:commands/hidden.adoc[] +** xref:commands/helpoptions.adoc[] +** xref:commands/interactionmode.adoc[] +** xref:commands/builtin/index.adoc[] +*** xref:commands/builtin/help.adoc[] +*** xref:commands/builtin/clear.adoc[] +*** xref:commands/builtin/exit.adoc[] +*** xref:commands/builtin/stacktrace.adoc[] +*** xref:commands/builtin/script.adoc[] +*** xref:commands/builtin/history.adoc[] +*** xref:commands/builtin/completion.adoc[] +*** xref:commands/builtin/version.adoc[] +** xref:commands/writing.adoc[] +* xref:options/index.adoc[] +** xref:options/basics/index.adoc[] +*** xref:options/basics/programmatic.adoc[] +*** xref:options/basics/annotation.adoc[] +*** xref:options/basics/legacyannotation.adoc[] +** xref:options/short.adoc[] +** xref:options/arity.adoc[] +** xref:options/positional.adoc[] +** xref:options/optional.adoc[] +** xref:options/default.adoc[] +** xref:options/validation.adoc[] +** xref:options/label.adoc[] +** xref:options/types.adoc[] +** xref:options/naming.adoc[] +* xref:completion.adoc[] +* xref:building.adoc[] +* xref:components/index.adoc[] +** xref:components/flow/index.adoc[] +** xref:components/ui/index.adoc[] +*** xref:components/ui/render.adoc[] +*** xref:components/ui/stringinput.adoc[] +*** xref:components/ui/pathinput.adoc[] +*** xref:components/ui/pathsearch.adoc[] +*** xref:components/ui/confirmation.adoc[] +*** xref:components/ui/singleselect.adoc[] +*** xref:components/ui/multiselect.adoc[] +* xref:customization/index.adoc[] +** xref:customization/styling.adoc[] +** xref:customization/logging.adoc[] +** xref:customization/commandnotfound.adoc[] +** xref:customization/singlecommand.adoc[] +** xref:customization/contextclose.adoc[] +* xref:execution.adoc[] +* xref:testing/index.adoc[] +** xref:testing/basics.adoc[] +** xref:testing/settings.adoc[] +* Appendices +** xref:appendices/techintro/index.adoc[] +*** xref:appendices/techintro/registration.adoc[] +*** xref:appendices/techintro/parser.adoc[] +*** xref:appendices/techintro/execution.adoc[] +*** xref:appendices/techintro/commandcontext.adoc[] +*** xref:appendices/techintro/commandcatalog.adoc[] +*** xref:appendices/techintro/theming.adoc[] +*** xref:appendices/techintro/searchalgorithm.adoc[] +** xref:appendices/debugging/index.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/debugging/index.adoc similarity index 79% rename from spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/debugging/index.adoc index d78b03c7..fa1356c2 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/debugging/index.adoc @@ -1,5 +1,6 @@ [appendix] [#appendix-debugging] -== Debugging += Debugging +:page-section-summary-toc: 1 Please find more info about debugging from https://github.com/spring-projects/spring-shell/wiki/Debugging[project wiki]. diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcatalog.adoc similarity index 85% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcatalog.adoc index 22c3f6e2..3410b0d7 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcatalog.adoc @@ -1,43 +1,43 @@ -=== Command Catalog +[[command-catalog]] += Command Catalog + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] + The `CommandCatalog` interface defines how command registrations exist in a shell application. It is possible to dynamically register and de-register commands, which gives flexibility for use cases where possible commands come and go, depending on a shell's state. Consider the following example: -==== [source, java, indent=0] ---- include::{snippets}/CommandCatalogSnippets.java[tag=snippet1] ---- -==== -==== Command Resolver +[[command-resolver]] +== Command Resolver You can implement the `CommandResolver` interface and define a bean to dynamically resolve mappings from a command's name to its `CommandRegistration` instances. Consider the following example: -==== [source, java, indent=0] ---- include::{snippets}/CommandCatalogSnippets.java[tag=snippet2] ---- -==== IMPORTANT: A current limitation of a `CommandResolver` is that it is used every time commands are resolved. Thus, we advise not using it if a command resolution call takes a long time, as it would make the shell feel sluggish. -==== Command Catalog Customizer +[[command-catalog-customizer]] +== Command Catalog Customizer You can use the `CommandCatalogCustomizer` interface to customize a `CommandCatalog`. Its main use is to modify a catalog. Also, within `spring-shell` auto-configuration, this interface is used to register existing `CommandRegistration` beans into a catalog. Consider the following example: -==== [source, java, indent=0] ---- include::{snippets}/CommandCatalogSnippets.java[tag=snippet3] ---- -==== You can create a `CommandCatalogCustomizer` as a bean, and Spring Shell handles the rest. diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcontext.adoc similarity index 72% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcontext.adoc index 8593a4df..6a8d390a 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/commandcontext.adoc @@ -1,20 +1,21 @@ -=== Command Context +[[command-context]] += Command Context +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] + The `CommandContext` interface gives access to a currently running context. You can use it to get access to options: -==== [source, java, indent=0] ---- include::{snippets}/CommandContextSnippets.java[tag=snippet1] ---- -==== If you need to print something into a shell, you can get a `Terminal` and use its writer to print something: -==== [source, java, indent=0] ---- include::{snippets}/CommandContextSnippets.java[tag=snippet2] ---- -==== diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/techintro/execution.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/execution.adoc new file mode 100644 index 00000000..a27a0f59 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/execution.adoc @@ -0,0 +1,8 @@ +[[command-execution]] += Command Execution +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] + +When command parsing has done its job and command registration has been resolved, command execution +does the hard work of running the code. diff --git a/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc new file mode 100644 index 00000000..4af2f9d7 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc @@ -0,0 +1,14 @@ +[appendix] +[#appendix-tech-intro] += Techical Introduction +:page-section-summary-toc: 1 + +This appendix contains information for developers and others who would like to know more about how Spring Shell +works internally and what its design decisions are. + + + + + + + diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/parser.adoc similarity index 72% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/parser.adoc index 1ecc76ae..6d785205 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/parser.adoc @@ -1,3 +1,6 @@ -=== Command Parser +[[command-parser]] += Command Parser +:page-section-summary-toc: 1 + Before a command can be executed, we need to parse the command and whatever options the user may have provided. Parsing comes between command registration and command execution. diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/registration.adoc similarity index 91% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/registration.adoc index 415461d3..fc9957ab 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/registration.adoc @@ -1,16 +1,17 @@ [#appendix-tech-intro-registration] -=== Command Registration -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Command Registration + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] Defining a command registration is a first step to introducing the structure of a command and its options and parameters. This is loosely decoupled from what happens later, such as parsing command-line input and running actual target code. Essentially, it is the definition of a command API that is shown to a user. -==== Commands +[[commands]] +== Commands A command in a `spring-shell` structure is defined as an array of commands. This yields a structure similar to the following example: -==== [source, bash] ---- command1 sub1 @@ -18,12 +19,12 @@ command2 sub1 subsub1 command2 sub2 subsub1 command2 sub2 subsub2 ---- -==== NOTE: We do not currently support mapping commands to an explicit parent if sub-commands are defined. For example, `command1 sub1` and `command1 sub1 subsub1` cannot both be registered. -==== Interaction Mode +[[interaction-mode]] +== Interaction Mode Spring Shell has been designed to work on two modes: interactive (which essentially is a `REPL` where you have an active shell instance throughout a series of commands) and non-interactive (where commands are executed one by one from a command line). @@ -36,70 +37,63 @@ dictates the available information. Also, being on an active `REPL` session may provide more information about what the user has been doing within an active session. -==== Options +[[options]] +== Options Options can be defined as long and short, where the prefixing is `--` and `-`, respectively. The following examples show long and short options: -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationSnippets.java[tag=snippet1] ---- -==== -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationSnippets.java[tag=snippet2] ---- -==== -==== Target +[[target]] +== Target The target defines the execution target of a command. It can be a method in a POJO, a `Consumer`, or a `Function`. -===== Method +[[method]] +=== Method Using a `Method` in an existing POJO is one way to define a target. Consider the following class: -==== [source, java, indent=0] ---- include::{snippets}/CommandTargetSnippets.java[tag=snippet11] ---- -==== Given the existing class shown in the preceding listing, you can then register its method: -==== [source, java, indent=0] ---- include::{snippets}/CommandTargetSnippets.java[tag=snippet12] ---- -==== -===== Function +[[function]] +=== Function Using a `Function` as a target gives a lot of flexibility to handle what happens in a command execution, because you can handle many things manually by using a `CommandContext` given to a `Function`. The return type from a `Function` is then what gets printed into the shell as a result. Consider the following example: -==== [source, java, indent=0] ---- include::{snippets}/CommandTargetSnippets.java[tag=snippet2] ---- -==== -===== Consumer +[[consumer]] +=== Consumer Using a `Consumer` is basically the same as using a `Function`, with the difference being that there is no return type. If you need to print something into a shell, you can get a reference to a `Terminal` from a context and print something through it. Consider the following example: -==== [source, java, indent=0] ---- include::{snippets}/CommandTargetSnippets.java[tag=snippet3] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/searchalgorithm.adoc similarity index 87% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/searchalgorithm.adoc index 5fa9492f..e319fc77 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/searchalgorithm.adoc @@ -1,6 +1,7 @@ [#appendix-tech-intro-searchalgorithm] -=== Search Algorithms -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Search Algorithms + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] `SearchMatch` is an interface to match _text_ with a _pattern_. Match results are in a returned value `SearchMatchResult`. Match result @@ -8,7 +9,8 @@ contains info about match positions and overall score of a match. https://github.com/junegunn/fzf[fzf]. -==== Implementations +[[implementations]] +== Implementations *FuzzyMatchV2Search* @@ -20,19 +22,18 @@ quickly finding paths. Port of _fzf ExactMatchNaive_ algorithm. Simple exact match works more accurately if you know what to search. -==== SearchMatch +[[searchmatch]] +== SearchMatch Algorithms and default syntax are hidden inside package protected classes as we don't want to fully open these until we know API's are good to go for longer support. You need to construct `SearchMatch` via its build-in builder. -==== [source, java, indent=0] ---- include::{snippets}/SearchAlgorithmsSnippets.java[tag=builder] ---- -==== It's possible to configure _case sensitivity_, on what _direction_ search happens or if text should be _normilized_ before search happens. Normalization @@ -55,11 +56,10 @@ below table. |Items that include `stuff` |=== -==== Examples +[[examples]] +== Examples -==== [source, java, indent=0] ---- include::{snippets}/SearchAlgorithmsSnippets.java[tag=simple] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc similarity index 94% rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc rename to spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc index 15e4989b..c625df3e 100644 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc @@ -1,6 +1,7 @@ [#appendix-tech-intro-theming] -=== Theming -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Theming + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] Styling in a theming is provided by a use of a _AttributedString_ from `JLine`. Unfortunately styling in `JLine` is mostly undocumented but we try to go through @@ -22,7 +23,6 @@ applied. Prefixing with `~` will resolve from JLine internal bsd color table. If rgb format is expected and prefixed with either `x` or `#` a normal hex format is used. -==== [source, text] ---- fg-red @@ -31,30 +31,25 @@ fg-rgb:red fg-rgb:xff3333 fg-rgb:#ff3333 ---- -==== If spec contains special names `default`, `bold`, `faint`, `italic`, `underline`, `blink`, `inverse`, `inverse-neg`, `inverseneg`, `conceal`, `crossed-out`, `crossedout` or `hidden` a style is changed accordingly with an existing color. -==== [source, text] ---- bold bold,fg:red ---- -==== If spec is a number or numbers separated with semicolon, format is a plain part of an ansi ascii codes. -==== [source, text] ---- 31 31;1 ---- -==== NOTE: JLine special mapping format which would resolve spec starting with dot can't be used as we don't yet map those into Spring Shell styling names. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc b/spring-shell-docs/modules/ROOT/pages/basics/index.adoc similarity index 92% rename from spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc rename to spring-shell-docs/modules/ROOT/pages/basics/index.adoc index 39c83693..c54c90a2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc +++ b/spring-shell-docs/modules/ROOT/pages/basics/index.adoc @@ -1,5 +1,7 @@ [[using-shell-basics]] -== Basics += Basics +:page-section-summary-toc: 1 + This section covers the basics of Spring Shell. Before going on to define actual commands and options, we need to go through some of the fundamental concepts of Spring Shell. @@ -13,4 +15,3 @@ Essentially, a few things needs to happen before you have a working Spring Shell You can get a full working Spring Shell application without defining any user-level commands as some basic built-in commands (such as `help` and `history`) are provided. -include::using-shell-basics-reading.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc b/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc similarity index 72% rename from spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc rename to spring-shell-docs/modules/ROOT/pages/basics/reading.adoc index b1e089e1..a2eadf75 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc +++ b/spring-shell-docs/modules/ROOT/pages/basics/reading.adoc @@ -1,11 +1,12 @@ [[using-shell-basics-reading]] -=== Reading Docs += Reading Docs +:page-section-summary-toc: 1 Throughout this documentation, we make references to configuring something by using annotations or programmatic examples. -NOTE: There are two annotation models, <> -referred to new annotation model, <> +NOTE: There are two annotation models, xref:commands/registration/annotation.adoc[annotations] +referred to new annotation model, xref:commands/registration/legacyannotation.adoc[legacy annotations] referred to old legacy annotation model. Old legacy annotation model mostly relates to use of `@ShellMethod` and `@ShellOption` and @@ -15,4 +16,4 @@ The programmatic model is how things are actually registered, even if you use an NOTE: Currently whole documentation structure is in transit to provide better structure how things can be used using different ways to provide configurations. -So pardon a for little confusion now and there during a transit. \ No newline at end of file +So pardon a for little confusion now and there during a transit. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc b/spring-shell-docs/modules/ROOT/pages/building.adoc similarity index 94% rename from spring-shell-docs/src/main/asciidoc/using-shell-building.adoc rename to spring-shell-docs/modules/ROOT/pages/building.adoc index 0077819d..49b131d0 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc +++ b/spring-shell-docs/modules/ROOT/pages/building.adoc @@ -1,10 +1,10 @@ [[using-shell-building]] -== Building += Building This section covers how to build a Spring Shell application. [[native]] -=== Native Support +== Native Support Support for compiling _Spring Shell_ application into a _GraalVM_ binary mostly comes from _Spring Framework_ and _Spring Boot_ where feature is @@ -23,7 +23,6 @@ _GraalVM_ installed and `JAVA_HOME` pointing to that. For _gradle_ add graalvm's native plugin and configure metadata repository. -==== [source, groovy, subs=attributes+] ---- plugins { @@ -36,7 +35,6 @@ graalvmNative { } } ---- -==== When gradle build is run with `./gradlew nativeCompile` you should get binary under `build/native/nativeCompile` directory. @@ -44,7 +42,6 @@ under `build/native/nativeCompile` directory. For `maven` use `spring-boot-starter-parent` as parent and you'll get `native` profile which can be used to do a compilation. You need to configure metadata repository -==== [source, xml, subs=attributes+] ---- @@ -63,12 +60,11 @@ profile which can be used to do a compilation. You need to configure metadata re ---- -==== NOTE: If you rely on `spring-boot-starter-parent` it manages `native-maven-plugin` version which is kept up to date. -When maven build is run with `./mvnw package -Pnative` you should get binary +When maven build is run with `./mvnw native:compile -Pnative` you should get binary under `target` directory. If everything went well this binary can be run as is instead of executing diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc b/spring-shell-docs/modules/ROOT/pages/commands/availability.adoc similarity index 97% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/availability.adoc index 95d53721..5f96fd4f 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/availability.adoc @@ -1,5 +1,5 @@ [[dynamic-command-availability]] -=== Dynamic Command Availability += Dynamic Command Availability Registered commands do not always make sense, due to the internal state of the application. For example, there may be a `download` command, but it only works once the user has used `connect` on a remote @@ -12,7 +12,6 @@ There are three possible ways for a command to indicate availability. They all use a no-arg method that returns an instance of `Availability`. Consider the following example: -==== [source, java] ---- @ShellComponent @@ -38,7 +37,6 @@ public class MyCommands { } } ---- -==== The `connect` method is used to connect to the server (details omitted), altering the state of the command through the `connected` boolean when done. @@ -48,16 +46,14 @@ The method returns an instance of `Availability`, constructed with one of the tw If the command is not available, an explanation has to be provided. Now, if the user tries to invoke the command while not being connected, here is what happens: -==== [source] ---- shell:>download Command 'download' exists but is not currently available because you are not connected. Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace. ---- -==== -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 xref:commands/builtin/help.adoc[Help]. [TIP] ==== @@ -69,7 +65,6 @@ You should not start the sentence with a capital or add a final period If naming the availability method after the name of the command method does not suit you, you can provide an explicit name by using the `@ShellMethodAvailability` annotation: -==== [source, java] ---- @ShellMethod("Download the nuclear codes.") @@ -85,14 +80,12 @@ can provide an explicit name by using the `@ShellMethodAvailability` annotation: } ---- <1> the names have to match -==== Finally, it is often the case that several commands in the same class share the same internal state and, thus, should all be available or unavailable as a group. Instead of having to stick the `@ShellMethodAvailability` on all command methods, Spring Shell lets you flip things around and put the `@ShellMethodAvailabilty` annotation on the availability method, specifying the names of the commands that it controls: -==== [source, java] ---- @ShellMethod("Download the nuclear codes.") @@ -112,7 +105,6 @@ annotation on the availability method, specifying the names of the commands that : Availability.unavailable("you are not connected"); } ---- -==== [TIP] ===== @@ -120,7 +112,6 @@ The default value for the `@ShellMethodAvailability.value()` attribute is `*`. T wildcard matches all command names. This makes it easy to turn all commands of a single class on or off with a single availability method: -==== [source,java] ---- @ShellComponent @@ -139,7 +130,6 @@ public class Toggles { public void bar() {} } ---- -==== ===== TIP: Spring Shell does not impose many constraints on how to write commands and how to organize classes. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc similarity index 79% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc index f335f39f..0d36f1bd 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc @@ -1,4 +1,6 @@ [[built-in-commands-clear]] -==== Clear += Clear +:page-section-summary-toc: 1 + 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-commands-builtin-completion.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc similarity index 88% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-completion.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc index e933aefe..1e69a129 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-completion.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc @@ -1,5 +1,6 @@ [[built-in-commands-completion]] -==== Completion += Completion +:page-section-summary-toc: 1 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 diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/exit.adoc similarity index 88% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/exit.adoc index bb380f37..5f8e05c2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/exit.adoc @@ -1,5 +1,6 @@ [[built-in-commands-exit]] -==== Exit += Exit +:page-section-summary-toc: 1 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 diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc similarity index 87% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc index 162234ab..28e87e51 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc @@ -1,5 +1,5 @@ [[built-in-commands-help]] -==== 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, @@ -7,10 +7,9 @@ accessing a web browser or any other rich UI application (such as a PDF viewer) 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) +Typing `help` + `ENTER` lists all the commands known to the shell (including xref:commands/availability.adoc[unavailable] commands) and a short description of what they do, similar to the following: -==== [source, bash] ---- my-shell:>help @@ -27,14 +26,12 @@ Built-In Commands 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 @@ -49,7 +46,6 @@ OPTIONS 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 @@ -58,7 +54,6 @@ 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 @@ -74,7 +69,6 @@ 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. @@ -96,10 +90,10 @@ as a model. |`true` if showing groups is enabled. Otherwise, false. |`groups` -|The commands variables (see <>). +|The commands variables (see xref:commands/builtin/help.adoc#groupcommandinfomodel-variables[GroupCommandInfoModel Variables]). |`commands` -|The commands variables (see <>). +|The commands variables (see xref:commands/builtin/help.adoc#commandinfomodel-variables[CommandInfoModel Variables]). |`hasUnavailableCommands` |`true` if there is unavailable commands. Otherwise, false. @@ -114,7 +108,7 @@ as a model. |The name of a group, if set. Otherwise, empty. |`commands` -|The commands, if set. Otherwise, empty. Type is a multi value, see <>. +|The commands, if set. Otherwise, empty. Type is a multi value, see xref:commands/builtin/help.adoc#commandinfomodel-variables[CommandInfoModel Variables]. |=== [[commandinfomodel-variables]] @@ -135,10 +129,10 @@ as a model. |The description of a command, if set. Otherwise, null. |`parameters` -|The parameters variables, if set. Otherwise empty. Type is a multi value, see <>. +|The parameters variables, if set. Otherwise empty. Type is a multi value, see xref:commands/builtin/help.adoc#commandparameterinfomodel-variables[CommandParameterInfoModel Variables]. |`availability` -|The availability variables (see <>). +|The availability variables (see xref:commands/builtin/help.adoc#commandavailabilityinfomodel-variables[CommandAvailabilityInfoModel Variables]). |=== [[commandparameterinfomodel-variables]] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/history.adoc similarity index 85% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/history.adoc index 0e79d5cf..d3e8210b 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/history.adoc @@ -1,5 +1,6 @@ [[built-in-commands-history]] -==== History += History +:page-section-summary-toc: 1 The `history` command shows the history of commands that has been executed. @@ -11,6 +12,6 @@ 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. +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/modules/ROOT/pages/commands/builtin/index.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/index.adoc new file mode 100644 index 00000000..521eb5ee --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/index.adoc @@ -0,0 +1,11 @@ +[[built-in-commands]] += Built-In Commands +:page-section-summary-toc: 1 + + + + + + + + diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/script.adoc similarity index 89% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/script.adoc index b87416af..2afe28fa 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/script.adoc @@ -1,5 +1,6 @@ [[built-in-commands-script]] -==== Script += Script +:page-section-summary-toc: 1 The `script` command accepts a local file as an argument and replays commands found there, one at a time. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/stacktrace.adoc similarity index 92% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/stacktrace.adoc index ba9684ba..f3183012 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/stacktrace.adoc @@ -1,5 +1,6 @@ [[built-in-commands-stacktrace]] -==== Stacktrace += Stacktrace +:page-section-summary-toc: 1 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. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc b/spring-shell-docs/modules/ROOT/pages/commands/builtin/version.adoc similarity index 97% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/builtin/version.adoc index dc8339e6..6d54e161 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/builtin/version.adoc @@ -1,5 +1,5 @@ [[built-in-commands-version]] -==== 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. @@ -16,21 +16,17 @@ 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`, diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc index e20a51e4..76d28871 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc @@ -1,5 +1,6 @@ [[dynamic-command-exitcode-annotation]] -==== @ExceptionResolver += @ExceptionResolver + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] `@ShellComponent` classes can have `@ExceptionResolver` methods to handle exceptions from component @@ -17,42 +18,35 @@ is used to sort exceptions based on their depth from the thrown exception type. Alternatively, the annotation declaration may narrow the exception types to match, as the following example shows: -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-type-in-annotation] ---- -==== -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-type-in-method] ---- -==== `@ExceptionResolver` can also return `String` which is used as an output to console. You can use `@ExitCode` annotation to define return code. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-exitcode-annotation] ---- -==== `@ExceptionResolver` with `void` return type is automatically handled as handled exception. You can then also define `@ExitCode` and use `Terminal` if you need to write something into console. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void] ---- -==== -===== Method Arguments +[[method-arguments]] +== Method Arguments `@ExceptionResolver` methods support the following arguments: [Attributes] @@ -67,7 +61,8 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void] |=== -===== Return Values +[[return-values]] +== Return Values `@ExceptionResolver` methods support the following return values: [Attributes] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc similarity index 76% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc index 60b7b867..041ba897 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc @@ -1,5 +1,7 @@ [[dynamic-command-exitcode]] -=== Exception Handling += Exception Handling +:page-section-summary-toc: 1 + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Exceptions happen from a user code wether it is intentional or not. This section describes @@ -12,8 +14,5 @@ this mostly relates when a command is run on a non-interactive mode meaning one is always executed once with an instance of a `spring-shell`. Take a note that _exit code_ always relates to non-interactive shell. -include::using-shell-commands-exceptionhandling-resolving.adoc[] -include::using-shell-commands-exceptionhandling-mappings.adoc[] -include::using-shell-commands-exceptionhandling-annotation.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc index 951e9f2b..b83f91fc 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc @@ -1,5 +1,6 @@ [[dynamic-command-exitcode-mappings]] -==== Exit Code Mappings += Exit Code Mappings + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Default behaviour of an exit codes is as: @@ -14,21 +15,17 @@ integrate into that. Assuming there is an exception show below which would be thrown from a command: -==== [source, java, indent=0] ---- include::{snippets}/ExitCodeSnippets.java[tag=my-exception-class] ---- -==== It is possible to define a mapping function between `Throwable` and exit code. You can also just configure a _class_ to _exit code_ which is just a syntactic sugar within configurations. -==== [source, java, indent=0] ---- include::{snippets}/ExitCodeSnippets.java[tag=example1] ---- -==== NOTE: Exit codes cannot be customized with annotation based configuration diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc index eb4998bb..778d96a2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc @@ -1,5 +1,6 @@ [[dynamic-command-exitcode-resolving]] -==== Exception Resolving += Exception Resolving + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Unhandled exceptions will bubble up into shell's `ResultHandlerService` and then eventually @@ -8,30 +9,24 @@ can be used to resolve exceptions and gives you flexibility to return message to into console together with exit code which are wrapped within `CommandHandlingResult`. `CommandHandlingResult` may contain a _message_ and/or _exit code_. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class] ---- -==== `CommandExceptionResolver` implementations can be defined globally as bean. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class-as-bean] ---- -==== or defined per `CommandRegistration` if it's applicable only for a particular command itself. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=example1] ---- -==== NOTE: Resolvers defined with a command are handled before global resolvers. @@ -39,12 +34,10 @@ NOTE: Resolvers defined with a command are handled before global resolvers. Use you own exception types which can also be an instance of boot's `ExitCodeGenerator` if you want to define exit code there. -==== [source, java, indent=0] ---- include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-class] ---- -==== Some build in `CommandExceptionResolver` beans are registered to handle common exceptions thrown from command parsing. These are registered with _order_ diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc b/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc similarity index 97% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc index a3418782..6c686eef 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc @@ -1,5 +1,6 @@ [[commands-helpoptions]] -=== Help Options += Help Options + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] _Spring Shell_ has a build-in `help` command but not all favour getting command help @@ -14,16 +15,13 @@ what other command-line options is typed. Below example shows its default settings. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationHelpOptionsSnippets.java[tag=defaults] ---- -==== It is possible to change default behaviour via configuration options. -==== [source, yaml] ---- spring: @@ -34,7 +32,6 @@ spring: short-names: h command: help ---- -==== NOTE: Commands defined programmationally or via annotations will automatically add help options. With annotation model you can only turn things off globally, programmatic diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc b/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc index f0a75950..7014c8b5 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc @@ -1,5 +1,6 @@ [[commands-hidden]] -=== Hidden Command += Hidden Command + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] It is possible to _hide_ a command which is convenient in cases where it is not yet ready for @@ -17,11 +18,9 @@ from: Below is an example how to define command as _hidden_. It shows available builder methods to define _hidden_ state. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationHiddenSnippets.java[tag=snippet1] ---- -==== NOTE: Defining hidden commands is not supported with annotation based configuration diff --git a/spring-shell-docs/modules/ROOT/pages/commands/index.adoc b/spring-shell-docs/modules/ROOT/pages/commands/index.adoc new file mode 100644 index 00000000..2662bfe8 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/commands/index.adoc @@ -0,0 +1,18 @@ +[[commands]] += Commands +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] + +In this section, we go through an actual command registration and leave command options +and execution for later in a documentation. You can find more detailed info in +xref:appendices/techintro/registration.adoc[Command Registration]. + + + + + + + + + diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc b/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc similarity index 60% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc index fd3d7fd5..baec8007 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc @@ -1,24 +1,22 @@ [[commands-interactionmode]] -=== Interaction Mode -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Interaction Mode +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Command registration can define `InteractionMode` which is used to hide commands -depending which mode shell is executing. More about that in <>. +depending which mode shell is executing. More about that in xref:execution.adoc#using-shell-execution-interactionmode[Interaction Mode]. You can define it with `CommandRegisration`. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet1] ---- -==== Or with `@ShellMethod`. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet2] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc b/spring-shell-docs/modules/ROOT/pages/commands/organize.adoc similarity index 98% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/organize.adoc index 1f4041af..8a275adb 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/organize.adoc @@ -1,5 +1,5 @@ [[organizing-commands]] -=== Organizing Commands += Organizing Commands When your shell starts to provide a lot of functionality, you may end up with a lot of commands, which could be confusing for your users. By typing `help`, @@ -27,7 +27,6 @@ package (unless overridden at the method or class level, as explained earlier). The following listing shows an example: -==== [source,java] ---- public class UserCommands { @@ -51,4 +50,3 @@ public class SomeCommands { public void last() {} } ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/annotation.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/registration/annotation.adoc index e8772b00..3d5e8b66 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/annotation.adoc @@ -1,27 +1,24 @@ [[commands-registration-annotation]] -==== Annotation += Annotation + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] `@Command` annotation when used on a method marks it as a candidate for command registration. In below example a command `example` is defined. -==== [source, java, indent=0] ---- include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-method] ---- -==== `@Command` annotation can be placed on a class which either defines defaults or shared settings for `@Command` methods defined in a same class. In below example a command `parent example` is defined. -==== [source, java, indent=0] ---- include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-class] ---- -==== Using a `@Command` will not automatically register command targets, instead it is required to use `@EnableCommand` and/or `@CommandScan` annotations. This model is familiar from other parts @@ -31,12 +28,10 @@ for command targets. You can define target classes using `@EnableCommand`. It will get picked from all _Configuration_ classes. -==== [source, java, indent=0] ---- include::{snippets}/CommandAnnotationSnippets.java[tag=enablecommand-with-class] ---- -==== You can define target classes using `@CommandScan`. It will get picked from all _Configuration_ classes. @@ -44,9 +39,7 @@ classes. TIP: Define `@CommandScan` in Spring Boot `App` class on a top level and it will automatically scan all command targets from all packages and classes under `App`. -==== [source, java, indent=0] ---- include::{snippets}/CommandAnnotationSnippets.java[tag=commandscan-no-args] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc similarity index 65% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc index b9061076..928ce9f4 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc @@ -1,4 +1,7 @@ -=== Registration +[[registration]] += Registration +:page-section-summary-toc: 1 + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] There are two different ways to define a command: through an annotation model and @@ -8,14 +11,11 @@ In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog). Starting from _3.1.x_ a better support for defining commands using -<> were added. Firstly because eventually standard -package providing <> will get deprecated +xref:commands/registration/annotation.adoc[annotations] were added. Firstly because eventually standard +package providing xref:commands/registration/legacyannotation.adoc[legacy annotations] will get deprecated and removed. Secondly so that we're able to provide same set of features than using underlying `CommandRegistration`. Creating new a annotation model allows us to rethink and modernise that part without breaking existing applications. -include::using-shell-commands-registration-programmatic.adoc[] -include::using-shell-commands-registration-annotation.adoc[] -include::using-shell-commands-registration-legacyannotation.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/legacyannotation.adoc similarity index 96% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/registration/legacyannotation.adoc index cded0907..fe3cf939 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/legacyannotation.adoc @@ -1,5 +1,6 @@ [[commands-registration-legacyannotation]] -==== Legacy Annotation += Legacy Annotation + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] When you use the standard API, methods on beans are turned into executable commands, provided that: @@ -16,16 +17,14 @@ you can use it in addition to the filtering mechanism to declare beans (for exam You can customize the name of the created bean by using the `value` attribute of the annotation. ==== -==== [source, java, indent=0] ---- 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 xref:commands/builtin/help.adoc[Help]). 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. @@ -36,12 +35,10 @@ dashed, gnu-style, names (for example, `sayHello()` becomes `say-hello`). You can, however, explicitly set the command key, by using the `key` attribute of the annotation: -==== [source, java, indent=0] ---- include::{snippets}/AnnotationRegistrationSnippets.java[tag=snippet2] ---- -==== NOTE: The `key` attribute accepts multiple values. If you set multiple keys for a single method, the command is registered with those different aliases. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc b/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc similarity index 91% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc index ad7b8a2a..ac67f8b9 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc @@ -1,16 +1,15 @@ [[commands-registration-programmatic]] -==== Programmatic += Programmatic + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] In the programmatic model, `CommandRegistration` can be defined as a `@Bean` and it will be automatically registered. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationBeanSnippets.java[tag=plain] ---- -==== If all your commands have something in common, an instance of a _CommandRegistration.BuilderSupplier_ is created which can @@ -18,24 +17,20 @@ be autowired. Default implementation of this supplier returns a new builder so you don't need to worry about its internal state. IMPORTANT: Commands registered programmatically automatically -add _help options_ mentioned in <>. +add _help options_ mentioned in xref:commands/helpoptions.adoc[Help Options]. If bean of this supplier type is defined then auto-configuration will back off giving you an option to redefine default functionality. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationBeanSnippets.java[tag=fromsupplier] ---- -==== `CommandRegistrationCustomizer` beans can be defined if you want to centrally modify builder instance given you by supplier mentioned above. -==== [source, java, indent=0] ---- include::{snippets}/CommandRegistrationBeanSnippets.java[tag=customizer] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc b/spring-shell-docs/modules/ROOT/pages/commands/writing.adoc similarity index 95% rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc rename to spring-shell-docs/modules/ROOT/pages/commands/writing.adoc index 7f73f25b..e19ae311 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc +++ b/spring-shell-docs/modules/ROOT/pages/commands/writing.adoc @@ -1,4 +1,6 @@ -=== Writing +[[writing]] += Writing + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] When something needs to get written into your console you can always @@ -10,18 +12,14 @@ If using target endpoints, i.e. _consumer_ which is not expected to return anything given `CommandContext` contains reference to `Terminal` and writer can be accessed from there. -==== [source, java, indent=0] ---- include::{snippets}/WritingSnippets.java[tag=reg-terminal-writer] ---- -==== It's possible to autowire `Terminal` to get access to its writer. -==== [source, java, indent=0] ---- include::{snippets}/WritingSnippets.java[tag=anno-terminal-writer] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc b/spring-shell-docs/modules/ROOT/pages/completion.adoc similarity index 90% rename from spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc rename to spring-shell-docs/modules/ROOT/pages/completion.adoc index d53907c0..e13019c6 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc +++ b/spring-shell-docs/modules/ROOT/pages/completion.adoc @@ -1,4 +1,6 @@ -== Completion +[[completion]] += Completion + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Spring Shell can provide completion proposals for both interactive shell @@ -8,7 +10,8 @@ easier to provide more programmatic ways to provide completion hints. When shell is purely run as a command-line tool a completion can only be accomplished with integration into OS level shell's like _bash_. -=== Interactive +[[interactive]] +== Interactive Hints for completions are calculated with _function_ or _interface_ style methods which takes `CompletionContext` and returns a list of @@ -20,45 +23,38 @@ for all commands and scenarious. For example existing completion implementation `RegistrationOptionsCompletionResolver` handles completions for a option names. -==== [source, java, indent=0] ---- include::{snippets}/CompletionSnippets.java[tag=resolver-1] ---- -==== Option values with builder based command registration can be defined per option. -==== [source, java, indent=0] ---- include::{snippets}/CompletionSnippets.java[tag=builder-1] ---- -==== Option values with annotation based command registration are handled via `ValueProvider` interface which can be defined with `@ShellOption` annotation. -==== [source, java, indent=0] ---- include::{snippets}/CompletionSnippets.java[tag=provider-1] ---- -==== Actual `ValueProvider` with annotation based command needs to be registered as a _Bean_. -==== [source, java, indent=0] ---- include::{snippets}/CompletionSnippets.java[tag=anno-method] ---- -==== -=== Command-Line +[[command-line]] +== Command-Line Command-line completion currently only support _bash_ and is documented -in a built-in `completion` command <>. +in a built-in `completion` command xref:commands/builtin/completion.adoc[Completion]. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc b/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc similarity index 71% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc rename to spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc index 5faf1764..1ddd76dd 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc @@ -1,8 +1,9 @@ [[using-shell-components-flow]] -=== Flow -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Flow -When you use <> to build something that involves +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] + +When you use xref:components/ui/index.adoc[Flow Components] to build something that involves use of a multiple components, your implementation may become a bit cluttered. To ease these use cases, we added a `ComponentFlow` that can hook multiple component executions together @@ -10,28 +11,31 @@ as a "`flow`". The following listings show examples of flows and their output in a shell: -==== [source, java, indent=0] ---- include::{snippets}/FlowComponentSnippets.java[tag=snippet1] ---- -==== -image::images/component-flow-showcase-1.svg[text input] +[asciinema,rows=15] +---- +include::example$component-flow-showcase-1.cast[] +---- Normal execution order of a components is same as defined with a builder. It's possible to conditionally choose where to jump in a flow by using a `next` function and returning target _component id_. If this returned id is aither _null_ or doesn't exist flow is essentially stopped right there. -==== [source, java, indent=0] ---- include::{snippets}/FlowComponentSnippets.java[tag=snippet2] ---- -==== -image::images/component-flow-conditional-1.svg[text input] +[asciinema,rows=11] +---- +include::example$component-flow-conditional-1.cast[] +---- + TIP: The result from running a flow returns `ComponentFlowResult`, which you can use to do further actions. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc b/spring-shell-docs/modules/ROOT/pages/components/index.adoc similarity index 73% rename from spring-shell-docs/src/main/asciidoc/using-shell-components.adoc rename to spring-shell-docs/modules/ROOT/pages/components/index.adoc index 7a31c5df..dcbec06b 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/index.adoc @@ -1,11 +1,10 @@ [[using-shell-components]] -== Components += Components +:page-section-summary-toc: 1 Components are a set of features which are either build-in or something you can re-use or extend for your own needs. Components in question are either built-in _commands_ or UI side components providing higher level features within commands itself. -include::using-shell-components-flow.adoc[] -include::using-shell-components-ui.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/confirmation.adoc similarity index 57% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/confirmation.adoc index 4046895c..452cd4fd 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/confirmation.adoc @@ -1,20 +1,22 @@ [[using-shell-components-ui-confirmation]] -==== Confirmation -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Confirmation + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] The confirmation component asks a user for a simple confirmation. It is essentially a yes-or-no question. -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet5] ---- -==== -The following image shows the typical output from a confirmation component: +The following screencast shows the typical output from a confirmation component: -image::images/component-confirmation-1.svg[text input] +[asciinema,rows=8] +---- +include::example$component-confirmation-1.cast[] +---- The context object is `ConfirmationInputContext`. The following table describes its context variables: @@ -27,5 +29,5 @@ The context object is `ConfirmationInputContext`. The following table describes |The default value -- either `true` or `false`. |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]). |=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/index.adoc similarity index 61% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/index.adoc index a2a08a1f..b9124fb2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/index.adoc @@ -1,5 +1,6 @@ [[using-shell-components-ui]] -=== Flow Components += Flow Components + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Starting from version 2.1.x, a new component model provides an @@ -18,19 +19,12 @@ Built-in components generally follow this logic: . Exit. . Render the final status of a component state. -NOTE: <> gives better interface for defining the flow of +NOTE: xref:components/flow/index.adoc[Flow] gives better interface for defining the flow of components that are better suited for defining interactive command flows. -include::using-shell-components-ui-render.adoc[] -include::using-shell-components-ui-stringinput.adoc[] -include::using-shell-components-ui-pathinput.adoc[] -include::using-shell-components-ui-pathsearch.adoc[] -include::using-shell-components-ui-confirmation.adoc[] -include::using-shell-components-ui-singleselect.adoc[] -include::using-shell-components-ui-multiselect.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/multiselect.adoc similarity index 61% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/multiselect.adoc index b59d9540..ee2cde27 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/multiselect.adoc @@ -1,20 +1,22 @@ [[using-shell-components-ui-multiselect]] -==== Multi Select -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Multi Select + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] The multi select component asks a user to select multiple items from a list. The following listing shows an example: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet7] ---- -==== -The following image shows a typical multi-select component: +The following screencast shows a typical multi-select component: -image::images/component-multi-select-1.svg[text input] +[asciinema,rows=9] +---- +include::example$component-multi-select-1.cast[] +---- The context object is `MultiItemSelectorContext`. The following table describes its context variables: @@ -30,5 +32,5 @@ The context object is `MultiItemSelectorContext`. The following table describes |The visible items, where rows contain maps of name, selected, on-row, and enabled items. |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:components/ui/render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]). |=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/pathinput.adoc similarity index 52% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/pathinput.adoc index 76cb6f23..87f98110 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/pathinput.adoc @@ -1,19 +1,21 @@ [[using-shell-components-ui-pathinput]] -==== Path Input -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Path Input + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] The path input component asks a user for a `Path` and gives additional information about a path itself. -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet4] ---- -==== -The following image shows typical output from a path input component: +The following screencast shows typical output from a path input component: -image::images/component-path-input-1.svg[text input] +[asciinema,rows=6] +---- +include::example$component-path-input-1.cast[] +---- The context object is `PathInputContext`. The following table describes its context variables: @@ -23,5 +25,5 @@ The context object is `PathInputContext`. The following table describes its cont |Key |Description |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]). |=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/pathsearch.adoc similarity index 59% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/pathsearch.adoc index aaf1b9a5..a8a7d764 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/pathsearch.adoc @@ -1,24 +1,26 @@ [[using-shell-components-ui-pathsearch]] -==== Path Search -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Path Search + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] The path search component asks base directory for scan and optional search expression. Results are shown in a single select list where user can pick a path. `PathSearchConfig` can be used to customise component behaviour. -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet9] ---- -==== NOTE: Logic for search is passed as is into algorithms documented -in <>. +in xref:appendices/techintro/searchalgorithm.adoc[Search Algorithms]. -The following image shows typical output from a path search component: +The following screencast shows typical output from a path search component: -image::images/component-path-search-1.svg[text input] +[asciinema,rows=10] +---- +include::example$component-path-search-1.cast[] +---- The context object is `PathSearchContext`. The following table describes its context variables: @@ -31,5 +33,5 @@ The context object is `PathSearchContext`. The following table describes its con |The items available for rendering search results. |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:/components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]). |=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/render.adoc similarity index 98% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/render.adoc index 5b7e2390..8e6ebc97 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/render.adoc @@ -1,5 +1,6 @@ [[using-shell-components-ui-render]] -==== Component Render += Component Render + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] You can implement component rendering in either of two ways: fully @@ -14,21 +15,17 @@ through code then gives you flexibility to do whatever you need. The programmatic way to render is to create a `Function`: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet1] ---- -==== Then you can hook it to a component: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet2] ---- -==== Components have their own context but usually share some functionality from a parent component types. The following tables show those context variables: diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/singleselect.adoc similarity index 69% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/singleselect.adoc index 78aba16e..4c5fb489 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/singleselect.adoc @@ -1,20 +1,22 @@ [[using-shell-components-ui-singleselect]] -==== Single Select -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Single Select + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] A single select component asks a user to choose one item from a list. It is similar to a simple dropbox implementation. The following listing shows an example: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet6] ---- -==== -The following image shows typical output for a single select component: +The following screencast shows typical output for a single select component: -image::images/component-single-select-1.svg[text input] +[asciinema,rows=8] +---- +include::example$component-single-select-1.cast[] +---- The context object is `SingleItemSelectorContext`. The following table describes its context variables: @@ -30,16 +32,14 @@ The context object is `SingleItemSelectorContext`. The following table describes |The visible items, where rows contains maps of name and selected items. |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:/components/ui/render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]). |=== You can pre-select an item by defining it to get exposed. This is useful if you know the default and lets the user merely press `Enter` to make a choice. The following listing sets a default: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet8] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc b/spring-shell-docs/modules/ROOT/pages/components/ui/stringinput.adoc similarity index 66% rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc rename to spring-shell-docs/modules/ROOT/pages/components/ui/stringinput.adoc index b88574a6..96c54f29 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc +++ b/spring-shell-docs/modules/ROOT/pages/components/ui/stringinput.adoc @@ -1,20 +1,22 @@ [[using-shell-components-ui-stringinput]] -==== String Input -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += String Input + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] The string input component asks a user for simple text input, optionally masking values if the content contains something sensitive. The following listing shows an example: -==== [source, java, indent=0] ---- include::{snippets}/UiComponentSnippets.java[tag=snippet3] ---- -==== -The following image shows typical output from a string input component: +The following screencast shows typical output from a string input component: -image::images/component-text-input-1.svg[text input] +[asciinema,rows=6] +---- +include::example$component-text-input-1.cast[] +---- The context object is `StringInputContext`. The following table lists its context variables: @@ -39,5 +41,5 @@ The context object is `StringInputContext`. The following table lists its contex |`true` if a mask character is set. Otherwise, false. |`model` -|The parent context variables (see <>). +|The parent context variables (see xref:/components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]). |=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc b/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc similarity index 94% rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc rename to spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc index 5a76a99c..a3ed12f8 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/commandnotfound.adoc @@ -1,44 +1,37 @@ [[using-shell-customization-commandnotfound]] -=== Command Not Found += Command Not Found + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] On default a missing command is handled via `CommandNotFoundResultHandler` and outputs a simple message: -==== [source, text] ---- shell:>missing No command found for 'missing' ---- -==== Internally `CommandNotFoundResultHandler` is using `CommandNotFoundMessageProvider` which is a simple function taking a `ProviderContext` and returning a text message. Below is an example what a custom message provider might look like. -==== [source, java, indent=0] ---- include::{snippets}/CommandNotFoundSnippets.java[tag=custom-provider] ---- -==== It's possible to change this implementation by defining it as a bean. -==== [source, java, indent=0] ---- include::{snippets}/CommandNotFoundSnippets.java[tag=provider-bean-1] ---- -==== `CommandNotFoundResultHandler` is a functional interface so it can be writter as a lambda. -==== [source, java, indent=0] ---- include::{snippets}/CommandNotFoundSnippets.java[tag=provider-bean-2] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-contextclose.adoc b/spring-shell-docs/modules/ROOT/pages/customization/contextclose.adoc similarity index 85% rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-contextclose.adoc rename to spring-shell-docs/modules/ROOT/pages/customization/contextclose.adoc index a302b066..609a7d65 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-contextclose.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/contextclose.adoc @@ -1,5 +1,8 @@ [[using-shell-customization-contextclose]] -=== Context Close += Context Close +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] Command execution logic happens via Spring Boot's `ApplicationRunner` beans. Normally Spring `ApplicationContext` closes automatically after these runner @@ -20,4 +23,3 @@ spring: ---- NOTE: This setting is not enabled by default. - diff --git a/spring-shell-docs/modules/ROOT/pages/customization/index.adoc b/spring-shell-docs/modules/ROOT/pages/customization/index.adoc new file mode 100644 index 00000000..41408675 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/customization/index.adoc @@ -0,0 +1,9 @@ +[[using-shell-customization]] += Customization +:page-section-summary-toc: 1 + +This section describes how you can customize the shell. + + + + diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc b/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc similarity index 95% rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc rename to spring-shell-docs/modules/ROOT/pages/customization/logging.adoc index 693d732b..ab331829 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/logging.adoc @@ -1,5 +1,5 @@ [[using-shell-customization-logging]] -=== Logging += Logging On default a _Spring Boot_ application will log messages into a console which at minimum is annoying and may also mix output from a shell commands. @@ -7,29 +7,24 @@ Fortunately there is a simple way to instruct logging changes via boot propertie Completely silence console logging by defining its pattern as an empty value. -==== [source, yaml] ---- logging: pattern: console: ---- -==== If you need log from a shell then write those into a file. -==== [source, yaml] ---- logging: file: name: shell.log ---- -==== If you need different log levels. -==== [source, yaml] ---- logging: @@ -38,18 +33,15 @@ logging: springframework: shell: debug ---- -==== Passing contiguration properties as command line options is not supported but you can use any other ways supported by boot, for example. -==== [source, bash] ---- $ java -Dlogging.level.root=debug -jar demo.jar $ LOGGING_LEVEL_ROOT=debug java -jar demo.jar ---- -==== NOTE: In a GraalVM image settings are locked during compilation which means you can't change log levels at runtime. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc b/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc similarity index 93% rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc rename to spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc index 19233207..93cfe85d 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/singlecommand.adoc @@ -1,5 +1,7 @@ [[using-shell-customization-singlecommand]] -=== Single Command += Single Command +:page-section-summary-toc: 1 + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] If your shell application is made for exactly a single purpose having only one @@ -8,7 +10,6 @@ command it may be beneficial to configure it for this. Property runners than `NonInteractiveShellRunner` and configures it to use defined _Primary Command_. -==== [source, yaml] ---- spring: @@ -16,7 +17,6 @@ spring: noninteractive: primary-command: mycommand ---- -==== For example if you have a command `mycommand` with option `arg` it had to be executed with ` mycommand --arg hi`, but with above diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc b/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc similarity index 89% rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc rename to spring-shell-docs/modules/ROOT/pages/customization/styling.adoc index 109774ed..242f3964 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc +++ b/spring-shell-docs/modules/ROOT/pages/customization/styling.adoc @@ -1,6 +1,7 @@ [[theming]] -=== Theming -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Theming + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Current terminal implementations are rich in features and can usually show something else that just plain text. For example a text can be styled to be @@ -12,7 +13,7 @@ Spring Shell supports these via it's theming framework which contains two parts, firstly _styling_ can be used to change text type and secondly _figures_ how some characters are shown. These two are then combined together as a _theme_. -More about _theming_ internals, see <>. +More about _theming_ internals, see xref:appendices/techintro/theming.adoc[Theming]. NOTE: Default theme is named `default` but can be change using property `spring.shell.theme.name`. Other built-in theme named `dump` uses @@ -20,49 +21,39 @@ no styling for colors and tries to not use any special figures. Modify existing style by overriding settings. -==== [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-style-class] ---- -==== Modify existing figures by overriding settings. -==== [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-figure-class] ---- -==== To create a new theme, create a `ThemeSettings` and provide your own _style_ and _figure_ implementations. -==== [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-theme-class] ---- -==== Register a new bean `Theme` where you can return your custom `ThemeSettings` and a _theme_ name. -==== [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=custom-theme-config] ---- -==== You can use `ThemeResolver` to resolve _styles_ if you want to create JLine-styled strings programmatically and _figures_ if you want to theme characters for being more pretty. -==== [source, java, indent=0] ---- include::{snippets}/ThemingSnippets.java[tag=using-theme-resolver] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc b/spring-shell-docs/modules/ROOT/pages/execution.adoc similarity index 93% rename from spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc rename to spring-shell-docs/modules/ROOT/pages/execution.adoc index d99e856c..75c90293 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc +++ b/spring-shell-docs/modules/ROOT/pages/execution.adoc @@ -1,11 +1,12 @@ [[using-shell-execution]] -== Execution += Execution + ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] This section describes how to set up a Spring Shell to work in interactive mode. [[using-shell-execution-interactionmode]] -=== Interaction Mode +== Interaction Mode Version 2.1.x introduced built-in support to distinguish between interactive and non-interactive modes. This makes it easier to use the shell as a @@ -13,7 +14,7 @@ simple command-line tool without requiring customization. Currently, interactive mode is entered if any command line options are passed when starting or running a shell from a command line. This works especially well when a shell application -is compiled with <>. +is compiled with xref:building.adoc#native[Native Support]. Some commands may not have any useful meanings when they run in interactive mode or (conversely) in non-interactive mode. For example, a built-in `exit` command would @@ -23,7 +24,7 @@ The `@ShellMethod` annotation has a field called `interactionMode` that you can shell about when a particular command is available. [[using-shell-execution-shellrunner]] -=== Shell Runners +== Shell Runners `ShellApplicationRunner` is a main interface where Boot's `ApplicationArguments` are passed and its default implementation makes a choice which `ShellRunner` is used. There can be diff --git a/spring-shell-docs/src/main/asciidoc/getting-started.adoc b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc similarity index 92% rename from spring-shell-docs/src/main/asciidoc/getting-started.adoc rename to spring-shell-docs/modules/ROOT/pages/getting-started.adoc index 7379c618..f4b7bc01 100644 --- a/spring-shell-docs/src/main/asciidoc/getting-started.adoc +++ b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc @@ -1,11 +1,14 @@ -== Getting Started +[[getting-started]] += Getting Started + To see what Spring Shell has to offer, we can write a trivial _hello world_ shell application that has a simple argument. IMPORTANT: _Spring Shell_ is based on _Spring Boot_ {spring-boot-version} and _Spring Framework_ {spring-version} and thus requires _JDK 17_. -=== Creating a Project +[[creating-a-project]] +== Creating a Project For the purpose of this tutorial, we create a simple Spring Boot application by using https://start.spring.io where you can choose _Spring Shell_ dependency. @@ -16,7 +19,6 @@ NOTE: _Spring Shell_ version on `start.spring.io` is usually latest release. With _maven_ you're expected to have something like: -==== [source, xml, subs=attributes+] ---- @@ -46,11 +48,9 @@ With _maven_ you're expected to have something like: ---- -==== With _gradle_ you're expected to have something like: -==== [source, groovy, subs=attributes+] ---- dependencies { @@ -65,7 +65,6 @@ dependencyManagement { } } ---- -==== CAUTION: Given that Spring Shell starts the REPL (Read-Eval-Print-Loop) because this dependency is present, you need to either skip tests when you build (`-DskipTests`) @@ -76,27 +75,23 @@ the eval loop or crashes with a NPE. Once compiled it can be run either in interactive mode: -==== [source, text, subs=attributes+] ---- -include::code/getting-started-run-interactive.out[] +include::example$getting-started-run-interactive.out[] ---- -==== Or in non-interactive mode: -==== [source, text, subs=attributes+] ---- -include::code/getting-started-run-noninteractive.out[] +include::example$getting-started-run-noninteractive.out[] ---- -==== -TIP: Check out <> making logging to work +TIP: Check out xref:/customization/logging.adoc[Logging] making logging to work better with shell apps. [[using-spring-shell-your-first-command]] -=== Your First Command +== Your First Command Now we can add our first command. To do so, create a new class (named whatever you want) and annotate it with `@ShellComponent` which is a variation of `@Component` that is used to restrict @@ -107,7 +102,6 @@ returns it with "Hello world". Add `@ShellMethod` and optionally change command using `key` parameter. You can use `@ShellOption` to define argument default value if it's not given when running a command. -==== [source, java] ---- package com.example.demo; @@ -127,21 +121,17 @@ public class MyCommands { } } ---- -==== New _hello-world_ command becomes visible to _help_: -==== [source, text] ---- My Commands hello-world: ---- -==== And you can run it: -==== [source, text] ---- shell:>hello-world @@ -150,6 +140,5 @@ Hello world spring shell:>hello-world --arg boot Hello world boot ---- -==== The rest of this document delves deeper into the whole Spring Shell programming model. diff --git a/spring-shell-docs/modules/ROOT/pages/index.adoc b/spring-shell-docs/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..2d44d57f --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,18 @@ += Spring Shell +Eric Bottard; Janne Valkealahti; Jay Bryant; Corneil du Plessis +:page-section-summary-toc: 1 + +**{project-version}** + +Not all applications need a fancy web user interface. Sometimes, interacting with an application through an interactive terminal is the most appropriate way to get things done. + +Spring Shell lets you create such a runnable application, where the user enters textual commands that are run until the program terminates. The Spring Shell project provides the infrastructure to create such a REPL (Read, Eval, Print Loop) application, letting you concentrate on implementing commands by using the familiar Spring programming model. + +Spring Shell includes advanced features (such as parsing, tab completion, colorization of output, fancy ASCII-art table display, input conversion, and validation), freeing you to focus on core command logic. + +(C) 2017 - 2023 VMware, Inc. + +_Copies of this document may be made for your own use and for distribution to +others, provided that you do not charge any fee for such copies and further +provided that each copy contains this Copyright Notice, whether distributed in +print or electronically._ \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc b/spring-shell-docs/modules/ROOT/pages/options/arity.adoc similarity index 89% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc rename to spring-shell-docs/modules/ROOT/pages/options/arity.adoc index 53c2dc18..87e76828 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/arity.adoc @@ -1,6 +1,7 @@ [[using-shell-options-arity]] -=== Arity -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Arity + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Arity defines how many parameters option parsing takes. @@ -8,23 +9,29 @@ NOTE: There are limitations in a `legacy annotation` compared to `annotation` and `programmatic` use of arity settings. These are mentioned in notes in below samples. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-legacyannotation] ---- +====== [[using-shell-options-arity-optionarity-table]] .OptionArity @@ -50,30 +57,35 @@ include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-legacy NOTE: `legacy annotation` doesn't support defining minimum arity. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-legacyannotation] ---- +====== In below example we have option _arg1_ and it's defined as type _String[]_. Arity defines that it needs at least 1 parameter and not more that 2. As seen in below spesific exceptions _TooManyArgumentsOptionException_ and _NotEnoughArgumentsOptionException_ are thrown to indicate arity mismatch. -==== [source, bash] ---- shell:>e2e reg arity-errors --arg1 @@ -88,4 +100,3 @@ Hello [one, two] shell:>e2e reg arity-errors --arg1 one two three Too many arguments --arg1 requires at most 2. ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/options/basics/annotation.adoc similarity index 66% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc rename to spring-shell-docs/modules/ROOT/pages/options/basics/annotation.adoc index 227217f5..d4402d6b 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/basics/annotation.adoc @@ -1,13 +1,13 @@ [[using-shell-options-basics-annotation]] -==== Annotation -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Annotation +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] `Option` annotation can be used to define an option name if you don't want it to be same as argument name. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation] ---- -==== diff --git a/spring-shell-docs/modules/ROOT/pages/options/basics/index.adoc b/spring-shell-docs/modules/ROOT/pages/options/basics/index.adoc new file mode 100644 index 00000000..2c1bb3f8 --- /dev/null +++ b/spring-shell-docs/modules/ROOT/pages/options/basics/index.adoc @@ -0,0 +1,12 @@ +[[using-shell-options-basics]] += Basics +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] + +This section gives a generic idea how an option can be defined. Following +sections, beyond basics, discuss more about how various option behaviour +can be accomplished for a particular use case. + + + diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc b/spring-shell-docs/modules/ROOT/pages/options/basics/legacyannotation.adoc similarity index 84% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc rename to spring-shell-docs/modules/ROOT/pages/options/basics/legacyannotation.adoc index 3558bc84..d8edfab2 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/basics/legacyannotation.adoc @@ -1,33 +1,28 @@ [[using-shell-options-basics-legacyannotation]] -==== Legacy Annotation -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Legacy Annotation + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] Having a target method with argument is automatically registered with a matching argument name. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-without-annotation] ---- -==== `@ShellOption` annotation can be used to define an option name if you don't want it to be same as argument name. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-with-annotation] ---- -==== If option name is defined without prefix, either `-` or `--`, it is discovered from _ShellMethod#prefix_. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-with-annotation-without-prefix] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc b/spring-shell-docs/modules/ROOT/pages/options/basics/programmatic.adoc similarity index 77% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc rename to spring-shell-docs/modules/ROOT/pages/options/basics/programmatic.adoc index 2f7e93ba..58cfabe6 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/basics/programmatic.adoc @@ -1,17 +1,17 @@ [[using-shell-options-basics-registration]] [[using-shell-options-basics-programmatic]] -==== Programmatic -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Programmatic +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs] Programmatic way with `CommandRegistration` is to use `withOption` to define an option. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-longarg] ---- -==== `CommandRegistration` can be defined as a bean or manually registered with a `CommandCatalog`. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc b/spring-shell-docs/modules/ROOT/pages/options/default.adoc similarity index 68% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc rename to spring-shell-docs/modules/ROOT/pages/options/default.adoc index 0bb54ef8..6d48870c 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/default.adoc @@ -1,26 +1,33 @@ [[using-shell-options-default]] -=== Default Value -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Default Value + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Having a default value for an option is somewhat related to -<>, as there are cases where you +xref:options/optional.adoc[Optional Value], as there are cases where you may want to know if the user defined an option and change behavior based on a default value: +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-default-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-default-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-default-legacyannotation] ---- +====== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/modules/ROOT/pages/options/index.adoc similarity index 58% rename from spring-shell-docs/src/main/asciidoc/using-shell-options.adoc rename to spring-shell-docs/modules/ROOT/pages/options/index.adoc index 09b9289b..bcae7dc4 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/index.adoc @@ -1,6 +1,7 @@ [[using-shell-options]] -== Options -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Options + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Command line arguments can be separated into options and positional parameters. Following sections describes features how options are defined and used. We first @@ -17,22 +18,12 @@ arguments or with programmatically using `CommandRegistration`. NOTE: In below sections `@ShellOption` refer to a _legacy annotation model_ and `@Option` refer to an _annotation model_. -include::using-shell-options-basics.adoc[] -include::using-shell-options-short.adoc[] -include::using-shell-options-arity.adoc[] -include::using-shell-options-positional.adoc[] -include::using-shell-options-optional.adoc[] -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[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc b/spring-shell-docs/modules/ROOT/pages/options/label.adoc similarity index 84% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc rename to spring-shell-docs/modules/ROOT/pages/options/label.adoc index c2f8ccc5..f9f89f2a 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/label.adoc @@ -1,6 +1,7 @@ [[using-shell-options-label]] -=== Label -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Label + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] _Option Label_ has no functional behaviour within a shell itself other than what a default `help` command outputs. Within a command documentation @@ -9,20 +10,24 @@ you may want to give better descriptive word for an option. NOTE: Label is not supported with `legacy annotation`. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-label-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-label-annotation] ---- +====== Defining label is then shown in `help`. -==== [source, bash] ---- my-shell:>help labelOption @@ -37,4 +42,3 @@ OPTIONS [Optional] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc b/spring-shell-docs/modules/ROOT/pages/options/naming.adoc similarity index 94% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc rename to spring-shell-docs/modules/ROOT/pages/options/naming.adoc index ba9c9c50..4d07542f 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/naming.adoc @@ -1,6 +1,7 @@ [[using-shell-options-naming]] -=== Naming -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Naming + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] If there is a need to modify option long names that can be done using `OptionNameModifier` interface which is a simple @@ -15,22 +16,18 @@ on default. You can define one with an option in `CommandRegistration`. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-req] ---- -==== Add one _singleton bean_ as type `OptionNameModifier` and that becomes a global default. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-bean] ---- -==== It's also possible to just add configuration property with `spring.shell.option.naming.case-type` which auto-configures @@ -45,7 +42,6 @@ default via configuration properies only work if using pre-configured `Builder` instance. See more <>. -==== [source, yaml] ---- spring: @@ -58,21 +54,17 @@ spring: # case-type: kebab # case-type: pascal ---- -==== For example options defined in an annotated method like this. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-sample1] ---- -==== On default `help` for that command shows names coming directly from `@ShellOption`. -==== [source, bash] ---- OPTIONS @@ -88,12 +80,10 @@ OPTIONS --FromPascal String [Mandatory] ---- -==== Define `spring.shell.option.naming.case-type=kebab` and default modifier is added and option names then look like. -==== [source, bash] ---- OPTIONS @@ -110,4 +100,3 @@ OPTIONS [Mandatory] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc b/spring-shell-docs/modules/ROOT/pages/options/optional.adoc similarity index 78% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc rename to spring-shell-docs/modules/ROOT/pages/options/optional.adoc index e8bc088f..60dfbe35 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/optional.adoc @@ -1,46 +1,59 @@ [[using-shell-options-optional]] -=== Optional Value -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Optional Value + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] An option is either required or not and, generally speaking, how it behaves depends on a command target. Making option optional. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-optional-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-optional-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-optional-legacyannotation] ---- +====== Making option mandatory. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/OptionSnippets.java[tag=option-mandatory-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-mandatory-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/OptionSnippets.java[tag=option-mandatory-legacyannotation] ---- +====== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc b/spring-shell-docs/modules/ROOT/pages/options/positional.adoc similarity index 91% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc rename to spring-shell-docs/modules/ROOT/pages/options/positional.adoc index b54563cd..e35e845c 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/positional.adoc @@ -1,15 +1,14 @@ [[using-shell-options-positional]] -=== Positional -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Positional + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Positional information is mostly related to a command target method: -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-positional] ---- -==== NOTE: Be careful with positional parameters as it may soon become confusing which options those are mapped to. @@ -26,36 +25,29 @@ ambiguous arguments. Let's look what happens when we don't define a position. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-noposition] ---- -==== Option _arg1_ is required and there is no info what to do with argument `one` resulting error for missing option. -==== [source, bash] ---- shell:>arity-strings-1 one Missing mandatory option --arg1. ---- -==== Now let's define a position `0`. -==== [source, java, indent=0] ---- include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-position] ---- -==== Arguments are processed until we get up to 2 arguments. -==== [source, bash] ---- shell:>arity-strings-2 one @@ -67,4 +59,3 @@ Hello [one, two] shell:>arity-strings-2 one two three Hello [one, two] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc b/spring-shell-docs/modules/ROOT/pages/options/short.adoc similarity index 82% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc rename to spring-shell-docs/modules/ROOT/pages/options/short.adoc index 74fce393..11b87096 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/short.adoc @@ -1,46 +1,59 @@ [[using-shell-options-short]] -=== Short Format -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Short Format + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Short style _POSIX_ option is usually just a synonym to long format. As shown below option `--arg` is equal to `-a`. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-legacyannotation] ---- +====== Short option with combined format is powerful if type is defined as a flag which means type is a _boolean_. That way you can define a presence of a flags as `-abc`, `-abc true` or `-abc false`. +[tabs] +====== +Programmatic:: ++ [source,java,indent=0,role="primary"] -.Programmatic ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-programmatic] ---- +Annotation:: ++ [source,java,indent=0,role="secondary"] -.Annotation ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-annotation] ---- +Legacy Annotation:: ++ [source,java,indent=0,role="secondary"] -.Legacy Annotation ---- include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-legacyannotation] ---- +====== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc b/spring-shell-docs/modules/ROOT/pages/options/types.adoc similarity index 90% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc rename to spring-shell-docs/modules/ROOT/pages/options/types.adoc index fac265bb..3f46ca19 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/types.adoc @@ -1,45 +1,41 @@ [[using-shell-options-types]] -=== Types -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Types + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] This section talks about how particular data type is used as an option value. -==== String +[[string]] +== 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 +[[boolean]] +== 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 @@ -51,16 +47,12 @@ 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 @@ -72,66 +64,54 @@ 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 +[[number]] +== 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 +[[enum]] +== 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 +[[array]] +== 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] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc b/spring-shell-docs/modules/ROOT/pages/options/validation.adoc similarity index 95% rename from spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc rename to spring-shell-docs/modules/ROOT/pages/options/validation.adoc index 9676a814..7f786225 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/options/validation.adoc @@ -1,5 +1,5 @@ [[validating-command-arguments]] -=== Validation += Validation Spring Shell integrates with the https://beanvalidation.org/[Bean Validation API] to support automatic and self-documenting constraints on command parameters. @@ -7,7 +7,6 @@ automatic and self-documenting constraints on command parameters. Annotations found on command parameters and annotations at the method level are honored and trigger validation prior to the command executing. Consider the following command: -==== [source, java] ---- @ShellMethod("Change password.") @@ -15,14 +14,11 @@ honored and trigger validation prior to the command executing. Consider the foll return "Password successfully set to " + password; } ---- -==== From the preceding example, you get the following behavior for free: -==== ---- shell:>change-password hello The following constraints were not met: --password string : size must be between 8 and 40 (You passed 'hello') ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc b/spring-shell-docs/modules/ROOT/pages/testing/basics.adoc similarity index 84% rename from spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc rename to spring-shell-docs/modules/ROOT/pages/testing/basics.adoc index d572aee1..78998b58 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc +++ b/spring-shell-docs/modules/ROOT/pages/testing/basics.adoc @@ -1,6 +1,7 @@ [[using-shell-testing-basics]] -=== Basics -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Basics + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Spring Shell provides a number of utilities and annotations to help when testing your application. Test support is provided by two modules: `spring-shell-test` contains core items, and @@ -8,18 +9,14 @@ Test support is provided by two modules: `spring-shell-test` contains core items To test _interactive_ commands. -==== [source, java, indent=0] ---- include::{snippets}/TestingSnippets.java[tag=testing-shelltest-interactive] ---- -==== To test _non-interactive_ commands. -==== [source, java, indent=0] ---- include::{snippets}/TestingSnippets.java[tag=testing-shelltest-noninteractive] ---- -==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc b/spring-shell-docs/modules/ROOT/pages/testing/index.adoc similarity index 76% rename from spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc rename to spring-shell-docs/modules/ROOT/pages/testing/index.adoc index b2e5e3fb..9f9bd7ff 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc +++ b/spring-shell-docs/modules/ROOT/pages/testing/index.adoc @@ -1,6 +1,8 @@ [[using-shell-testing]] -== Testing -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Testing +:page-section-summary-toc: 1 + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Testing cli application is difficult due to various reasons: @@ -15,6 +17,4 @@ Testing cli application is difficult due to various reasons: NOTE: Testing support is currently under development and will be unstable for various parts. -include::using-shell-testing-basics.adoc[] -include::using-shell-testing-settings.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc b/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc similarity index 86% rename from spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc rename to spring-shell-docs/modules/ROOT/pages/testing/settings.adoc index 851a0c5e..ae6e37c0 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc +++ b/spring-shell-docs/modules/ROOT/pages/testing/settings.adoc @@ -1,6 +1,7 @@ [[using-shell-testing-settings]] -=== Settings -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] += Settings + +ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs] Built in emulation uses terminal width 80 and height 24 on default. Changing dimensions is useful if output would span into multiple @@ -9,19 +10,15 @@ lines and you don't want to handle those cases in a tests. These can be changed using properties `spring.shell.test.terminal-width` or `spring.shell.test.terminal-height`. -==== [source, java, indent=0] ---- include::{snippets}/TestingSnippets.java[tag=testing-shelltest-dimensions-props] ---- -==== `ShellTest` annotation have fields `terminalWidth` and `terminalHeight` which can also be used to change dimensions. -==== [source, java, indent=0] ---- include::{snippets}/TestingSnippets.java[tag=testing-shelltest-dimensions-field] ---- -==== diff --git a/spring-shell-docs/readme.txt b/spring-shell-docs/readme.txt deleted file mode 100644 index 166e979a..00000000 --- a/spring-shell-docs/readme.txt +++ /dev/null @@ -1,35 +0,0 @@ -Some info how screen recordings were made - -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-text-input-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-path-input-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-path-search-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-confirmation-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-single-select-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-multi-select-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-flow-showcase-1.cast -asciinema rec spring-shell-docs/src/main/asciidoc/asciinema/component-flow-conditional-1.cast - -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-text-input-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-text-input-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-path-input-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-path-input-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-path-search-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-path-search-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-confirmation-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-confirmation-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-single-select-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-single-select-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-multi-select-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-multi-select-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-flow-showcase-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-flow-showcase-1.svg -svg-term \ - --in spring-shell-docs/src/main/asciidoc/asciinema/component-flow-conditional-1.cast \ - --out spring-shell-docs/src/main/asciidoc/images/component-flow-conditional-1.svg diff --git a/spring-shell-docs/spring-shell-docs.gradle b/spring-shell-docs/spring-shell-docs.gradle index 74c54b9d..4330c41b 100644 --- a/spring-shell-docs/spring-shell-docs.gradle +++ b/spring-shell-docs/spring-shell-docs.gradle @@ -1,5 +1,7 @@ plugins { id 'org.springframework.shell.docs' + id 'org.antora' version '1.0.0' + id 'io.spring.antora.generate-antora-yml' version '0.0.1' } description = 'Spring Shell Documentation' @@ -8,10 +10,41 @@ dependencies { management platform(project(":spring-shell-management")) implementation project(':spring-shell-starters:spring-shell-starter') implementation project(':spring-shell-starters:spring-shell-starter-test') + implementation project(':spring-shell-samples') testImplementation 'org.springframework.boot:spring-boot-starter-test' testImplementation 'org.awaitility:awaitility' } -asciidoctorj { - version = '2.5.4' +node { + version = '16.15.0' +} + +antora { + version = '3.2.0-alpha.2' + options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true] + dependencies = [ + '@antora/atlas-extension': '1.0.0-alpha.1', + '@antora/collector-extension': '1.0.0-alpha.3', + '@asciidoctor/tabs': '1.0.0-beta.3', + '@springio/antora-extensions': '1.8.1', + '@springio/asciidoctor-extensions': '1.0.0-alpha.8', + ] +} + +tasks.named("generateAntoraYml") { + asciidocAttributes = project.provider( { + def dependencies = resolvedVersions(project.configurations.testRuntimeClasspath) + return ['project-version' : project.version, + 'spring-boot-version' : dependencies['spring-boot-starter-version'], + 'spring-version': dependencies['spring-core-version'] + ] + } ) +} + + + +def resolvedVersions(Configuration configuration) { + return configuration.resolvedConfiguration + .resolvedArtifacts + .collectEntries { [(it.name + '-version'): it.moduleVersion.id.version] } } diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc deleted file mode 100644 index 22fe4c02..00000000 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc +++ /dev/null @@ -1,3 +0,0 @@ -=== Command Execution -When command parsing has done its job and command registration has been resolved, command execution -does the hard work of running the code. diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc deleted file mode 100644 index cf835df2..00000000 --- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[appendix] -[#appendix-tech-intro] -== Techical Introduction -This appendix contains information for developers and others who would like to know more about how Spring Shell -works internally and what its design decisions are. - -include::appendices-techical-intro-registration.adoc[] - -include::appendices-techical-intro-parser.adoc[] - -include::appendices-techical-intro-execution.adoc[] - -include::appendices-techical-intro-commandcontext.adoc[] - -include::appendices-techical-intro-commandcatalog.adoc[] - -include::appendices-techical-intro-theming.adoc[] - -include::appendices-techical-intro-searchalgorithm.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/appendices.adoc b/spring-shell-docs/src/main/asciidoc/appendices.adoc deleted file mode 100644 index 10911ecc..00000000 --- a/spring-shell-docs/src/main/asciidoc/appendices.adoc +++ /dev/null @@ -1,3 +0,0 @@ -include::appendices-techical-intro.adoc[] - -include::appendices-debugging.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/images/component-confirmation-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-confirmation-1.svg deleted file mode 100644 index 32bd94cf..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-confirmation-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>componentmy-shell:>componentconfirmation?Entervalue(Y/n)?EntervaluetrueGotvaluetrue?EntervaluefalseGotvaluefalsemy-shell:>cmy-shell:>comy-shell:>commy-shell:>compmy-shell:>compomy-shell:>componmy-shell:>componemy-shell:>componenmy-shell:>componentcmy-shell:>componentcomy-shell:>componentconmy-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-flow-conditional-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-flow-conditional-1.svg deleted file mode 100644 index 9cf2e97d..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-flow-conditional-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>flowmy-shell:>flowconditional?Single1[Usearrowstomove],typetofilter>Field1Field2?Single1field1?Field1defaultField1Value?Single1field2?Field2defaultField2Valueorg.jline.reader.EndOfFileExceptionDetailsoftheerrorhavebeenomitted.Youcanusethestacktracecommandtoprintthefullstacktrace.my-shell:>fmy-shell:>flmy-shell:>flomy-shell:>flowcmy-shell:>flowcomy-shell:>flowcon?Field1[DefaultdefaultField1Value]Field1>Field2?Field2[DefaultdefaultField2Value] \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-flow-showcase-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-flow-showcase-1.svg deleted file mode 100644 index 23363bb4..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-flow-showcase-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>flowshowcase?Field1defaultField1Value?Field2hi?Confirmation1true>Pathok?Path1path?Single1[Usearrowstomove],typetofilter?Single1value2?Multi1[Usearrowstomove],typetofilter[]key2[]key3[x]key1>[]key2?Multi1value1?Field1[DefaultdefaultField1Value]?Field2?Field2h?Field2hi?Confirmation1(Y/n)?Path1?Path1p?Path1pa?Path1pat?Path1path>key1key2key1>key2>[]key1>[x]key1>[x]key2 \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-multi-select-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-multi-select-1.svg deleted file mode 100644 index a9928f51..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-multi-select-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>componentmy-shell:>componentmulti?testSimple[Usearrowstomove],typetofilter>[]key1[]key2[]key3?testSimple[Usearrowstomove],filtering'k'?testSimple[Usearrowstomove],filtering'ke'?testSimple[Usearrowstomove],filtering'key'[x]key1>[]key2>[]key3>[x]key3?testSimplevalue1Gotvaluevalue1my-shell:>cmy-shell:>comy-shell:>commy-shell:>compmy-shell:>compomy-shell:>componmy-shell:>componemy-shell:>componenmy-shell:>componentmmy-shell:>componentmu?testSimple[Usearrowstomove],filtering'key1'>[x]key1my-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-path-input-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-path-input-1.svg deleted file mode 100644 index 54f76402..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-path-input-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>componentmy-shell:>componentpath>>>Directoryexists>Pathok?Entervalue/tmp/demoGotvalue/tmp/demomy-shell:>cmy-shell:>comy-shell:>commy-shell:>compmy-shell:>compomy-shell:>componmy-shell:>componemy-shell:>componenmy-shell:>componentpmy-shell:>componentpamy-shell:>componentpat?Entervalue?Entervalue/?Entervalue/t?Entervalue/tm?Entervalue/tmp?Entervalue/tmp/?Entervalue/tmp/d?Entervalue/tmp/de?Entervalue/tmp/dem?Entervalue/tmp/demomy-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-path-search-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-path-search-1.svg deleted file mode 100644 index 498b5be1..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-path-search-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/build/libs/spring-shell-samples.jarmy-shell:>my-shell:>componentpathsearch?Entervalue.ℹType'<path><pattern>'tosearch,20/27❯buildSrc/srcbuildSrc/src/mainbuildSrc/build.gradlebuildSrc/src/main/javabuildSrc/src/main/java/orgℹType'<path><pattern>'tosearch,19/27?Entervalue.gradle❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/SamplePlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/ModulePlugin.java?EntervaluebuildSrc/src/main/java/org/springframework/shell/gradleGotvaluebuildSrc/src/main/java/org/springframework/shell/gradle?EntervalueℹType'<path><pattern>'tosearch?Entervalue.g❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/ModulePlugin.java?Entervalue.gr❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/SamplePlugin.java?Entervalue.gra❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/RootPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/ModulePlugin.java?Entervalue.grad❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/ModulePlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/SamplePlugin.java?Entervalue.gradl❯buildSrc/src/main/java/org/springframework/shell/gradlebuildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/DocsPlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/SamplePlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle/ModulePlugin.javabuildSrc/src/main/java/org/springframework/shell/gradle❯buildSrc/src/main/java/org/springframework/shell/gradle/BomPlugin.javamy-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-single-select-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-single-select-1.svg deleted file mode 100644 index 42f46112..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-single-select-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>componentmy-shell:>componentsingle?testSimple[Usearrowstomove],typetofilter>key1key2key1>key2?testSimple[Usearrowstomove],filtering'k'?testSimple[Usearrowstomove],filtering'ke'?testSimple[Usearrowstomove],filtering'key'?testSimplevalue2Gotvaluevalue2my-shell:>cmy-shell:>comy-shell:>commy-shell:>compmy-shell:>compomy-shell:>componmy-shell:>componemy-shell:>componenmy-shell:>componentsmy-shell:>componentsimy-shell:>componentsin?testSimple[Usearrowstomove],filtering'key1'my-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/images/component-text-input-1.svg b/spring-shell-docs/src/main/asciidoc/images/component-text-input-1.svg deleted file mode 100644 index 9f01dd37..00000000 --- a/spring-shell-docs/src/main/asciidoc/images/component-text-input-1.svg +++ /dev/null @@ -1 +0,0 @@ -java-jarspring-shell-samples/target/spring-shell-samples-2.1.0-SNAPSHOT.jarmy-shell:>my-shell:>componentmy-shell:>componentstring?EntervaluehiGotvaluehimy-shell:>cmy-shell:>comy-shell:>commy-shell:>compmy-shell:>compomy-shell:>componmy-shell:>componemy-shell:>componenmy-shell:>componentsmy-shell:>componentstmy-shell:>componentstrmy-shell:>componentstrimy-shell:>componentstrin?Entervalue[Defaultmyvalue]?Entervalueh?Entervaluehimy-shell:>my-shell:> \ No newline at end of file diff --git a/spring-shell-docs/src/main/asciidoc/index.adoc b/spring-shell-docs/src/main/asciidoc/index.adoc deleted file mode 100644 index 7b9c115a..00000000 --- a/spring-shell-docs/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= Spring Shell Reference Documentation -Eric Bottard; Janne Valkealahti; Jay Bryant; Corneil du Plessis -:doctype: book -:hide-uri-scheme: -:icons: font -:experimental: // For kbd: macro -:spring-shell-starter: spring-shell-starter - -*{project-version}* - -(C) 2017 - 2023 VMware, Inc. - -_Copies of this document may be made for your own use and for distribution to -others, provided that you do not charge any fee for such copies and further -provided that each copy contains this Copyright Notice, whether distributed in -print or electronically._ - -include::introduction.adoc[] - -include::getting-started.adoc[] - -include::using-shell.adoc[] - -include::appendices.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/introduction.adoc b/spring-shell-docs/src/main/asciidoc/introduction.adoc deleted file mode 100644 index 2e871523..00000000 --- a/spring-shell-docs/src/main/asciidoc/introduction.adoc +++ /dev/null @@ -1,14 +0,0 @@ -== What is Spring Shell? -Not all applications need a fancy web user interface. -Sometimes, interacting with an application through an interactive terminal is -the most appropriate way to get things done. - -Spring Shell lets you create such a runnable application, where the -user enters textual commands that are run until the program terminates. -The Spring Shell project provides the infrastructure to create such a REPL (Read, Eval, -Print Loop) application, letting you concentrate on implementing commands by using -the familiar Spring programming model. - -Spring Shell includes advanced features (such as parsing, tab completion, colorization of -output, fancy ASCII-art table display, input conversion, and validation), freeing you -to focus on core command logic. diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc deleted file mode 100644 index f8aabfbc..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[[built-in-commands]] -=== Built-In Commands - -include::using-shell-commands-builtin-help.adoc[] - -include::using-shell-commands-builtin-clear.adoc[] - -include::using-shell-commands-builtin-exit.adoc[] - -include::using-shell-commands-builtin-stacktrace.adoc[] - -include::using-shell-commands-builtin-script.adoc[] - -include::using-shell-commands-builtin-history.adoc[] - -include::using-shell-commands-builtin-completion.adoc[] - -include::using-shell-commands-builtin-version.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc deleted file mode 100644 index a8053ace..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc +++ /dev/null @@ -1,24 +0,0 @@ -== Commands -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] - -In this section, we go through an actual command registration and leave command options -and execution for later in a documentation. You can find more detailed info in -<>. - -include::using-shell-commands-registration.adoc[] - -include::using-shell-commands-organize.adoc[] - -include::using-shell-commands-availability.adoc[] - -include::using-shell-commands-exceptionhandling.adoc[] - -include::using-shell-commands-hidden.adoc[] - -include::using-shell-commands-helpoptions.adoc[] - -include::using-shell-commands-interactionmode.adoc[] - -include::using-shell-commands-builtin.adoc[] - -include::using-shell-commands-writing.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc deleted file mode 100644 index c8b1d854..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[[using-shell-customization]] -== Customization - -This section describes how you can customize the shell. - -include::using-shell-customization-styling.adoc[] - -include::using-shell-customization-logging.adoc[] - -include::using-shell-customization-commandnotfound.adoc[] - -include::using-shell-customization-singlecommand.adoc[] - -include::using-shell-customization-contextclose.adoc[] diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc deleted file mode 100644 index e5ce2638..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[using-shell-options-basics]] -=== Basics -ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] - -This section gives a generic idea how an option can be defined. Following -sections, beyond basics, discuss more about how various option behaviour -can be accomplished for a particular use case. - -include::using-shell-options-basics-programmatic.adoc[] - -include::using-shell-options-basics-annotation.adoc[] - -include::using-shell-options-basics-legacyannotation.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 deleted file mode 100644 index ad1dd5e2..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc +++ /dev/null @@ -1,359 +0,0 @@ -==== Invoking your Commands - -This section addresses how you can control the way in which your commands are invoked. - -===== By Name Versus Positional Parameters - -As seen <>, decorating a method with `@ShellMethod` is the sole requirement for creating a command. - -The user can set the value of all the method parameters in either of two ways: - -* By using a parameter key (for example, `--arg value`). This approach is called "`by name parameters.`" -* Without a key, by setting parameter values in the order in which they appear in the method signature (called "`positional parameters`"). - -These two approaches can be mixed and matched, with named parameters always taking precedence (as they are less -prone to ambiguity). Consider the following command definition: - -==== -[source, java] ----- - @ShellMethod("Display stuff.") - public String echo(int a, int b, int c) { - return String.format("You said a=%d, b=%d, c=%d", a, b, c); - } ----- -==== - -Given the preceding command definiton, the following invocations are all equivalent, as shown in the output: - -==== -[source, bash] ----- -shell:>echo 1 2 3 <1> -You said a=1, b=2, c=3 - -shell:>echo --a 1 --b 2 --c 3 <2> -You said a=1, b=2, c=3 - -shell:>echo --b 2 --c 3 --a 1 <3> -You said a=1, b=2, c=3 - -shell:>echo --a 1 2 3 <4> -You said a=1, b=2, c=3 - -shell:>echo 1 --c 3 2 <5> -You said a=1, b=2, c=3 ----- -<1> This uses positional parameters. -<2> This is an example of full by-name parameters. -<3> By-name parameters can be reordered as desired. -<4> You can use a mix of the two approaches. -<5> The non by-name parameters are resolved in the order in which they appear. -==== - -====== Customizing the Named Parameter Keys - -As seen <>, the default strategy for deriving the key for a named parameter is to use the Java -name of the method signature and prefix it with two dashes (`--`). You can customize this in two ways: - -* Use the `prefix()` attribute of the `@ShellMethod` annotation to change the default prefix for the whole method. -* Annotate the parameter with the `@ShellOption` annotation to override the entire key in a per-parameter fashion. - -Consider the following example: - -==== -[source, java] ----- - @ShellMethod(value = "Display stuff.", prefix="-") - public String echo(int a, int b, @ShellOption("--third") int c) { - return String.format("You said a=%d, b=%d, c=%d", a, b, c); - } ----- -==== - -For such a setup, the possible parameter keys are `-a`, `-b` and `--third`. - -[TIP] -===== -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: - -==== -[source, java] ----- - @ShellMethod("Describe a command.") - public String help(@ShellOption({"-C", "--command"}) String command) { - ... - } ----- -==== -===== - -[[optional-parameters-default-values]] -===== Optional Parameters and Default Values - -Spring Shell provides the ability to give parameters default values, which lets users omit -those parameters. Consider the following command definition: - -==== -[source, java] ----- - @ShellMethod("Say hello.") - public String greet(@ShellOption(defaultValue="World") String who) { - return "Hello " + who; - } ----- -==== - -With the preceding definition, the `greet` command can still be invoked as `greet Mother` (or `greet --who Mother`), but the following -is also possible: - -==== -[source] ----- -shell:>greet -Hello World ----- -==== - -===== Parameter Arity -Up to now, it has always been assumed that each parameter maps to a single word entered by the user. -Situations may arise, though, when a parameter value should be multi-valued. This is driven by the `arity()` -attribute of the `@ShellOption` annotation. You can use a collection or array for the parameter type and specify how -many values are expected: - -==== -[source, java] ----- - @ShellMethod("Add Numbers.") - public float add(@ShellOption(arity=3) float[] numbers) { - return numbers[0] + numbers[1] + numbers[2]; - } ----- -==== - -The users can then invoke the command by using any of the following syntax: - -==== -[source] ----- -shell:>add 1 2 3.3 -6.3 -shell:>add --numbers 1 2 3.3 -6.3 ----- -==== - -[WARNING] -===== -When using the _by-name_ parameter approach, the key should *not* be repeated. The following does *not* work: - -==== -[source] ----- -shell:>add --numbers 1 --numbers 2 --numbers 3.3 ----- -==== -===== - -====== Varying Amount Arity - -The above example demonstrates requiring a known, constant arity for a parameter, three in this case. Allowing any number of multiple values of a parameter can be achieved by leaving `arity` unspecified and using Spring's built-in comma separated value parsing for collections and/or arrays: -[source, java] ----- - @ShellMethod("Add a Varying Amount of Numbers.") - public double add(@ShellOption double[] numbers) { - return Arrays.stream(numbers).sum(); - } ----- - -The command may then be invoked with any amount of `numbers`: - -==== -[source] ----- -shell:>add 1,2,3.3 -6.3 -shell:>add --numbers 42 -42.0 -shell:>add --numbers 1,2,3.3,4,5 -15.3 ----- -==== - -====== Special Handling of Boolean Parameters - -When it comes to parameter arity, one kind of parameter receives a special treatment by default, as -is often the case in command-line utilities. -Boolean (that is, `boolean` as well as `java.lang.Boolean`) parameters behave like they have an `arity()` of `0` by default, allowing users to set their values by using a "`flag`" approach. -Consider the following command definition: - -==== -[source, java] ----- - @ShellMethod("Terminate the system.") - public String shutdown(boolean force) { - return "You said " + force; - } ----- -==== - -This preceding command definition allows the following invocations: - -==== -[source] ----- -shell:>shutdown -You said false -shell:>shutdown --force -You said true ----- -==== - -TIP: This special treatment plays well with the <> specification. Although the default -for boolean parameters is to have their default value be `false`, you can specify otherwise (that is, -`@ShellOption(defaultValue="true")`), and the behavior is inverted (that is, not specifying the parameter -results in the value being `true`, and specifying the flag results in the value being `false`) - -[WARNING] -===== -Having this behavior of implicit `arity()=0` prevents the user from specifying a value (for example, `shutdown --force true`). -If you would like to allow this behavior (and forego the flag approach), then force an arity of `1` by using the annotation as follows: - -==== -[source, java] ----- - @ShellMethod("Terminate the system.") - public String shutdown(@ShellOption(arity=1, defaultValue="false") boolean force) { - return "You said " + force; - } ----- -==== -===== - -[[quotes-handling]] -===== Quotes Handling - -Spring Shell takes user input and tokenizes it into words, splitting on space characters. -If the user wants to provide a parameter value that contains spaces, that value needs to be quoted. -Both single (`'`) and double (`"`) quotes are supported, and those quotes are not part of the value: -Consider the following command definition: - -==== -[source, java] ----- - @ShellMethod("Prints what has been entered.") - public String echo(String what) { - return "You said " + what; - } ----- -==== - -The following commands all invoke the preceding command definition: - -==== -[source] ----- -shell:>echo Hello -You said Hello -shell:>echo 'Hello' -You said Hello -shell:>echo 'Hello World' -You said Hello World -shell:>echo "Hello World" -You said Hello World ----- -==== - -Supporting both single and double quotes lets the user embed one type of quotes into -a value: - -==== -[source] ----- -shell:>echo "I'm here!" -You said I'm here! -shell:>echo 'He said "Hi!"' -You said He said "Hi!" ----- -==== - -That way, the user can use a single quote as an apostrophe in a message. - -Should the user need to embed the same kind of quote that was used to quote the whole parameter, -the escape sequence uses the backslash (`\`) character: - -==== -[source] ----- -shell:>echo 'I\'m here!' -You said I'm here! -shell:>echo "He said \"Hi!\"" -You said He said "Hi!" -shell:>echo I\'m here! -You said I'm here! ----- -==== - -It is also possible to escape space characters when not using enclosing quotes: - -==== -[source] ----- -shell:>echo This\ is\ a\ single\ value -You said This is a single value ----- -==== - -[[interacting-with-the-shell]] -===== Interacting with the Shell - -The Spring Shell project builds on top of the https://github.com/jline/jline3[JLine] library and, as a result, brings -a lot of nice interactive features, some of which are detailed in this section. - -First and foremost, Spring Shell supports tab completion almost everywhere possible. So, if there -is an `echo` command and the user types `ec` and presses `TAB`, `echo` appears. -Should there be several commands that start with `ec`, then the user is prompted to choose (using `TAB` or -`Shift + TAB` to navigate and `ENTER` to select.) - -But completion does not stop at command keys. It also works for parameter keys (`--arg`) and even -parameter values, if the application developer registered the appropriate beans (see <>). - -Another nice feature of Spring Shell applications is support for line continuation. If a command and its parameters -is too long and does not fit nicely on the screen, a user can chunk it by ending a line with a backslash -(`\`) character, pressing `ENTER`, and continuing on the next line. Upon submission of the whole command, this is -parsed as if the user entered a single space on line breaks. The following listing shows an example of this behavior: - -==== -[source] ----- -shell:>register module --type source --name foo \ <1> -> --uri file:///tmp/bar -Successfully registered module 'source:foo' ----- -<1> command continues on next line -==== - -Line continuation also automatically triggers if the user has opened a quote (see <>) -and presses `ENTER` while still in the quotes: - -==== -[source] ----- -shell:>echo "Hello <1> -dquote> World" -You said Hello World ----- -<1> The user pressed `ENTER` here. -==== - -Finally, Spring Shell applications benefit from a lot of keyboard shortcuts (borrowed from Emacs) with which you may -already be familiar from working with your regular OS Shell. Notable shortcuts include `Ctrl+r` to perform -a reverse search, `Ctrl+a`] and `Ctrl+e` to move to the beginning and the end of the current line (respectively), -and `Esc f` and `Esc b` to move forward or backward (respectively) one word at a time. - -[[providing-tab-completion]] -// ===== Providing TAB Completion Proposals - -// TBD diff --git a/spring-shell-docs/src/main/asciidoc/using-shell.adoc b/spring-shell-docs/src/main/asciidoc/using-shell.adoc deleted file mode 100644 index 1278d918..00000000 --- a/spring-shell-docs/src/main/asciidoc/using-shell.adoc +++ /dev/null @@ -1,17 +0,0 @@ -include::using-shell-basics.adoc[] - -include::using-shell-commands.adoc[] - -include::using-shell-options.adoc[] - -include::using-shell-completion.adoc[] - -include::using-shell-building.adoc[] - -include::using-shell-components.adoc[] - -include::using-shell-customization.adoc[] - -include::using-shell-execution.adoc[] - -include::using-shell-testing.adoc[]