Package org.jline.keymap

Class KeyMap<T>

java.lang.Object

org.jline.keymap.KeyMap<T>

Type Parameters:

T - the type of objects to which key sequences are bound

public class KeyMap<T>
extends Object

The KeyMap class maps keyboard input sequences to operations or actions.

KeyMap is a core component of JLine's input handling system, providing the ability to bind specific key sequences (like Ctrl+A, Alt+F, or multi-key sequences) to arbitrary operations represented by objects of type T.

Key features include:

• Support for single-key and multi-key sequences
• Special handling for Unicode characters not explicitly bound
• Timeout handling for ambiguous bindings (e.g., Escape key vs. Alt combinations)
• Utility methods for creating common key sequences (Ctrl, Alt, etc.)

This class is used extensively by the LineReader to implement customizable key bindings for line editing operations.

Since:

2.6

Field Summary

Fields

Modifier and Type	Field	Description
static final long	DEFAULT_AMBIGUOUS_TIMEOUT	Default timeout in milliseconds for ambiguous bindings.
static final int	KEYMAP_LENGTH	The size of the direct mapping array for ASCII characters.
static final Comparator<String>	KEYSEQ_COMPARATOR	Comparator for sorting key sequences.

Constructor Summary

Constructors

Constructor	Description
KeyMap()

Method Summary

Modifier and Type	Method	Description
static String	alt(char c)	Creates an Alt+key sequence for a single character.
static String	alt(String c)	Creates an Alt+key sequence for a string.
void	bind(T function, CharSequence keySeq)	Binds a function to a key sequence.
void	bind(T function, CharSequence... keySeqs)	Binds a function to multiple key sequences.
void	bind(T function, Iterable<? extends CharSequence> keySeqs)	Binds a function to multiple key sequences.
void	bindIfNotBound(T function, CharSequence keySeq)	Binds a function to a key sequence only if the key sequence is not already bound.
static String	ctrl(char key)	Creates a Ctrl+key sequence for a character.
static String	del()	Returns the delete character as a string.
static String	display(String key)	Converts a key sequence to a displayable string representation.
static String	esc()	Returns the escape character as a string.
long	getAmbiguousTimeout()	Gets the timeout for ambiguous key bindings in milliseconds.
T	getAnotherKey()	Gets the binding for the "another key" action.
T	getBound(CharSequence keySeq)	Gets the binding for a key sequence.
T	getBound(CharSequence keySeq, int[] remaining)	Gets the binding for a key sequence, with information about remaining characters.
Map<String,T>	getBoundKeys()	Returns a map of all bound key sequences and their associated bindings.
T	getNomatch()	Gets the binding for input sequences that don't match any known binding.
T	getUnicode()	Gets the binding for Unicode characters that don't have explicit bindings.
static String	key(org.jline.terminal.Terminal terminal, org.jline.utils.InfoCmp.Capability capability)	Returns the escape sequence for a terminal capability.
static Collection<String>	range(String range)	Generates a collection of key sequences from a range specification.
void	setAmbiguousTimeout(long ambiguousTimeout)	Sets the timeout for ambiguous key bindings in milliseconds.
void	setNomatch(T nomatch)	Sets the binding for input sequences that don't match any known binding.
void	setUnicode(T unicode)	Sets the binding for Unicode characters that don't have explicit bindings.
static String	translate(String str)	Translates a string containing special escape sequences into the actual key sequence.
void	unbind(CharSequence keySeq)	Unbinds a key sequence.
void	unbind(CharSequence... keySeqs)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

KEYMAP_LENGTH

public static final int KEYMAP_LENGTH

The size of the direct mapping array for ASCII characters. Characters with code points below this value are mapped directly.

See Also:

• Constant Field Values

DEFAULT_AMBIGUOUS_TIMEOUT

public static final long DEFAULT_AMBIGUOUS_TIMEOUT

Default timeout in milliseconds for ambiguous bindings.

This is used when a prefix of a multi-character binding is also bound to an action. For example, if both Escape and Escape+[A are bound, the reader will wait this amount of time after receiving Escape to determine if it's a standalone Escape or the beginning of the Escape+[A sequence.

See Also:

• Constant Field Values

KEYSEQ_COMPARATOR

public static final Comparator<String> KEYSEQ_COMPARATOR

Comparator for sorting key sequences.

This comparator sorts key sequences first by length, then lexicographically. It's useful for ensuring that longer key sequences are checked before their prefixes.

Constructor Details

KeyMap

public KeyMap()

Method Details

display

public static String display(String key)

Converts a key sequence to a displayable string representation.

This method formats control characters, escape sequences, and other special characters in a readable way, similar to how they might be represented in configuration files.

Parameters:

key - the key sequence to display

Returns:

a readable string representation of the key sequence

translate

public static String translate(String str)

Translates a string containing special escape sequences into the actual key sequence.

This method handles escape sequences like ^A (Ctrl+A), \e (Escape), \C-a (Ctrl+A), \M-a (Alt+A), etc., converting them to the actual character sequences they represent.

Parameters:

str - the string with escape sequences to translate

Returns:

the translated key sequence

range

public static Collection<String> range(String range)

Generates a collection of key sequences from a range specification.

This method takes a range specification like "a-z" or "\C-a-\C-z" and returns a collection of all key sequences in that range.

Parameters:

range - the range specification

Returns:

a collection of key sequences in the specified range, or null if the range is invalid

esc

public static String esc()

Returns the escape character as a string.

Returns:

the escape character ("\033")

alt

public static String alt(char c)

Creates an Alt+key sequence for a single character.

This is equivalent to pressing the Alt key and a character key simultaneously. Internally, this is represented as the escape character followed by the character.

Parameters:

c - the character to combine with Alt

Returns:

the Alt+character key sequence

alt

public static String alt(String c)

Creates an Alt+key sequence for a string.

This is equivalent to pressing the Alt key and typing a sequence of characters. Internally, this is represented as the escape character followed by the string.

Parameters:

c - the string to combine with Alt

Returns:

the Alt+string key sequence

del

public static String del()

Returns the delete character as a string.

Returns:

the delete character ("\177")

ctrl

public static String ctrl(char key)

Creates a Ctrl+key sequence for a character.

This is equivalent to pressing the Ctrl key and a character key simultaneously. For example, Ctrl+A is represented as the character with code point 1.

Parameters:

key - the character to combine with Ctrl

Returns:

the Ctrl+key sequence

key

public static String key(org.jline.terminal.Terminal terminal,
 org.jline.utils.InfoCmp.Capability capability)

Returns the escape sequence for a terminal capability.

This method retrieves the escape sequence for special keys like arrow keys, function keys, etc., based on the terminal's capabilities.

Parameters:

terminal - the terminal to query

capability - the capability to retrieve

Returns:

the escape sequence for the specified capability

getUnicode

public T getUnicode()

Gets the binding for Unicode characters that don't have explicit bindings.

This is used as a fallback for characters that don't have specific bindings in the keymap. Typically, this might be set to a function that inserts the character into the line buffer.

Returns:

the binding for Unicode characters

setUnicode

public void setUnicode(T unicode)

Sets the binding for Unicode characters that don't have explicit bindings.

Parameters:

unicode - the binding for Unicode characters

getNomatch

public T getNomatch()

Gets the binding for input sequences that don't match any known binding.

This is used as a fallback when an input sequence doesn't match any binding in the keymap.

Returns:

the binding for non-matching sequences

setNomatch

public void setNomatch(T nomatch)

Sets the binding for input sequences that don't match any known binding.

Parameters:

nomatch - the binding for non-matching sequences

getAmbiguousTimeout

public long getAmbiguousTimeout()

Gets the timeout for ambiguous key bindings in milliseconds.

This timeout is used when a prefix of a multi-character binding is also bound to an action. The reader will wait this amount of time after receiving the prefix to determine if more characters are coming.

Returns:

the ambiguous binding timeout in milliseconds

setAmbiguousTimeout

public void setAmbiguousTimeout(long ambiguousTimeout)

Sets the timeout for ambiguous key bindings in milliseconds.

Parameters:

ambiguousTimeout - the ambiguous binding timeout in milliseconds

getAnotherKey

public T getAnotherKey()

Gets the binding for the "another key" action.

This binding is returned when a key sequence doesn't match any binding but is a prefix of a longer binding. It's typically used to implement incremental search or other features that need to process each character as it's typed.

Returns:

the "another key" binding

getBoundKeys

public Map<String,T> getBoundKeys()

Returns a map of all bound key sequences and their associated bindings.

The map is sorted by key sequence using the KEYSEQ_COMPARATOR.

Returns:

a map of bound key sequences to their bindings

getBound

public T getBound(CharSequence keySeq,
 int[] remaining)

Gets the binding for a key sequence, with information about remaining characters.

This method returns the binding for the given key sequence, if one exists. It also provides information about how much of the key sequence was consumed in the remaining parameter:

• If remaining[0] is -1, the entire sequence was consumed
• If remaining[0] is positive, that many characters at the end were not consumed
• If remaining[0] is 0, the sequence was consumed but no binding was found

Parameters:

keySeq - the key sequence to look up

remaining - array of length at least 1 to receive information about remaining characters

Returns:

the binding for the key sequence, or null if no binding was found

getBound

public T getBound(CharSequence keySeq)

Gets the binding for a key sequence.

This method returns the binding for the given key sequence only if the entire sequence is consumed. If the sequence is a prefix of a longer binding or doesn't match any binding, null is returned.

Parameters:

keySeq - the key sequence to look up

Returns:

the binding for the key sequence, or null if no binding was found or the sequence is a prefix

bindIfNotBound

public void bindIfNotBound(T function,
 CharSequence keySeq)

Binds a function to a key sequence only if the key sequence is not already bound.

This method is useful for setting up default bindings that should not override user-defined bindings.

Parameters:

function - the function to bind

keySeq - the key sequence to bind to

bind

public void bind(T function,
 CharSequence... keySeqs)

Binds a function to multiple key sequences.

This is a convenience method that calls bind(Object, CharSequence) for each key sequence.

Parameters:

function - the function to bind

keySeqs - the key sequences to bind to

bind

public void bind(T function,
 Iterable<? extends CharSequence> keySeqs)

Binds a function to multiple key sequences.

This is a convenience method that calls bind(Object, CharSequence) for each key sequence in the iterable.

Parameters:

function - the function to bind

keySeqs - the key sequences to bind to

bind

public void bind(T function,
 CharSequence keySeq)

Binds a function to a key sequence.

If the function is null, the key sequence is unbound.

Parameters:

function - the function to bind, or null to unbind

keySeq - the key sequence to bind to

unbind

public void unbind(CharSequence... keySeqs)

unbind

public void unbind(CharSequence keySeq)

Unbinds a key sequence.

This removes any binding associated with the given key sequence.

Parameters:

keySeq - the key sequence to unbind