diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc index 22c3f6e2..d5baabb4 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc @@ -1,3 +1,4 @@ +[[command-catalog]] === Command Catalog The `CommandCatalog` interface defines how command registrations exist in a shell application. It is possible to dynamically register and de-register @@ -11,6 +12,7 @@ include::{snippets}/CommandCatalogSnippets.java[tag=snippet1] ---- ==== +[[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 @@ -27,6 +29,7 @@ IMPORTANT: A current limitation of a `CommandResolver` is that it is used every 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 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 diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc index 8593a4df..c0113475 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc @@ -1,3 +1,4 @@ +[[command-context]] === Command Context The `CommandContext` interface gives access to a currently running context. You can use it to get access to options: diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc index 22fe4c02..c536a1d2 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc @@ -1,3 +1,4 @@ +[[command-execution]] === 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/modules/ROOT/pages/appendices-techical-intro-parser.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc index 1ecc76ae..57a79d74 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc @@ -1,3 +1,4 @@ +[[command-parser]] === Command Parser 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/modules/ROOT/pages/appendices-techical-intro-registration.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc index 415461d3..ff523a50 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc @@ -6,6 +6,7 @@ Defining a command registration is a first step to introducing the structure of 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 A command in a `spring-shell` structure is defined as an array of commands. This yields a structure similar to the following example: @@ -23,6 +24,7 @@ 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 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 @@ -36,6 +38,7 @@ 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 can be defined as long and short, where the prefixing is `--` and `-`, respectively. The following examples show long and short options: @@ -54,10 +57,12 @@ include::{snippets}/CommandRegistrationSnippets.java[tag=snippet2] ---- ==== +[[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 Using a `Method` in an existing POJO is one way to define a target. Consider the following class: @@ -78,6 +83,7 @@ include::{snippets}/CommandTargetSnippets.java[tag=snippet12] ---- ==== +[[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 @@ -91,6 +97,7 @@ include::{snippets}/CommandTargetSnippets.java[tag=snippet2] ---- ==== +[[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, diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc index 5fa9492f..28d77fcb 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc @@ -8,6 +8,7 @@ contains info about match positions and overall score of a match. https://github.com/junegunn/fzf[fzf]. +[[implementations]] ==== Implementations *FuzzyMatchV2Search* @@ -20,6 +21,7 @@ quickly finding paths. Port of _fzf ExactMatchNaive_ algorithm. Simple exact match works more accurately if you know what to search. +[[searchmatch]] ==== SearchMatch Algorithms and default syntax are hidden inside package protected classes @@ -55,6 +57,7 @@ below table. |Items that include `stuff` |=== +[[examples]] ==== Examples ==== diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc index 21b205c8..d218fc28 100644 --- a/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc +++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc @@ -7,6 +7,7 @@ In this section we discuss how this application works. It can be considered to b a reference application as it's using most of the features available and tries to follow best practices. +[[create-scenario]] ==== Create Scenario Every `Scenario` essentially is a sample code of a `View` as that's what catalog app demonstrates. diff --git a/spring-shell-docs/modules/ROOT/pages/getting-started.adoc b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc index 54049e78..c9567d45 100644 --- a/spring-shell-docs/modules/ROOT/pages/getting-started.adoc +++ b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc @@ -1,3 +1,4 @@ +[[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. @@ -5,6 +6,7 @@ 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 For the purpose of this tutorial, we create a simple Spring Boot application by diff --git a/spring-shell-docs/modules/ROOT/pages/index.adoc b/spring-shell-docs/modules/ROOT/pages/index.adoc index 7b9c115a..e41b82f1 100644 --- a/spring-shell-docs/modules/ROOT/pages/index.adoc +++ b/spring-shell-docs/modules/ROOT/pages/index.adoc @@ -1,3 +1,4 @@ +[[spring-shell-reference-documentation]] = Spring Shell Reference Documentation Eric Bottard; Janne Valkealahti; Jay Bryant; Corneil du Plessis :doctype: book diff --git a/spring-shell-docs/modules/ROOT/pages/introduction.adoc b/spring-shell-docs/modules/ROOT/pages/introduction.adoc index 2e871523..41e550bc 100644 --- a/spring-shell-docs/modules/ROOT/pages/introduction.adoc +++ b/spring-shell-docs/modules/ROOT/pages/introduction.adoc @@ -1,3 +1,4 @@ +[[what-is-spring-shell?]] == What is Spring Shell? Not all applications need a fancy web user interface. Sometimes, interacting with an application through an interactive terminal is diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc index b1e089e1..3a3b28cf 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc @@ -15,4 +15,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/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc index e20a51e4..50ea998b 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc @@ -52,6 +52,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void] ---- ==== +[[method-arguments]] ===== Method Arguments `@ExceptionResolver` methods support the following arguments: @@ -67,6 +68,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void] |=== +[[return-values]] ===== Return Values `@ExceptionResolver` methods support the following return values: diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc index b9061076..4675dfcd 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc @@ -1,3 +1,4 @@ +[[registration]] === Registration ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc index 7f73f25b..99a35c95 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc @@ -1,3 +1,4 @@ +[[writing]] === Writing ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc index a8053ace..00c3fc48 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc @@ -1,3 +1,4 @@ +[[commands]] == Commands ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc index d53907c0..45e0c76d 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc @@ -1,3 +1,4 @@ +[[completion]] == Completion ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] @@ -8,6 +9,7 @@ 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 Hints for completions are calculated with _function_ or _interface_ style @@ -58,6 +60,7 @@ include::{snippets}/CompletionSnippets.java[tag=anno-method] ---- ==== +[[command-line]] === Command-Line Command-line completion currently only support _bash_ and is documented diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc index fac265bb..4515d1e6 100644 --- a/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc +++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc @@ -4,6 +4,7 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] This section talks about how particular data type is used as an option value. +[[string]] ==== String `String` is a most simplest type as there's no conversion involved as what's @@ -26,6 +27,7 @@ include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-reg] ---- ==== +[[boolean]] ==== Boolean Using boolean types is a bit more involved as there are `boolean` and @@ -74,6 +76,7 @@ arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false ---- ==== +[[number]] ==== Number Numbers are converted as is. @@ -92,6 +95,7 @@ include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-reg] ---- ==== +[[enum]] ==== Enum Conversion to enums is possible if given value is exactly matching enum itself. @@ -118,6 +122,7 @@ include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-reg] ---- ==== +[[array]] ==== Array Arrays can be used as is with strings and primitive types.