Module org.jline.prompt
Package org.jline.prompt

Interface Prompter

All Known Implementing Classes:
DefaultPrompter
public interface Prompter
Main interface for the JLine Prompt API.

The Prompter is the primary entry point for creating and executing interactive console prompts. It provides a fluent, type-safe API for building various types of user input prompts including text input, lists, checkboxes, choices, and confirmations.

Basic Usage


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

 // Build and execute prompts
 PromptBuilder builder = prompter.newBuilder();
 builder.createListPrompt()
     .name("choice")
     .message("Select an option:")
     .newItem("option1").text("Option 1").add()
     .newItem("option2").text("Option 2").add()
     .addPrompt();

 Map<String, ? extends PromptResult<? extends Prompt>> results =
     prompter.prompt(Collections.emptyList(), builder.build());

Dynamic Prompts

The prompter supports dynamic prompt generation where subsequent prompts can be created based on the results of previous prompts: 


 Map<String, ? extends PromptResult<? extends Prompt>> results = prompter.prompt(
     header,
     previousResults -> {
         // Create prompts based on previous answers
         if (shouldShowMorePrompts(previousResults)) {
             return createAdditionalPrompts();
         }
         return null; // No more prompts
     }
 );

Thread Safety

Prompter instances are thread-safe for reading configuration, but prompt execution should be performed on a single thread due to terminal I/O constraints.

Since:
3.30.0
See Also:

  • Method Details

    • newBuilder

      PromptBuilder newBuilder()
      Get a builder for creating prompts.
      Returns:
      a prompt builder

    • prompt

      Map<String,? extends PromptResult<? extends Prompt>> prompt(List<org.jline.utils.AttributedString> header, List<? extends Prompt> prompts) throws IOException, org.jline.reader.UserInterruptException
      Execute a list of prompts and collect user responses.

      This method presents the given prompts to the user in sequence and collects their responses. Each prompt is identified by its name, which serves as the key in the returned result map.

      Example:

      
 List<AttributedString> header = Arrays.asList(
     new AttributedString("Welcome to the setup wizard")
 );

 List<Prompt> prompts = builder.build();
 Map<String, ? extends PromptResult<? extends Prompt>> results =
     prompter.prompt(header, prompts);

 // Access specific results
 ListResult choice = (ListResult) results.get("choice");
 String selectedId = choice.getSelectedId();
      Parameters:
      header - header information to display before the prompts (may be empty)
      prompts - the list of prompts to present to the user in sequence
      Returns:
      a map containing results for each prompt, keyed by prompt name
      Throws:
      IOException - if an I/O error occurs during prompt execution
      org.jline.reader.UserInterruptException - if user interrupt handling is enabled and the user types the interrupt character (Ctrl+C)
      See Also:

    • prompt

      Map<String,? extends PromptResult<? extends Prompt>> prompt(List<org.jline.utils.AttributedString> header, Function<Map<String,? extends PromptResult<? extends Prompt>>,List<? extends Prompt>> promptsProvider) throws IOException
      Execute prompts dynamically based on previous user responses.

      This method enables conditional prompting where subsequent prompts are generated based on the user's previous answers. The promptsProvider function is called repeatedly with the accumulated results until it returns null, indicating no more prompts should be shown.

      Use Cases:

      • Conditional prompts based on user choices
      • Multi-step wizards with branching logic
      • Progressive disclosure of options
      • Validation-dependent follow-up questions

      Example:

      
 Map<String, ? extends PromptResult<? extends Prompt>> results = prompter.prompt(
     header,
     previousResults -> {
         if (previousResults.isEmpty()) {
             // First call - show initial prompts
             return Arrays.asList(
                 builder.createConfirmPrompt()
                     .name("advanced")
                     .message("Show advanced options?")
                     .addPrompt()
             );
         } else if (previousResults.containsKey("advanced")) {
             ConfirmResult advanced = (ConfirmResult) previousResults.get("advanced");
             if (advanced.isConfirmed()) {
                 // Show advanced prompts
                 return Arrays.asList(
                     builder.createInputPrompt()
                         .name("config")
                         .message("Enter configuration:")
                         .addPrompt()
                 );
             }
         }
         return null; // No more prompts
     }
 );
      Parameters:
      header - header information to display before the first set of prompts (may be empty)
      promptsProvider - a function that receives previous results and returns the next list of prompts, or null to indicate no more prompts should be shown
      Returns:
      a map containing results for all executed prompts, keyed by prompt name
      Throws:
      IOException - if an I/O error occurs during prompt execution
      See Also:

    • getTerminal

      org.jline.terminal.Terminal getTerminal()
      Get the terminal associated with this Prompter.
      Returns:
      the terminal

    • getLineReader

      org.jline.reader.LineReader getLineReader()
      Get the line reader associated with this Prompter, if any.
      Returns:
      the line reader, or null if none is associated