Class BindingReader
- java.lang.Object
-
- org.jline.keymap.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 aKeyMap
. 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 matchedprotected java.lang.StringBuilder
opBuffer
Buffer for storing characters during key sequence processingprotected java.util.Deque<java.lang.Integer>
pushBackChar
Stack for pushing back characters that need to be re-readprotected NonBlockingReader
reader
The non-blocking reader used to read input characters
-
Constructor Summary
Constructors Constructor Description BindingReader(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.
-
-
-
Field Detail
-
reader
protected final 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(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 theKeyMap.getNomatch()
binding. Unicode (>= 128) characters will be matched toKeyMap.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 bindingslocal
- 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 bindingslocal
- the local KeyMap to check first for bindings, or null if noneblock
- 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 readingjava.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 readingjava.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
-
-