Class BindingReader


  • public class BindingReader
    extends java.lang.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 Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String lastBinding
      The last key binding that was matched
      protected java.lang.StringBuilder opBuffer
      Buffer for storing characters during key sequence processing
      protected java.util.Deque<java.lang.Integer> pushBackChar
      Stack for pushing back characters that need to be re-read
      protected org.jline.utils.NonBlockingReader reader
      The non-blocking reader used to read input characters
    • Constructor Summary

      Constructors 
      Constructor Description
      BindingReader​(org.jline.utils.NonBlockingReader reader)
      Creates a new BindingReader that reads from the specified NonBlockingReader.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getCurrentBuffer()
      Returns the current contents of the operation buffer.
      java.lang.String getLastBinding()
      Returns the last key binding that was successfully read.
      int peekCharacter​(long timeout)
      Peeks at the next character in the input stream without consuming it.
      <T> T readBinding​(KeyMap<T> keys)
      Read from the input stream and decode an operation from the key map.
      <T> T readBinding​(KeyMap<T> keys, KeyMap<T> local)
      Reads a key binding from the input stream using the specified KeyMaps.
      <T> T readBinding​(KeyMap<T> keys, KeyMap<T> local, boolean block)
      Reads a key binding from the input stream using the specified KeyMaps.
      int readCharacter()
      Reads a single character (Unicode code point) from the input stream.
      int readCharacterBuffered()
      Reads a single character (Unicode code point) from the input stream with buffering.
      java.lang.String readStringUntil​(java.lang.String sequence)
      Reads characters from the input until a specific sequence is encountered.
      void runMacro​(java.lang.String macro)
      Runs a macro by pushing its characters into the input buffer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • reader

        protected final org.jline.utils.NonBlockingReader reader
        The non-blocking reader used to read input characters
      • opBuffer

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

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

        protected java.lang.String lastBinding
        The last key binding that was matched
    • Constructor Detail

      • BindingReader

        public BindingReader​(org.jline.utils.NonBlockingReader reader)
        Creates a new BindingReader that reads from the specified NonBlockingReader.
        Parameters:
        reader - the NonBlockingReader to read characters from
    • Method Detail

      • 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 java.lang.String readStringUntil​(java.lang.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
        java.io.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
        java.io.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:
        java.io.IOError - if an I/O error occurs
      • runMacro

        public void runMacro​(java.lang.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 java.lang.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 java.lang.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