Spring Shell

Spring Shell is a framework for building interactive terminal-based applications (REPL - Read, Eval, Print Loop). It allows developers to create applications where users enter textual commands that are executed within a running program.

By using the familiar Spring programming model, you can focus on implementing core command logic while Spring Shell handles advanced terminal features such as:

• Command parsing
• Tab completion
• Output colorization
• ASCII-art table displays
• Input conversion and validation

The spring-shell-samples directory contains several example projects designed to demonstrate different usage patterns of Spring Shell. Each sample is self-contained and includes its own README with specific build and execution instructions.

Available samples include:

• spring-shell-sample-hello-world: A basic command-line application for greeting users.
• spring-shell-sample-non-interactive: Demonstrates how to invoke commands (e.g., hi) and exit without an interactive session.
• spring-shell-sample-petclinic: Integrates shell commands with the Spring PetClinic application.
• spring-shell-sample-secure-input: Demonstrates how to handle secure user input, such as password prompts.
• spring-shell-sample-spring-boot: Shows how to use Spring Shell within a Spring Boot-based application.

The Terminal UI Framework is a toolkit designed for building rich console applications within Spring Shell.

Note: This feature is currently experimental and is subject to breaking changes as the framework foundation and related concepts stabilize.

If you want to use the existing components as-is, you can follow the standard Terminal UI guides. If you intend to extend the framework by creating your own custom components, refer to the Terminal UI Appendix for advanced implementation details.

AppView manages input processing through a specific hierarchy of precedence for both standard keys and hotkeys.

Key Handling

Standard key handling follows this order of priority:

1. Menu: If the menu has focus and handles the key, processing stops.
2. Main: If the menu does not handle the key, the main content view is consulted.
3. Navigation: Cursor left/right keys are intercepted to dispatch an AppViewEvent.

HotKey Handling

Hotkeys are processed in the reverse order of standard keys:

1. Main
2. Menu
3. Status

You can implement branching or conditional logic within a ComponentFlow by using a next function. The next function allows you to specify which component should execute next by returning its target component ID.

Flow Control Rules:

• To jump to a specific component, return its component ID.
• To stop the flow, return null or an ID that does not exist in the flow.

// Example of conditional jumping (conceptual based on snippet2)
// Returning a component ID directs the flow to that component
// Returning null stops the flow

The sample demonstrates how to use the AvailabilityProvider API to control command visibility and execution based on application state, such as authentication status.

In this sample, the auth change-password command is only available to the user when they are successfully authenticated. This is achieved by implementing an AvailabilityProvider that checks the user's authentication status.

Starting from version 2.1.x, Spring Shell provides a component model designed for higher-level user interactions. This model is ideal for common use cases such as requesting plain text input or allowing a user to select an item from a list.

Built-in component templates are available in the org.springframework.shell.component classpath.

Built-in components typically follow a specific lifecycle:

1. Enter a run loop for user input.
2. Generate component-related context.
3. Render the runtime status of a component state.
4. Exit the loop.
5. Render the final status of the component state.

The ShellRunner interface is the primary mechanism for running a shell. An application context can only have one ShellRunner.

Spring Shell provides three implementations:

1. SystemShellRunner: The default implementation used for interactive sessions.
2. JLineShellRunner: An alternative interactive implementation.
3. NonInteractiveShellRunner: Used for running commands without an interactive loop.

To switch to non-interactive mode, set the following property in your configuration: spring.shell.interactive.enabled=false

Note for Spring Boot users: Spring Shell automatically registers an ApplicationRunner bean named springShellApplicationRunner to run the default interactive runner. To use a different ShellRunner implementation, you must override this default ApplicationRunner bean.

The ListView<T> is a base TUI (Terminal User Interface) view used to draw a list of items of type T. It inherits from BoxView.

ListView supports three selection modes:

• NOCHECK: Items are shown as-is without a selection state.
• CHECK: Multiple items can be in a checked state.
• RADIO: Only one item can be in a checked state at a time.

Item rendering is handled by a CellFactory.

// Example of creating a ListView (referencing snippet1 logic)
ListView<String> listView = new ListView<>(items, selectionMode);