Class BindingReader
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
FieldsModifier and TypeFieldDescriptionprotected String
The last key binding that was matchedprotected final StringBuilder
Buffer for storing characters during key sequence processingStack for pushing back characters that need to be re-readprotected final NonBlockingReader
The non-blocking reader used to read input characters -
Constructor Summary
ConstructorsConstructorDescriptionBindingReader
(NonBlockingReader reader) Creates a new BindingReader that reads from the specified NonBlockingReader. -
Method Summary
Modifier and TypeMethodDescriptionReturns the current contents of the operation buffer.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
Reads a single character (Unicode code point) from the input stream.int
Reads a single character (Unicode code point) from the input stream with buffering.readStringUntil
(String sequence) Reads characters from the input until a specific sequence is encountered.void
Runs a macro by pushing its characters into the input buffer.
-
Field Details
-
reader
The non-blocking reader used to read input characters -
opBuffer
Buffer for storing characters during key sequence processing -
pushBackChar
Stack for pushing back characters that need to be re-read -
lastBinding
The last key binding that was matched
-
-
Constructor Details
-
BindingReader
Creates a new BindingReader that reads from the specified NonBlockingReader.- Parameters:
reader
- the NonBlockingReader to read characters from
-
-
Method Details
-
readBinding
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
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
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
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 readingIOError
- 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 readingIOError
- 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
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
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
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
-