Function: key-translate

key-translate is a byte-compiled function defined in keymap.el.gz.

Signature

(key-translate FROM TO)

Documentation

Translate character FROM to TO on the current terminal.

This function creates a keyboard-translate-table if necessary and then modifies one entry in it.

Both FROM and TO should be specified by strings that satisfy key-valid-p. If TO is nil, remove any existing translation for FROM.

View in manual

Probably introduced at or before Emacs version 30.1.

Source Code

;; Defined in /usr/src/emacs/lisp/keymap.el.gz
(defun key-translate (from to)
  "Translate character FROM to TO on the current terminal.

This function creates a `keyboard-translate-table' if necessary
and then modifies one entry in it.

Both FROM and TO should be specified by strings that satisfy `key-valid-p'.
If TO is nil, remove any existing translation for FROM."
  (declare (compiler-macro
            (lambda (form) (keymap--compile-check from to) form)))
  (keymap--check from)
  (when to
    (keymap--check to))
  (let ((from-key (key-parse from))
        (to-key (and to (key-parse to))))
    (cond
     ((= (length from-key) 0)
      (error "FROM key is empty"))
     ((> (length from-key) 1)
      (error "FROM key %s is not a single key" from)))
    (cond
     ((and to (= (length to-key) 0))
      (error "TO key is empty"))
     ((and to (> (length to-key) 1))
      (error "TO key %s is not a single key" to)))
    (or (char-table-p keyboard-translate-table)
        (setq keyboard-translate-table
              (make-char-table 'keyboard-translate-table nil)))
    (aset keyboard-translate-table
          (aref from-key 0)
          (and to (aref to-key 0)))))