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 java.lang.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 long
DEFAULT_AMBIGUOUS_TIMEOUT
Default timeout in milliseconds for ambiguous bindings.static int
KEYMAP_LENGTH
The size of the direct mapping array for ASCII characters.static java.util.Comparator<java.lang.String>
KEYSEQ_COMPARATOR
Comparator for sorting key sequences.
-
Constructor Summary
Constructors Constructor Description KeyMap()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static java.lang.String
alt(char c)
Creates an Alt+key sequence for a single character.static java.lang.String
alt(java.lang.String c)
Creates an Alt+key sequence for a string.void
bind(T function, java.lang.CharSequence keySeq)
Binds a function to a key sequence.void
bind(T function, java.lang.CharSequence... keySeqs)
Binds a function to multiple key sequences.void
bind(T function, java.lang.Iterable<? extends java.lang.CharSequence> keySeqs)
Binds a function to multiple key sequences.void
bindIfNotBound(T function, java.lang.CharSequence keySeq)
Binds a function to a key sequence only if the key sequence is not already bound.static java.lang.String
ctrl(char key)
Creates a Ctrl+key sequence for a character.static java.lang.String
del()
Returns the delete character as a string.static java.lang.String
display(java.lang.String key)
Converts a key sequence to a displayable string representation.static java.lang.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(java.lang.CharSequence keySeq)
Gets the binding for a key sequence.T
getBound(java.lang.CharSequence keySeq, int[] remaining)
Gets the binding for a key sequence, with information about remaining characters.java.util.Map<java.lang.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 java.lang.String
key(org.jline.terminal.Terminal terminal, org.jline.utils.InfoCmp.Capability capability)
Returns the escape sequence for a terminal capability.static java.util.Collection<java.lang.String>
range(java.lang.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 java.lang.String
translate(java.lang.String str)
Translates a string containing special escape sequences into the actual key sequence.void
unbind(java.lang.CharSequence keySeq)
Unbinds a key sequence.void
unbind(java.lang.CharSequence... keySeqs)
-
-
-
Field Detail
-
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 java.util.Comparator<java.lang.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.
-
-
Method Detail
-
display
public static java.lang.String display(java.lang.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 java.lang.String translate(java.lang.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 java.util.Collection<java.lang.String> range(java.lang.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 java.lang.String esc()
Returns the escape character as a string.- Returns:
- the escape character ("\033")
-
alt
public static java.lang.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 java.lang.String alt(java.lang.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 java.lang.String del()
Returns the delete character as a string.- Returns:
- the delete character ("\177")
-
ctrl
public static java.lang.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 java.lang.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 querycapability
- 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 java.util.Map<java.lang.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(java.lang.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 upremaining
- 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(java.lang.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, java.lang.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 bindkeySeq
- the key sequence to bind to
-
bind
public void bind(T function, java.lang.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 bindkeySeqs
- the key sequences to bind to
-
bind
public void bind(T function, java.lang.Iterable<? extends java.lang.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 bindkeySeqs
- the key sequences to bind to
-
bind
public void bind(T function, java.lang.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 unbindkeySeq
- the key sequence to bind to
-
unbind
public void unbind(java.lang.CharSequence... keySeqs)
-
unbind
public void unbind(java.lang.CharSequence keySeq)
Unbinds a key sequence.This removes any binding associated with the given key sequence.
- Parameters:
keySeq
- the key sequence to unbind
-
-