Class ShellBuilder


  • public class ShellBuilder
    extends java.lang.Object
    Builder for creating Shell instances.

    The builder provides a fluent API for configuring the shell:

     Shell shell = Shell.builder()
         .terminal(terminal)              // optional, auto-created if null
         .prompt("myapp> ")               // or .prompt(() -> dynamicPrompt)
         .dispatcher(dispatcher)          // optional, DefaultCommandDispatcher if null
         .groups(group1, group2)          // added to dispatcher
         .parser(parser)                  // optional, DefaultParser by default
         .historyFile(path)               // optional
         .variable(name, value)           // forwarded to LineReader
         .option(Option.X, true)          // forwarded to LineReader
         .onReaderReady((reader, dispatcher) -> { ... })// optional callback
         .build();
     
    Since:
    4.0
    See Also:
    Shell
    • Method Detail

      • terminal

        public ShellBuilder terminal​(org.jline.terminal.Terminal terminal)
        Sets the terminal for the shell. If not specified, a system terminal is created automatically.
        Parameters:
        terminal - the terminal
        Returns:
        this builder
      • prompt

        public ShellBuilder prompt​(java.lang.String prompt)
        Sets a static prompt string.
        Parameters:
        prompt - the prompt string
        Returns:
        this builder
      • prompt

        public ShellBuilder prompt​(java.util.function.Supplier<java.lang.String> promptSupplier)
        Sets a dynamic prompt supplier, called before each line read.
        Parameters:
        promptSupplier - the prompt supplier
        Returns:
        this builder
      • rightPrompt

        public ShellBuilder rightPrompt​(java.lang.String rightPrompt)
        Sets a static right prompt string.
        Parameters:
        rightPrompt - the right prompt string
        Returns:
        this builder
      • rightPrompt

        public ShellBuilder rightPrompt​(java.util.function.Supplier<java.lang.String> rightPromptSupplier)
        Sets a dynamic right prompt supplier, called before each line read.
        Parameters:
        rightPromptSupplier - the right prompt supplier
        Returns:
        this builder
      • groups

        public ShellBuilder groups​(CommandGroup... groups)
        Adds command groups to the dispatcher.
        Parameters:
        groups - the command groups
        Returns:
        this builder
      • parser

        public ShellBuilder parser​(org.jline.reader.Parser parser)
        Sets the line parser. If not specified, a DefaultParser is used.
        Parameters:
        parser - the parser
        Returns:
        this builder
      • historyFile

        public ShellBuilder historyFile​(java.nio.file.Path historyFile)
        Sets the history file path.
        Parameters:
        historyFile - the path to the history file
        Returns:
        this builder
      • variable

        public ShellBuilder variable​(java.lang.String name,
                                     java.lang.Object value)
        Sets a LineReader variable.
        Parameters:
        name - the variable name
        value - the variable value
        Returns:
        this builder
      • option

        public ShellBuilder option​(org.jline.reader.LineReader.Option option,
                                   boolean value)
        Sets a LineReader option.
        Parameters:
        option - the option
        value - the option value
        Returns:
        this builder
      • onReaderReady

        public ShellBuilder onReaderReady​(java.util.function.Consumer<org.jline.reader.LineReader> onReaderReady)
        Sets a callback invoked after the LineReader is created but before Shell.run().

        This is useful for setting up post-reader customizations.

        Parameters:
        onReaderReady - the callback receiving the LineReader
        Returns:
        this builder
        See Also:
        onReaderReady(BiConsumer)
      • onReaderReady

        public ShellBuilder onReaderReady​(java.util.function.BiConsumer<org.jline.reader.LineReader,​CommandDispatcher> onReaderReady)
        Sets a callback invoked after the LineReader is created but before Shell.run().

        This is useful for setting up CommandTailTipWidgets or other post-reader customizations that need access to both the reader and the dispatcher.

         Shell.builder()
             .onReaderReady((reader, dispatcher) -> {
                 new CommandTailTipWidgets(reader, dispatcher, 5).enable();
             })
             .build();
         
        Parameters:
        onReaderReady - the callback receiving the LineReader and CommandDispatcher
        Returns:
        this builder
      • initScript

        public ShellBuilder initScript​(java.io.File initScript)
        Sets the initialization script to execute on startup.
        Parameters:
        initScript - the init script file
        Returns:
        this builder
      • jobManager

        public ShellBuilder jobManager​(JobManager jobManager)
        Sets the job manager for the shell.
        Parameters:
        jobManager - the job manager
        Returns:
        this builder
      • pipelineParser

        public ShellBuilder pipelineParser​(PipelineParser pipelineParser)
        Sets a custom pipeline parser for the shell.

        This allows custom operator registration and subclass overrides of operator matching.

        Parameters:
        pipelineParser - the pipeline parser
        Returns:
        this builder
      • aliasManager

        public ShellBuilder aliasManager​(AliasManager aliasManager)
        Sets the alias manager for the shell.

        When set, aliases are expanded before pipeline parsing, and built-in alias/unalias commands are registered automatically.

        Parameters:
        aliasManager - the alias manager
        Returns:
        this builder
      • historyCommands

        public ShellBuilder historyCommands​(boolean enable)
        Enables or disables built-in history commands (history).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • helpCommands

        public ShellBuilder helpCommands​(boolean enable)
        Enables or disables built-in help commands (help).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • optionCommands

        public ShellBuilder optionCommands​(boolean enable)
        Enables or disables built-in option commands (setopt, unsetopt, setvar).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • highlighter

        public ShellBuilder highlighter​(org.jline.reader.Highlighter highlighter)
        Sets a custom highlighter for the shell's LineReader.
        Parameters:
        highlighter - the highlighter
        Returns:
        this builder
      • commandHighlighter

        public ShellBuilder commandHighlighter​(boolean enable)
        Enables or disables the built-in command-aware syntax highlighter.

        When enabled, known commands are highlighted in bold and unknown commands are highlighted in red.

        Parameters:
        enable - true to enable
        Returns:
        this builder
      • lineExpander

        public ShellBuilder lineExpander​(LineExpander lineExpander)
        Sets the line expander for variable expansion.

        The line expander is called after alias expansion and before pipeline parsing.

        Parameters:
        lineExpander - the line expander
        Returns:
        this builder
      • scriptRunner

        public ShellBuilder scriptRunner​(ScriptRunner scriptRunner)
        Sets the script runner for executing script files.
        Parameters:
        scriptRunner - the script runner
        Returns:
        this builder
      • scriptCommands

        public ShellBuilder scriptCommands​(boolean enable)
        Enables or disables built-in script commands (source, .).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • variableCommands

        public ShellBuilder variableCommands​(boolean enable)
        Enables or disables built-in variable commands (set, unset, export).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • exitCommands

        public ShellBuilder exitCommands​(boolean enable)
        Enables or disables built-in exit commands (exit, quit).
        Parameters:
        enable - true to enable
        Returns:
        this builder
      • exitMessage

        public ShellBuilder exitMessage​(java.lang.String message)
        Sets the message that will be printed to the terminal when the exit command is called. Also enables the exit command if it was disabled.
        Parameters:
        message - The message to be printed upon exit
        Returns:
        this builder
      • build

        public Shell build()
                    throws java.io.IOException
        Builds the Shell instance.

        If no terminal is provided, a system terminal is created. If no dispatcher is provided, a DefaultCommandDispatcher is created. All configured groups are added to the dispatcher.

        Returns:
        a new Shell
        Throws:
        java.io.IOException - if terminal creation fails