Package org.jline.keymap

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 Summary

Fields

Modifier and Type	Field	Description
protected String	lastBinding	The last key binding that was matched
protected final StringBuilder	opBuffer	Buffer for storing characters during key sequence processing
protected final Deque<Integer>	pushBackChar	Stack for pushing back characters that need to be re-read
protected final 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

Modifier and Type	Method	Description
String	getCurrentBuffer()	Returns the current contents of the operation buffer.
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.
String	readStringUntil(String sequence)	Reads characters from the input until a specific sequence is encountered.
void	runMacro(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 Details

reader

protected final org.jline.utils.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(org.jline.utils.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