Class BindingReader

java.lang.Object
org.jline.keymap.BindingReader

public class BindingReader extends Object
The BindingReader transforms incoming characters into key bindings.

This class reads characters from a NonBlockingReader and maps them to bindings defined in a KeyMap. It handles multi-character key sequences, such as escape sequences for function keys, by reading ahead when necessary.

Key features include:

  • Support for timeout-based disambiguation of key sequences
  • Buffering of input to handle multi-character sequences
  • Support for running macros (predefined sequences of keystrokes)
  • Access to the current input buffer and last binding read

This class is used by the LineReader to read key bindings for line editing operations.

  • Field Details

    • reader

      protected final NonBlockingReader reader
      The non-blocking reader used to read input characters
    • opBuffer

      protected final StringBuilder opBuffer
      Buffer for storing characters during key sequence processing
    • pushBackChar

      protected final Deque<Integer> pushBackChar
      Stack for pushing back characters that need to be re-read
    • lastBinding

      protected String lastBinding
      The last key binding that was matched
  • Constructor Details

    • BindingReader

      public BindingReader(NonBlockingReader reader)
      Creates a new BindingReader that reads from the specified NonBlockingReader.
      Parameters:
      reader - the NonBlockingReader to read characters from
  • Method Details

    • readBinding

      public <T> T readBinding(KeyMap<T> keys)
      Read from the input stream and decode an operation from the key map. The input stream will be read character by character until a matching binding can be found. Characters that can't possibly be matched to any binding will be send with the KeyMap.getNomatch() binding. Unicode (>= 128) characters will be matched to KeyMap.getUnicode().

      If the current key sequence is ambiguous, i.e. the sequence is bound but it's also a prefix to other sequences, then the KeyMap.getAmbiguousTimeout() timeout will be used to wait for another incoming character. If a character comes, the disambiguation will be done. If the timeout elapses and no character came in, or if the timeout is <= 0, the current bound operation will be returned.

      This method blocks until a complete key binding is read or the end of the stream is reached. If a binding is found in the KeyMap, it is returned. Otherwise, if the Unicode fallback is set in the KeyMap and a Unicode character is read, the Unicode fallback binding is returned.

      Type Parameters:
      T - the type of bindings in the KeyMap
      Parameters:
      keys - the KeyMap to use for mapping input to bindings
      Returns:
      the binding for the read key sequence, or null if the end of stream is reached
    • readBinding

      public <T> T readBinding(KeyMap<T> keys, KeyMap<T> local)
      Reads a key binding from the input stream using the specified KeyMaps.

      This method works like readBinding(KeyMap), but it first checks the local KeyMap for a binding before falling back to the main KeyMap.

      Type Parameters:
      T - the type of bindings in the KeyMaps
      Parameters:
      keys - the main KeyMap to use for mapping input to bindings
      local - the local KeyMap to check first for bindings
      Returns:
      the binding for the read key sequence, or null if the end of stream is reached
    • readBinding

      public <T> T readBinding(KeyMap<T> keys, KeyMap<T> local, boolean block)
      Reads a key binding from the input stream using the specified KeyMaps.

      This method works like readBinding(KeyMap, KeyMap), but it allows specifying whether to block waiting for input or return immediately if no input is available.

      Type Parameters:
      T - the type of bindings in the KeyMaps
      Parameters:
      keys - the main KeyMap to use for mapping input to bindings
      local - the local KeyMap to check first for bindings, or null if none
      block - whether to block waiting for input
      Returns:
      the binding for the read key sequence, or null if no input is available or the end of stream is reached
    • readStringUntil

      public String readStringUntil(String sequence)
      Reads characters from the input until a specific sequence is encountered.

      This method reads characters one by one and accumulates them in a buffer until the specified terminating sequence is found.

      Parameters:
      sequence - the terminating sequence to look for
      Returns:
      the string read up to but not including the terminating sequence, or null if the end of the stream is reached before the sequence is found
    • readCharacter

      public int readCharacter()
      Reads a single character (Unicode code point) from the input stream.

      This method blocks until a character is available or the end of the stream is reached. It properly handles surrogate pairs for Unicode characters outside the BMP (Basic Multilingual Plane).

      Returns:
      the character read, or -1 if the end of the stream is reached
      Throws:
      EndOfFileException - if the stream is closed while reading
      IOError - if an I/O error occurs
    • readCharacterBuffered

      public int readCharacterBuffered()
      Reads a single character (Unicode code point) from the input stream with buffering.

      This method attempts to read multiple characters at once for efficiency, storing them in an internal buffer. It properly handles surrogate pairs for Unicode characters outside the BMP (Basic Multilingual Plane).

      Returns:
      the character read, or -1 if the end of the stream is reached
      Throws:
      EndOfFileException - if the stream is closed while reading
      IOError - if an I/O error occurs
    • peekCharacter

      public int peekCharacter(long timeout)
      Peeks at the next character in the input stream without consuming it.

      This method waits up to the specified timeout for a character to become available. If a character is available, it is returned but not consumed. If no character is available within the timeout, -2 is returned.

      Parameters:
      timeout - the maximum time to wait in milliseconds
      Returns:
      the next character, -1 if the end of the stream is reached, or -2 if the timeout expires
      Throws:
      IOError - if an I/O error occurs
    • runMacro

      public void runMacro(String macro)
      Runs a macro by pushing its characters into the input buffer.

      This method allows simulating keystrokes by pushing the characters of the macro string into the input buffer. These characters will be read before any actual input from the underlying reader.

      Parameters:
      macro - the string of characters to push into the input buffer
    • getCurrentBuffer

      public String getCurrentBuffer()
      Returns the current contents of the operation buffer.

      The operation buffer contains the characters of the current key sequence being processed. This is useful for debugging or displaying the current input state.

      Returns:
      the current operation buffer as a string
    • getLastBinding

      public String getLastBinding()
      Returns the last key binding that was successfully read.

      This method returns the string representation of the last key sequence that was successfully mapped to a binding. This can be useful for displaying the binding to the user or for implementing key sequence chaining.

      Returns:
      the last key binding, or null if no binding has been read yet