reverse-im.el

reverse-im.el copied to clipboard

• Reverse-im.el

  [[https://melpa.org/#/reverse-im][https://melpa.org/packages/reverse-im-badge.svg]] [[https://github.com/a13/reverse-im.el/stargazers][https://img.shields.io/github/stars/a13/reverse-im.el.svg]] [[https://github.com/a13/reverse-im.el/issues][https://img.shields.io/github/issues/a13/reverse-im.el.svg]] [[https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md][https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg]]

  Overrides [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Translation-Keymaps.html][function-key-map]] for preferred input-method(s) to translate input sequences to English, so we can use Emacs bindings while a non-default system layout is active.

** Quick start

 #+BEGIN_SRC emacs-lisp
   ;; Needed for `:after char-fold' to work
   (use-package char-fold
     :custom
     (char-fold-symmetric t)
     (search-default-mode #'char-fold-to-regexp))

   (use-package reverse-im
     :ensure t ; install `reverse-im' using package.el
     :demand t ; always load it
     :after char-fold ; but only after `char-fold' is loaded
     :bind
     ("M-T" . reverse-im-translate-word) ; fix a word in wrong layout
     :custom
     (reverse-im-char-fold t) ; use lax matching
     (reverse-im-read-char-advice-function #'reverse-im-read-char-include)
     (reverse-im-input-methods '("ukrainian-computer")) ; translate these methods
     :config
     (reverse-im-mode t)) ; turn the mode on
 #+END_SRC

• Installation and usage

** Manual installation

#+BEGIN_SRC emacs-lisp M-x package-install RET reverse-im RET #+END_SRC

** Using use-package /:ensure/

Using provided minor mode instead (see [[Settings][Settings]] for details): #+BEGIN_SRC emacs-lisp (use-package reverse-im :ensure t :custom (reverse-im-input-methods '("ukrainian-computer")) ;; (reverse-im-activate "ukrainian-computer") ; the legacy way :config (reverse-im-mode t)) #+END_SRC

** Usage Reverse-im provides a simple minor mode that activates/deactivates translations for all input methods from ([[https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html][customizable]]) ~reverse-im-input-methods~ list (empty by default).

If you have [[https://github.com/justbur/emacs-which-key][which-key]] installed, you can examine how an input method will be remapped by calling

#+BEGIN_SRC emacs-lisp M-x reverse-im-which-key-show #+END_SRC

*** Manual customization

NB: I highly recommend the ~use-package~ method.

#+BEGIN_SRC emacs-lisp
  ;; standard customization interface, note that this will turn on the mode immediately
  M-x customize-variable RET reverse-im-input-methods RET
  ;; These store list variable in `custom-file'.
  ;; provides auto-completion, one input-method at a time
  M-x reverse-im-add-input-method RET ukrainian-computer RET
#+END_SRC

Since version 0.0.2 all possible bindings with Ctrl, Meta, and Super are translated.
If you want to change it (e.g. you don't use Super)
#+BEGIN_SRC emacs-lisp
  (setq reverse-im-modifiers '(control meta))
  ;; or
  M-x customize-variable RET reverse-im-modifiers RET
#+END_SRC

*** Activation/Deactivation

#+BEGIN_SRC emacs-lisp
  M-x reverse-im-mode RET
  ;; or
  (reverse-im-mode t) ; call with a negative argument to disable
#+END_SRC


Alternatively, you can directly call translation function:
#+BEGIN_SRC emacs-lisp
  (reverse-im-activate "ukrainian-computer")
#+END_SRC

Since version 0.0.3 it supports multiple input method translation:
#+BEGIN_SRC emacs-lisp
  (reverse-im-activate '("ukrainian-computer" "arabic"))
#+END_SRC

If something goes wrong or you just want to turn translation off.

#+BEGIN_SRC emacs-lisp
  M-x reverse-im-deactivate
  ;; or
  (reverse-im-deactivate)
  (reverse-im-deactivate t) ; to reset translation tables cache
#+END_SRC

*** Advising read-char

Reverse-im doesn't work with custom dispatchers like ~org-export~, ~org-capture~ , ~mu4e~ etc. You can try to fix it by advising ~read-char~ and ~read-char-exclusive~. Do it on your own risk since the feature is experimental, hacky and wasn't tested good enough.

There are two versions of advice functions - ~reverse-im-read-char-include~ (the less risky one) translates input iff current command matches (or equals) any element of customizable ~reverse-im-read-char-include-commands~ list, while ~reverse-im-read-char-exclude~ (the more risky one) translates input unless current command does match ~reverse-im-read-char-exclude-commands~.

You can choose which one to use by customizing ~reverse-im-read-char-advice-function~ before ~reverse-im-mode~ is enabled (see Examples above) or by advicing ~read-char~/~read-char-exclusive~ manually.

#+BEGIN_SRC emacs-lisp
  (advice-add #'read-char-exclusive #'reverse-im-read-char-include)
  (advice-add #'read-char #'reverse-im-read-char-include)
#+END_SRC
or
#+BEGIN_SRC emacs-lisp
  (advice-add 'read-char-exclusive #'reverse-im-read-char)
  (advice-add 'read-char #'reverse-im-read-char)
#+END_SRC

If something goes wrong, remove the advices by
#+BEGIN_SRC emacs-lisp
  (advice-remove 'read-char-exclusive #'reverse-im-read-char-include)
  (advice-remove 'read-char #'reverse-im-read-char-include)
#+END_SRC
or
#+BEGIN_SRC emacs-lisp
  (advice-remove 'read-char-exclusive #'reverse-im-read-char)
  (advice-remove 'read-char #'reverse-im-read-char)
#+END_SRC

*** Char folding [[./screenshots/char-fold.png]] Emacs supports [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Lax-Search.html#Lax-Search][Lax Matching During Searching]] and since version 27 you can include your own search substitutions. Reverse-im adds substitutions to ~char-fold-include~ generated using ~reverse-im-char-fold-include~ if ~reverse-im-char-fold~ is set to ~t~ (before ~reverse-im-mode~ is activated).

#+BEGIN_SRC emacs-lisp
  (use-package char-fold
    :custom
    (char-fold-symmetric t)
    (search-default-mode #'char-fold-to-regexp))
#+END_SRC

*** pre-27 versions You can download a new version of char-fold.el manually, or using something like #+BEGIN_SRC emacs-lisp (use-package char-fold :custom (char-fold-symmetric t) (search-default-mode #'char-fold-to-regexp) :quelpa (char-fold :url "https://raw.githubusercontent.com/emacs-mirror/emacs/master/lisp/char-fold.el" :fetcher url)) #+END_SRC

** Interactive translation If you want to fix a region or a word which was typed using incorrect layout, you can use interactive functions ~reverse-im-translate-region~ and ~reverse-im-translate-word~ respectively.

*** [[https://github.com/abo-abo/avy][Avy]] integration

[[./screenshots/avy.png]]

If avy is installed, reverse-im adds ~avy-action-reverse-im-translate~ to ~avy-dispatch-alist~ (bound to ~reverse-im-avy-action-char~, ~?T~ is default one), so it's possible to translate words and lines which are you jumping to. To disable the functionality ~reverse-im-avy-action-char~ should be set to ~nil~.

** Known issues:

• Bindings with AltGr (as Meta) [[https://github.com/a13/reverse-im.el/issues/4#issuecomment-308143947][don't work]] well on Windows.
• Single key shortcuts (i.e. without modifiers) [[https://github.com/a13/reverse-im.el/issues/17][don't work with]] in Hydra and some other modes (~org-agenda~).
• [[https://github.com/a13/reverse-im.el/issues/21][Doesn't]] [[https://github.com/a13/reverse-im.el/issues/6][work]] well for punctuation keys if they are placed on different keys than in English layout.