Skip to main content

Prompt Module

The JLine Prompt module provides a modern, native JLine implementation for interactive console prompts. It offers a complete replacement for the console-ui module with enhanced features including multi-column layouts, advanced navigation, and script integration capabilities.

Introduction​

The Prompt module is a comprehensive prompt system built natively on JLine, providing all the functionality of console-ui while adding significant enhancements. It features a fluent builder API, multi-column layouts, grid-based navigation, and command-line integration for scripts and automation.

Key Features​

The Prompt module offers:

  • Multi-column layouts with automatic terminal width adaptation
  • Grid-based navigation using arrow keys (left/right for columns, up/down for rows)
  • Advanced item support including disabled items and pre-checked checkboxes
  • Choice prompts with key-based selection (e.g., 'r' for Red, 'g' for Green)
  • Specialized prompts for passwords, numbers, toggles, search, editor, and key press
  • Professional display management with efficient screen updates
  • Pagination and scrolling for large item lists
  • Script integration via PromptCommands for shell scripts and automation
  • Terminal capability detection with graceful fallbacks
  • Native JLine implementation with no external dependencies

Quick Start Example​

Here's a simple example demonstrating the fluent builder API:

Loading snippet: PromptBasicExample...

Architecture​

The Prompt module uses a factory pattern with fluent builders:

// Create a prompter
Terminal terminal = TerminalBuilder.builder().build();
Prompter prompter = PrompterFactory.create(terminal);

// Build prompts using fluent API
PromptBuilder builder = prompter.newBuilder();

Prompt Types​

List Prompt​

Single-selection lists with multi-column layout support:

Loading snippet: PromptListExample...

Checkbox Prompt​

Multiple-selection checkboxes with pre-checked item support:

Loading snippet: PromptCheckboxExample...

Choice Prompt​

Key-based selection with character shortcuts:

Loading snippet: PromptChoiceExample...

Input Prompt​

Text input with default values and masking:

Loading snippet: PromptInputExample...

Confirm Prompt​

Yes/No confirmation with default values:

Loading snippet: PromptConfirmExample...

Password Prompt​

Secure password input with configurable masking:

Loading snippet: PromptPasswordExample...

Number Prompt​

Numeric input with range validation and decimal control:

Loading snippet: PromptNumberExample...

Toggle Prompt​

Binary choice between two labeled options, navigated with arrow keys:

Loading snippet: PromptToggleExample...

Editor Prompt​

Opens an inline editor (Nano) for multi-line text editing:

Loading snippet: PromptEditorExample...

Search Prompt​

Dynamic search with type-ahead filtering:

Loading snippet: PromptSearchExample...

KeyPress Prompt​

Captures a single key press without requiring Enter:

Loading snippet: PromptKeyPressExample...

Multi-Column Layouts​

The Prompt module automatically calculates optimal column layouts based on terminal width and item content:

Loading snippet: PromptMultiColumnExample...

  • Up/Down arrows: Navigate between rows
  • Left/Right arrows: Navigate between columns, switch toggle state
  • Enter: Select/confirm
  • Space: Toggle checkbox items
  • Character keys: Quick selection in choice prompts
  • Escape: Cancel / go back to previous prompt
  • Any key: Advances key press prompts

Advanced Features​

Disabled Items​

Items can be disabled with custom disabled text:

Loading snippet: PromptDisabledItemsExample...

Pre-checked Checkboxes​

Checkbox items can be initially checked:

Loading snippet: PromptPreCheckedExample...

Mixed Prompt Types​

Combine multiple prompt types in a single session:

Loading snippet: PromptMixedTypesExample...

Script Integration​

The Prompt module includes PromptCommands for command-line usage:

Command Syntax​

prompt [OPTIONS] TYPE [ITEMS...]

Options:
  -m --message=MESSAGE     prompt message
  -t --title=TITLE         prompt title/header
  -d --default=VALUE       default value
  -k --key=KEYS           choice keys (for choice type)

Examples​

# List selection
prompt list "Choose environment" "Development" "Staging" "Production"

# Multiple selection
prompt checkbox "Select features" "Feature A" "Feature B" "Feature C"

# Quick choice with keys
prompt choice "Pick color" "Red" "Green" "Blue" -k "rgb"

# Text input with default
prompt input "Enter name" -d "John Doe"

# Confirmation
prompt confirm "Deploy to production?" -d "y"

Configuration​

The prompt system can be configured via PrompterConfig:

Loading snippet: PromptConfigExample...

Migration from Console-UI​

The Prompt module provides full backward compatibility with console-ui:

Before (Console-UI)​

ConsolePrompt prompt = new ConsolePrompt();
PromptBuilder promptBuilder = prompt.getPromptBuilder();

After (Prompt Module)​

Prompter prompter = PrompterFactory.create(terminal);
PromptBuilder promptBuilder = prompter.newBuilder();

The API is identical, but the Prompt module offers enhanced features and better performance.

Best Practices​

Builder Pattern Usage​

Always use the fluent builder API for consistency:

Loading snippet: PromptBestPracticesExample...

Error Handling​

Handle user interruptions gracefully:

Loading snippet: PromptErrorHandlingExample...

Terminal Adaptation​

The prompt system automatically adapts to different terminal sizes and capabilities. For optimal experience:

  • Use descriptive but concise item text
  • Consider terminal width when designing prompts
  • Test with different terminal sizes
  • Provide meaningful default values

Performance​

The Prompt module is optimized for performance:

  • Efficient rendering: Only updates changed screen areas
  • Lazy evaluation: Calculates layouts only when needed
  • Memory efficient: Minimal object allocation during navigation
  • Terminal capability caching: Avoids repeated capability detection

Troubleshooting​

Common Issues​

Multi-column layout not working: Ensure terminal width is sufficient and item text is not too long.

Navigation keys not responding: Check terminal capability detection and ensure proper key binding setup.

Display corruption: Verify terminal supports required capabilities and consider using fallback mode.

Debug Mode​

Enable debug logging to troubleshoot issues:

System.setProperty("jline.prompt.debug", "true");

API Reference​

Core Interfaces​

  • Prompter: Main interface for creating prompts
  • PromptBuilder: Builder for creating multiple prompts
  • BaseBuilder: Common base for all prompt builders (name, message, transformer, filter)
  • PromptResult: Base interface for prompt results

Prompt Builders​

  • ListBuilder: Single-selection list prompt
  • CheckboxBuilder: Multiple-selection checkbox prompt
  • ChoiceBuilder: Key-based choice prompt
  • InputBuilder: Text input prompt
  • ConfirmBuilder: Yes/No confirmation prompt
  • PasswordBuilder: Masked password input prompt
  • NumberBuilder: Numeric input with validation
  • ToggleBuilder: Binary toggle between two options
  • EditorBuilder: Multi-line editor prompt
  • SearchBuilder: Type-ahead search prompt
  • KeyPressBuilder: Single key capture prompt
  • TextBuilder: Static text display

Factory Classes​

  • PrompterFactory: Creates Prompter instances
  • DefaultPrompter: Main implementation

Configuration​

  • PrompterConfig: Configuration interface
  • DefaultPrompterConfig: Default configuration implementation

For complete API documentation, see the JavaDoc reference.