Class 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)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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.

    • Constructor Detail

      • KeyMap

        public KeyMap()
    • 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 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 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 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​(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 bind
        keySeq - 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 bind
        keySeqs - 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 bind
        keySeqs - 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 unbind
        keySeq - 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