search

a13 / reverse-im.el

116 stars 4 forks source link
emacs-keybindings emacs-lisp emacs-packages keyboard-layout

readme

** 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
     ;; cache generated keymaps
     (reverse-im-cache-file (locate-user-emacs-file "reverse-im-cache.el"))
     ;; use lax matching
     (reverse-im-char-fold t)
     (reverse-im-read-char-advice-function #'reverse-im-read-char-include)
     ;; translate these methods
     (reverse-im-input-methods '("ukrainian-computer"))
     :config
     (reverse-im-mode t)) ; turn the mode on
 #+END_SRC

** 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: