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 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:
    • 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:
    • 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(Terminal terminal, 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