Fix indentation for all pages
This commit is contained in:
Rob Winch
@@ -1,5 +1,5 @@
|
||||
[appendix]
|
||||
[#appendix-debugging]
|
||||
== Debugging
|
||||
= Debugging
|
||||
|
||||
Please find more info about debugging from https://github.com/spring-projects/spring-shell/wiki/Debugging[project wiki].
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[command-catalog]]
|
||||
=== 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
|
||||
commands, which gives flexibility for use cases where possible commands
|
||||
@@ -13,7 +14,7 @@ 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:
|
||||
@@ -30,7 +31,7 @@ Thus, we advise not using it if a command resolution call takes a long time, as
|
||||
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.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[command-context]]
|
||||
=== Command Context
|
||||
= Command Context
|
||||
|
||||
The `CommandContext` interface gives access to a currently running
|
||||
context. You can use it to get access to options:
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
[[command-execution]]
|
||||
=== 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.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
[[command-parser]]
|
||||
=== 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.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tech-intro-registration]
|
||||
=== Command Registration
|
||||
= Command Registration
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Defining a command registration is a first step to introducing the structure of a command and its options
|
||||
@@ -7,7 +8,7 @@ and parameters. This is loosely decoupled from what happens later, such as parsi
|
||||
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:
|
||||
|
||||
@@ -25,7 +26,7 @@ NOTE: We do not currently support mapping commands to an explicit parent if sub-
|
||||
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).
|
||||
@@ -39,7 +40,7 @@ Also, being on an active `REPL` session may provide more information about what
|
||||
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:
|
||||
|
||||
@@ -58,12 +59,12 @@ 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:
|
||||
|
||||
@@ -84,7 +85,7 @@ 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
|
||||
@@ -98,7 +99,7 @@ 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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tech-intro-searchalgorithm]
|
||||
=== Search Algorithms
|
||||
= Search Algorithms
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
`SearchMatch` is an interface to match _text_ with a _pattern_. Match
|
||||
@@ -9,7 +10,7 @@ contains info about match positions and overall score of a match.
|
||||
https://github.com/junegunn/fzf[fzf].
|
||||
|
||||
[[implementations]]
|
||||
==== Implementations
|
||||
== Implementations
|
||||
|
||||
*FuzzyMatchV2Search*
|
||||
|
||||
@@ -22,7 +23,7 @@ Port of _fzf ExactMatchNaive_ algorithm. Simple exact match works more accuratel
|
||||
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
|
||||
@@ -58,7 +59,7 @@ below table.
|
||||
|===
|
||||
|
||||
[[examples]]
|
||||
==== Examples
|
||||
== Examples
|
||||
|
||||
====
|
||||
[source, java, indent=0]
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tech-intro-theming]
|
||||
=== Theming
|
||||
= Theming
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Styling in a theming is provided by a use of a _AttributedString_ from `JLine`.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
[appendix]
|
||||
[#appendix-tech-intro]
|
||||
== Techical Introduction
|
||||
= 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.
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-catalog]
|
||||
=== Catalog App
|
||||
= Catalog App
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Catalog application is showing various ways how Terminal UI Framework can be used.
|
||||
@@ -8,6 +9,6 @@ a reference application as it's using most of the features available and tries
|
||||
to follow best practices.
|
||||
|
||||
[[create-scenario]]
|
||||
==== Create Scenario
|
||||
== Create Scenario
|
||||
Every `Scenario` essentially is a sample code of a `View` as that's what catalog
|
||||
app demonstrates.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-control]
|
||||
=== Control
|
||||
= Control
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_Control_ draws something into a screen with a given bounds.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-eventloop]
|
||||
=== EventLoop
|
||||
= EventLoop
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_EventLoop_ is a central system handling eventing in a framework.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-keyhandling]
|
||||
=== Key Handling
|
||||
= Key Handling
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Handles incoming key events.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-mousehandling]
|
||||
=== Mouse Handling
|
||||
= Mouse Handling
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Handles incoming mouse events.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-screen]
|
||||
=== Screen
|
||||
= Screen
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_Screen_ is an abstraction providing higher level concept to draw something
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[#appendix-tui-view]
|
||||
=== View
|
||||
= View
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_View_ extends _Control_ providing integration into event loop.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
[appendix]
|
||||
[#appendix-tech-intro-tui]
|
||||
== Terminal UI
|
||||
= Terminal UI
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
This is a technical introduction to _UI Framework_.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[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.
|
||||
|
||||
@@ -7,7 +8,7 @@ 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.
|
||||
@@ -98,7 +99,7 @@ TIP: Check out <<using-shell-customization-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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[what-is-spring-shell?]]
|
||||
== 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
|
||||
the most appropriate way to get things done.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[using-shell-basics-reading]]
|
||||
=== Reading Docs
|
||||
= Reading Docs
|
||||
|
||||
Throughout this documentation, we make references to configuring something by using
|
||||
annotations or programmatic examples.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-basics]]
|
||||
== Basics
|
||||
= Basics
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
[[built-in-commands-clear]]
|
||||
==== Clear
|
||||
= Clear
|
||||
|
||||
The `clear` command does what you would expect and clears the screen, resetting the prompt
|
||||
in the top left corner.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands-completion]]
|
||||
==== Completion
|
||||
= Completion
|
||||
|
||||
The `completion` command set lets you create script files that can be used
|
||||
with am OS shell implementations to provide completion. This is very useful when
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands-exit]]
|
||||
==== Exit
|
||||
= Exit
|
||||
|
||||
The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully
|
||||
closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands-history]]
|
||||
==== History
|
||||
= History
|
||||
|
||||
The `history` command shows the history of commands that has been executed.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands-script]]
|
||||
==== Script
|
||||
= Script
|
||||
|
||||
The `script` command accepts a local file as an argument and replays commands found there, one at a time.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands-stacktrace]]
|
||||
==== Stacktrace
|
||||
= Stacktrace
|
||||
|
||||
When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed
|
||||
so as not to overflow the user with too much information.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[built-in-commands]]
|
||||
=== Built-In Commands
|
||||
= Built-In Commands
|
||||
|
||||
include::using-shell-commands-builtin-help.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
|
||||
@@ -53,7 +54,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void]
|
||||
====
|
||||
|
||||
[[method-arguments]]
|
||||
===== Method Arguments
|
||||
== Method Arguments
|
||||
`@ExceptionResolver` methods support the following arguments:
|
||||
|
||||
[Attributes]
|
||||
@@ -69,7 +70,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void]
|
||||
|===
|
||||
|
||||
[[return-values]]
|
||||
===== Return Values
|
||||
== Return Values
|
||||
`@ExceptionResolver` methods support the following return values:
|
||||
|
||||
[Attributes]
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[dynamic-command-exitcode]]
|
||||
=== Exception Handling
|
||||
= Exception Handling
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Exceptions happen from a user code wether it is intentional or not. This section describes
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[commands-interactionmode]]
|
||||
=== Interaction Mode
|
||||
= Interaction Mode
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Command registration can define `InteractionMode` which is used to hide commands
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[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`
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[registration]]
|
||||
=== Registration
|
||||
= Registration
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
There are two different ways to define a command: through an annotation model and
|
||||
|
||||
@@ -1,5 +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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[commands]]
|
||||
== Commands
|
||||
= Commands
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
In this section, we go through an actual command registration and leave command options
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[completion]]
|
||||
== Completion
|
||||
= Completion
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Spring Shell can provide completion proposals for both interactive shell
|
||||
@@ -10,7 +11,7 @@ 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
|
||||
@@ -61,7 +62,7 @@ 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 <<built-in-commands-completion>>.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-flow]]
|
||||
=== Flow
|
||||
= Flow
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
When you use <<using-shell-components-ui>> to build something that involves
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-confirmation]]
|
||||
==== Confirmation
|
||||
= Confirmation
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
The confirmation component asks a user for a simple confirmation. It is essentially a
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-multiselect]]
|
||||
==== Multi Select
|
||||
= Multi Select
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
The multi select component asks a user to select multiple items from a list.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-pathinput]]
|
||||
==== Path Input
|
||||
= Path Input
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
The path input component asks a user for a `Path` and gives additional information about a path itself.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-pathsearch]]
|
||||
==== Path Search
|
||||
= Path Search
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
The path search component asks base directory for scan and optional search expression.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-singleselect]]
|
||||
==== Single Select
|
||||
= Single Select
|
||||
|
||||
ifndef::snippets[:snippets: ../../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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-components-ui-stringinput]]
|
||||
==== String Input
|
||||
= String Input
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
The string input component asks a user for simple text input, optionally masking values
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[using-shell-components]]
|
||||
== Components
|
||||
= Components
|
||||
|
||||
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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-customization-singlecommand]]
|
||||
=== Single Command
|
||||
= Single Command
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
If your shell application is made for exactly a single purpose having only one
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[theming]]
|
||||
=== Theming
|
||||
= Theming
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Current terminal implementations are rich in features and can usually show
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[using-shell-customization]]
|
||||
== Customization
|
||||
= Customization
|
||||
|
||||
This section describes how you can customize the shell.
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-arity]]
|
||||
=== Arity
|
||||
= Arity
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Arity defines how many parameters option parsing takes.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-basics-annotation]]
|
||||
==== Annotation
|
||||
= Annotation
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
`Option` annotation can be used to define an option name if you
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-basics-legacyannotation]]
|
||||
==== Legacy Annotation
|
||||
= Legacy Annotation
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Having a target method with argument is automatically registered with a matching
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
[[using-shell-options-basics-registration]]
|
||||
[[using-shell-options-basics-programmatic]]
|
||||
==== Programmatic
|
||||
= Programmatic
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Programmatic way with `CommandRegistration` is to use `withOption` to define
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-basics]]
|
||||
=== Basics
|
||||
= Basics
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
This section gives a generic idea how an option can be defined. Following
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-default]]
|
||||
=== Default Value
|
||||
= Default Value
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Having a default value for an option is somewhat related to
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-label]]
|
||||
=== Label
|
||||
= Label
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_Option Label_ has no functional behaviour within a shell itself other than
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-naming]]
|
||||
=== Naming
|
||||
= Naming
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
If there is a need to modify option long names that can be done
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-optional]]
|
||||
=== Optional Value
|
||||
= Optional Value
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
An option is either required or not and, generally speaking, how it behaves depends on
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-positional]]
|
||||
=== Positional
|
||||
= Positional
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Positional information is mostly related to a command target method:
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options-short]]
|
||||
=== Short Format
|
||||
= Short Format
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Short style _POSIX_ option is usually just a synonym to long format. As
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
[[using-shell-options-types]]
|
||||
=== Types
|
||||
= Types
|
||||
|
||||
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
|
||||
|
||||
`String` is a most simplest type as there's no conversion involved as what's
|
||||
coming in from a user is always a string.
|
||||
@@ -28,7 +29,7 @@ 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
|
||||
@@ -77,7 +78,7 @@ arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
|
||||
====
|
||||
|
||||
[[number]]
|
||||
==== Number
|
||||
== Number
|
||||
|
||||
Numbers are converted as is.
|
||||
|
||||
@@ -96,7 +97,7 @@ 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.
|
||||
@@ -123,7 +124,7 @@ include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-reg]
|
||||
====
|
||||
|
||||
[[array]]
|
||||
==== Array
|
||||
== Array
|
||||
|
||||
Arrays can be used as is with strings and primitive types.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-options]]
|
||||
== Options
|
||||
= Options
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Command line arguments can be separated into options and positional parameters.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-testing-basics]]
|
||||
=== Basics
|
||||
= Basics
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Spring Shell provides a number of utilities and annotations to help when testing your application.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-testing-settings]]
|
||||
=== Settings
|
||||
= Settings
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Built in emulation uses terminal width 80 and height 24 on default.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-testing]]
|
||||
== Testing
|
||||
= Testing
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Testing cli application is difficult due to various reasons:
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-tui-intro]]
|
||||
=== Introduction
|
||||
= Introduction
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Lets start with a simple app which prints "hello world" in a view.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-tui-views-box]]
|
||||
==== BoxView
|
||||
= BoxView
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_BoxView_ is a base implementation providing functionality to draw into a
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-tui-views-list]]
|
||||
==== ListView
|
||||
= ListView
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
_ListView_ is a base implementation providing functionality to draw list of items.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
[[using-shell-tui-views]]
|
||||
=== Views
|
||||
= Views
|
||||
|
||||
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
|
||||
|
||||
Framework provides a build-in views which are documented below.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
[[using-shell-tui]]
|
||||
== Terminal UI
|
||||
= Terminal UI
|
||||
|
||||
NOTE: Feature is experimental and subject to breaking changes until foundation
|
||||
and related concepts around framework are getting more stable.
|
||||
|
||||
Reference in New Issue
Block a user