emacs
/
evil-collection
mirror of https://github.com/jojojames/evil-collection.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Indent everything using emacs formatter

This commit is contained in:
James Nguyen 2022-04-14 13:30:05 -04:00
parent 78441dd47f
commit ee8b991f3e
1 changed files with 441 additions and 442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

423
readme.org
View File

@ -13,27 +13,27 @@ more.
** Preliminaries
1. ~evil-overriding-maps~ is assumed as ~nil~ to reduce redundant ~w/W/l/f/t~
1. ~evil-overriding-maps~ is assumed as ~nil~ to reduce redundant ~w/W/l/f/t~
etc evil bindings. See [[https://github.com/emacs-evil/evil-collection/pull/501][Fixup Info-mode]] for example.
** Goals
1. Reduce context switching: As soon as "moving around" gets hardwired
1. Reduce context switching: As soon as "moving around" gets hardwired
to ~<hjkl>~, it becomes frustratingly inefficient not to have it everywhere.
2. Community work: setting up bindings is tremendous work and joining force can
2. Community work: setting up bindings is tremendous work and joining force can
only save hours for all of Evil users out there. While not everyone may agree
on the chosen bindings, it helps to have something to start with rather than
nothing at all. In the end, users are free to override a subset of the proposed
bindings to best fit their needs.
3. Consistency: Having all bindings defined in one place allows for enforcing
3. Consistency: Having all bindings defined in one place allows for enforcing
consistency across special modes and coordinating the community work to define a
reference implementation.
** Installation
- Get the package, either from MELPA:
- Get the package, either from MELPA:
: M-x package-install RET evil-collection RET
@ -70,17 +70,17 @@ more.
For example:
#+begin_src emacs-lisp :tangle yes
(setq evil-want-integration t) ;; This is optional since it's already set to t by default.
(setq evil-want-keybinding nil)
(require 'evil)
(when (require 'evil-collection nil t)
(setq evil-want-integration t) ;; This is optional since it's already set to t by default.
(setq evil-want-keybinding nil)
(require 'evil)
(when (require 'evil-collection nil t)
(evil-collection-init))
#+end_src
Here's another full TLDR ~use-package~ example.
#+begin_src emacs-lisp :tangle yes
(use-package evil
(use-package evil
:ensure t
:init
(setq evil-want-integration t) ;; This is optional since it's already set to t by default.
@ -88,7 +88,7 @@ more.
:config
(evil-mode 1))
(use-package evil-collection
(use-package evil-collection
:after evil
:ensure t
:config
@ -100,42 +100,42 @@ more.
** Configuration
Modify ~evil-collection-mode-list~ to disable or add any modes that should be evilified by ~evil-collection~.
Modify ~evil-collection-mode-list~ to disable or add any modes that should be evilified by ~evil-collection~.
| Variable | Default | Description |
|--------------------------------------------+---------+-------------------------------------------------------------------|
| evil-collection-calendar-want-org-bindings | nil | Set up Org functions in calendar keymap. |
| evil-collection-outline-bind-tab-p | nil | Enable <tab>-based bindings in Outline mode. |
| evil-collection-term-sync-state-and-mode-p | t | Synchronize insert/normal state with char/line-mode in term-mode. |
| evil-collection-setup-minibuffer | nil | Set up Vim style bindings in the minibuffer. |
| evil-collection-setup-debugger-keys | t | Set up debugger keys for certain modes. |
| evil-collection-want-unimpaired-p | t | Set up unimpaired bindings globally. |
| evil-collection-want-find-usages-bindings | t | Bind -find references-, etc to various modes. |
| Variable | Default | Description |
|--------------------------------------------+---------+-------------------------------------------------------------------|
| evil-collection-calendar-want-org-bindings | nil | Set up Org functions in calendar keymap. |
| evil-collection-outline-bind-tab-p | nil | Enable <tab>-based bindings in Outline mode. |
| evil-collection-term-sync-state-and-mode-p | t | Synchronize insert/normal state with char/line-mode in term-mode. |
| evil-collection-setup-minibuffer | nil | Set up Vim style bindings in the minibuffer. |
| evil-collection-setup-debugger-keys | t | Set up debugger keys for certain modes. |
| evil-collection-want-unimpaired-p | t | Set up unimpaired bindings globally. |
| evil-collection-want-find-usages-bindings | t | Bind -find references-, etc to various modes. |
For example, if you want to enable Evil in the minibuffer, you'll have to turn it on
explicitly by customizing ~evil-collection-setup-minibuffer~ to ~t~.
Some minibuffer-related packages such as Helm rely on this option.
For example, if you want to enable Evil in the minibuffer, you'll have to turn it on
explicitly by customizing ~evil-collection-setup-minibuffer~ to ~t~.
Some minibuffer-related packages such as Helm rely on this option.
~use-package~ example:
~use-package~ example:
#+begin_src emacs-lisp :tangle yes
#+begin_src emacs-lisp :tangle yes
(use-package evil-collection
:custom (evil-collection-setup-minibuffer t)
:init (evil-collection-init))
#+end_src
#+end_src
** Guidelines
The following rules serve as guiding principles to define the set of standard
Evil bindings for various modes. Since special modes are by definition
structurally incomparable, those rules cannot be expected to be applied
universally.
The following rules serve as guiding principles to define the set of standard
Evil bindings for various modes. Since special modes are by definition
structurally incomparable, those rules cannot be expected to be applied
universally.
The rules are more-or-less sorted by priority.
The rules are more-or-less sorted by priority.
1. Don't bind anything to ~:~ nor ~<escape>~.
1. Don't bind anything to ~:~ nor ~<escape>~.
2. Keep the movement keys when possible and sensible.
2. Keep the movement keys when possible and sensible.
- ~h~, ~j~, ~k~, ~l~
- ~w~, ~W~, ~b~, ~B~, ~e~, ~E~, ~ge~, ~gE~
@ -148,22 +148,22 @@ more.
- ~+~, ~-~, ~0~, ~^~, ~$~
- ~C-i~, ~C-o~
3. Keep the yanking and register keys when possible and sensible.
3. Keep the yanking and register keys when possible and sensible.
- ~y~, ~Y~
- ="=
4. Keep the search keys when possible and sensible.
4. Keep the search keys when possible and sensible.
- ~/~, ~?~
- ~#~, ~*~
5. Keep the mark keys when possible and sensible.
5. Keep the mark keys when possible and sensible.
- ~m~
- ='=, =~=
6. Keep the windowing keys when possible and sensible.
6. Keep the windowing keys when possible and sensible.
- ~H~, ~L~, ~M~
- ~C-e~, ~C-y~
@ -172,7 +172,7 @@ more.
- ~C-w~-prefixed bindings.
- Some ~z~-prefixed bindings (see below).
7. The following keys are free when insert state does not make sense in the
7. The following keys are free when insert state does not make sense in the
current mode:
- ~a~, ~A~, ~i~, ~I~
@ -186,17 +186,17 @@ more.
Any of those keys can be set to be a prefix key.
8. Prefix keys: ~g~ and ~z~ are the ubiquitous prefix keys.
8. Prefix keys: ~g~ and ~z~ are the ubiquitous prefix keys.
- ~g~ generally stands for "go" and is best used for movements.
- ~z~ is used for scrolling, folding, spell-checking and more.
9. Macro and action keys
9. Macro and action keys
- ~@~, ~q~
- ~.~
10. Ensure terminal compatibility without sacrificing GUI key bindings.
10. Ensure terminal compatibility without sacrificing GUI key bindings.
- Tab key
- Tab key is recognized as ~<tab>~ in GUI and ~TAB~ in terminal.
@ -216,17 +216,17 @@ more.
** Rationale
Many special modes share the same set of similar actions. Those actions should
share the same bindings across all modes whenever feasible.
Many special modes share the same set of similar actions. Those actions should
share the same bindings across all modes whenever feasible.
*** Motion (~[~, ~]~, ~{~, ~}~, ~(~, ~)~, ~gj~, ~gk~, ~C-j~, ~C-k~)
- ~[~ and ~]~: Use ~[-~ and ~]-~ prefixed keys for navigation between sections.
- ~[~ and ~]~: Use ~[-~ and ~]-~ prefixed keys for navigation between sections.
If the mode makes no difference between the end of a section and the beginning
of the next, use ~[~ and ~]~.
- ~gj~ and ~gk~: synonym for ~[~ and ~]~. That's what [[evilmagit][evil-magit]] does.
- ~gj~ and ~gk~: synonym for ~[~ and ~]~. That's what [[evilmagit][evil-magit]] does.
*Question:* Should ~gj~ / ~gk~ rather be synonyms for ~C-j~ / ~C-k~? They cannot
emulate the behaviour of ~[]~ or ~][~.
@ -262,23 +262,23 @@ more.
*** Quitting (~q~, ~ZQ~, ~ZZ~)
In Vim, ~q~ is for recording macros. Vim quits with ~ZZ~ or ~ZQ~. In most
Emacs special modes, it stands for quitting while macros are recorded/played
with ~<f3>~ and ~<f4>~.
In Vim, ~q~ is for recording macros. Vim quits with ~ZZ~ or ~ZQ~. In most
Emacs special modes, it stands for quitting while macros are recorded/played
with ~<f3>~ and ~<f4>~.
A good rule of thumb would be:
A good rule of thumb would be:
- Always bind ~q~, ~ZZ~ and ~ZQ~ to the mode specific quitting functions. If there is none,
- Always bind ~q~, ~ZZ~ and ~ZQ~ to the mode specific quitting functions. If there is none,
- Bind ~q~ and ~ZZ~ to ~quit-window~
- Bind ~q~ and ~ZZ~ to ~quit-window~
- Bind ~ZQ~ to ~evil-quit~
- Bind ~ZQ~ to ~evil-quit~
- If macros don't make sense in current mode, then ~@~ is available.
- If macros don't make sense in current mode, then ~@~ is available.
*** Refreshing / Reverting (~gr~)
- ~gr~ is used for refreshing in [[evilmagit][evil-magit]], [[evilmu4e][evil-mu4e]], and some Spacemacs
- ~gr~ is used for refreshing in [[evilmagit][evil-magit]], [[evilmu4e][evil-mu4e]], and some Spacemacs
configurations (org-agenda and neotree among others).
~C-l~ is traditionally used to refresh the terminal screen. Since there does
@ -286,28 +286,28 @@ more.
*** Marking
~m~ defaults to ~evil-set-marker~ which might not be very useful in special
modes.
='= can still be used as it can jump to other buffers.
~m~ defaults to ~evil-set-marker~ which might not be very useful in special
modes.
='= can still be used as it can jump to other buffers.
- ~m~: Mark or toggle mark, depending on what the mode offers.
- ~m~: Mark or toggle mark, depending on what the mode offers.
In visual mode, always mark.
With a numeric argument, toggle mark on that many following lines.
- ~u~: Unmark current selection.
- ~u~: Unmark current selection.
- ~U~: Unmark all.
- ~U~: Unmark all.
- =~=: Toggle all marks. This mirrors the "invert-char" Vim command bound to =~=
- =~=: Toggle all marks. This mirrors the "invert-char" Vim command bound to =~=
by default.
- ~M~: Mark all, if available. Otherwise use =U~=.
- ~M~: Mark all, if available. Otherwise use =U~=.
- ~*~: Mark-prefix or mark all if current mode has no prefix. ~*~ is traditionally a wildcard.
- ~*~: Mark-prefix or mark all if current mode has no prefix. ~*~ is traditionally a wildcard.
- ~%~: Mark regexp.
- ~%~: Mark regexp.
- ~x~: Execute action on marks. This mirrors Dired's binding of ~x~.
- ~x~: Execute action on marks. This mirrors Dired's binding of ~x~.
If ~*~ is used for marking, then ~#~ is free.
@ -315,20 +315,20 @@ more.
*** Selecting / Filtering / Narrowing / Searching
- ~s~ and ~S~ seem to be used in some places like [[mu4e][mu4e]].
- ~s~ and ~S~ seem to be used in some places like [[mu4e][mu4e]].
- ~s~: [s]elect/[s]earch/filter candidates according to a pattern.
- ~S~: Remove filter and select all.
- ~=~ is usually free and its significance is obvious. It's taken for zooming though.
- ~=~ is usually free and its significance is obvious. It's taken for zooming though.
- ~|~ is not free but the pipe symbolic is very tantalizing.
- ~|~ is not free but the pipe symbolic is very tantalizing.
*** Sorting
- ~o~: Change the sort [o]rder.
- ~O~: Sort in reverse order.
- ~o~: Change the sort [o]rder.
- ~O~: Sort in reverse order.
There is no real consensus around which key to bind to sorting. What others do by default:
@ -344,37 +344,37 @@ more.
*** Go to definition (~gd~, ~gD~)
- ~gd~: [g]o to [d]efinition. This is mostly for programming modes.
- ~gd~: [g]o to [d]efinition. This is mostly for programming modes.
If there's a corresponding 'pop' action, use ~C-t~.
*** Go to references, etc (~gr~, ~gA~)
When ~evil-collection-want-find-usages-bindings~ is set to t:
When ~evil-collection-want-find-usages-bindings~ is set to t:
- ~gr~: [g] to [r]eferences. This binding is also used for refresh/reverting
- ~gr~: [g] to [r]eferences. This binding is also used for refresh/reverting
modes in non programming modes but is usually empty for programming modes.
- ~gA~: [g]o to [A]ssignments.
- ~gA~: [g]o to [A]ssignments.
- Additional bindings:
- Additional bindings:
There may be additional binds under this category. Please file a Pull Request if so.
*** Go to current entity
- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
Bind only if more relevant than ~evil-repeat~.
*** Open thing at point (~RET~, ~S-RET~, ~M-RET~, ~go~, ~gO~)
- ~RET~, ~S-RET~, ~M-RET~: Open thing at point in current window, open in other
- ~RET~, ~S-RET~, ~M-RET~: Open thing at point in current window, open in other
window and display in other window respectively. The latter is like the
former with the focus remaining on the current window.
- ~go~, ~gO~: When available, same as ~S-RET~ and ~M-RET~ respectively. This is
- ~go~, ~gO~: When available, same as ~S-RET~ and ~M-RET~ respectively. This is
useful in terminals where ~S-RET~ and ~M-RET~ might not work.
*** Emacs-style jumping (~J~)
- ~J~: [[mu4e][mu4e]] has ~j~ and [[evil-mu4e][evil-mu4e]] uses ~J~, so we use ~J~ too.
- ~J~: [[mu4e][mu4e]] has ~j~ and [[evil-mu4e][evil-mu4e]] uses ~J~, so we use ~J~ too.
Some special modes like [[mu4e][mu4e]] and ibuffer offer to "jump" to a different
buffer. This sometimes depends on the thing at point.
@ -384,51 +384,51 @@ more.
*** Browse URL (~gx~)
~gx~: go to URL. This is a default Vim binding.
~gx~: go to URL. This is a default Vim binding.
*** Help (~?~)
- ~g?~ : is the standard key for help related commands.
- ~?~ in places where backward search is not very useful.
- ~g?~ : is the standard key for help related commands.
- ~?~ in places where backward search is not very useful.
*** History browsing (~C-n~, ~C-p~)
~C-n~ and ~C-p~ are standard bindings to browse the history elements.
~C-n~ and ~C-p~ are standard bindings to browse the history elements.
*** Bookmarking
?
?
*** REPL (~gz~)
If the mode has a Go To REPL-type command, set it to ~gz~.
If the mode has a Go To REPL-type command, set it to ~gz~.
*** Zooming (~+~, ~-~, ~=~, ~0~)
- ~+~ and ~-~ have obvious meanings.
- ~+~ and ~-~ have obvious meanings.
- ~0~ has a somewhat intuitive meaning, plus it is next to ~+~ and ~-~ on QWERTY.
- ~0~ has a somewhat intuitive meaning, plus it is next to ~+~ and ~-~ on QWERTY.
- ~=~ is useful as a synonym for ~+~ because it is the unshifted key of ~+~ on QWERTY.
- ~=~ is useful as a synonym for ~+~ because it is the unshifted key of ~+~ on QWERTY.
*** Debugging
When debugging is on, debugger keys takes the most precedence.
When debugging is on, debugger keys takes the most precedence.
These keys will be set when there's an available command for them.
These keys will be set when there's an available command for them.
- ~n~ : Step Over
- ~i~ : Step Into
- ~o~ : Step Out
- ~c~ : Continue/Resume Execution
- ~L~ : Locals
- ~t~ : Tracing
- ~q~ : Quit Debugging
- ~H~ : Continue until Point
- ~e~ : Evaluate Expression
- ~b~ : Set Breakpoint
- ~u~ : Unset Breakpoint
- ~>~ : Navigate to Next Frame
- ~<~ : Navigate to Previous Frame
- ~g?~ : Help
- ~J~ : Jump to debugger location
- ~R~ : Restart
- ~n~ : Step Over
- ~i~ : Step Into
- ~o~ : Step Out
- ~c~ : Continue/Resume Execution
- ~L~ : Locals
- ~t~ : Tracing
- ~q~ : Quit Debugging
- ~H~ : Continue until Point
- ~e~ : Evaluate Expression
- ~b~ : Set Breakpoint
- ~u~ : Unset Breakpoint
- ~>~ : Navigate to Next Frame
- ~<~ : Navigate to Previous Frame
- ~g?~ : Help
- ~J~ : Jump to debugger location
- ~R~ : Restart
For debugging outside of debugger being on (e.g. setting initial breakpoints),
we use similar keys to [[https://github.com/realgud/realgud][realgud]].
@ -441,31 +441,31 @@ more.
- ~f11~ Step Into
- ~S-f11~ Step Out
*** Editable Buffers
For buffers where insert-state doesn't make sense but buffer can be edited,
(e.g. wdired or wgrep), pressing ~i~ will change into editable state.
For buffers where insert-state doesn't make sense but buffer can be edited,
(e.g. wdired or wgrep), pressing ~i~ will change into editable state.
When this editable state is turned on,
When this editable state is turned on,
~ZQ~ will abort and clear any changes.
~ZZ~ will finish and save any changes.
~ESC~ will exit editable state.
~ZQ~ will abort and clear any changes.
~ZZ~ will finish and save any changes.
~ESC~ will exit editable state.
*** :q/:wq/etc
Modes with commands that can be bound to :q/:wq/etc will have those keys remapped.
Modes with commands that can be bound to :q/:wq/etc will have those keys remapped.
** Key Translation
~evil-collection-translate-key~ allows binding a key to the definition of
another key in the same keymap (comparable to how Vim's keybindings work). Its
arguments are the ~states~ and ~keymaps~ to bind/look up the key(s) in followed
optionally by keyword arguments (currently only ~:destructive~) and
key/replacement pairs. ~states~ should be nil for non-evil keymaps, and both
~states~ and ~keymaps~ can be a single symbol or a list of symbols.
~evil-collection-translate-key~ allows binding a key to the definition of
another key in the same keymap (comparable to how Vim's keybindings work). Its
arguments are the ~states~ and ~keymaps~ to bind/look up the key(s) in followed
optionally by keyword arguments (currently only ~:destructive~) and
key/replacement pairs. ~states~ should be nil for non-evil keymaps, and both
~states~ and ~keymaps~ can be a single symbol or a list of symbols.
This function can be useful for making key swaps/cycles en masse. For example,
someone who uses an alternate keyboard layout may want to retain the ~hjkl~
positions for directional movement in dired, the calendar, etc.
This function can be useful for making key swaps/cycles en masse. For example,
someone who uses an alternate keyboard layout may want to retain the ~hjkl~
positions for directional movement in dired, the calendar, etc.
Here's an example for Colemak of making swaps in a single keymap:
#+begin_src emacs-lisp
(evil-collection-translate-key nil 'evil-motion-state-map
Here's an example for Colemak of making swaps in a single keymap:
#+begin_src emacs-lisp
(evil-collection-translate-key nil 'evil-motion-state-map
;; colemak hnei is qwerty hjkl
"n" "j"
"e" "k"
@ -474,12 +474,12 @@ more.
"j" "e"
"k" "n"
"l" "i")
#+end_src
#+end_src
Here's an example of using ~evil-collection-setup-hook~ to cycle the keys for
all modes in ~evil-collection-mode-list~:
#+begin_src emacs-lisp
(defun my-hjkl-rotation (_mode mode-keymaps &rest _rest)
Here's an example of using ~evil-collection-setup-hook~ to cycle the keys for
all modes in ~evil-collection-mode-list~:
#+begin_src emacs-lisp
(defun my-hjkl-rotation (_mode mode-keymaps &rest _rest)
(evil-collection-translate-key 'normal mode-keymaps
"n" "j"
"e" "k"
@ -488,43 +488,43 @@ more.
"k" "n"
"l" "i"))
;; called after evil-collection makes its keybindings
(add-hook 'evil-collection-setup-hook #'my-hjkl-rotation)
;; called after evil-collection makes its keybindings
(add-hook 'evil-collection-setup-hook #'my-hjkl-rotation)
(evil-collection-init)
#+end_src
(evil-collection-init)
#+end_src
A more common use case of ~evil-collection-translate-key~ would be for keeping
the functionality of some keys that users may bind globally. For example, ~SPC~,
~[~, and ~]~ are bound in some modes. If you use these keys as global prefix
keys that you never want to be overridden, you'll want to give them higher
priority than other evil keybindings (e.g. those made by ~(evil-define-key
'normal some-map ...)~). To do this, you can create an "intercept" map and bind
your prefix keys in it instead of in ~evil-normal-state-map~:
#+begin_src emacs-lisp
(defvar my-intercept-mode-map (make-sparse-keymap)
A more common use case of ~evil-collection-translate-key~ would be for keeping
the functionality of some keys that users may bind globally. For example, ~SPC~,
~[~, and ~]~ are bound in some modes. If you use these keys as global prefix
keys that you never want to be overridden, you'll want to give them higher
priority than other evil keybindings (e.g. those made by ~(evil-define-key
'normal some-map ...)~). To do this, you can create an "intercept" map and bind
your prefix keys in it instead of in ~evil-normal-state-map~:
#+begin_src emacs-lisp
(defvar my-intercept-mode-map (make-sparse-keymap)
"High precedence keymap.")
(define-minor-mode my-intercept-mode
(define-minor-mode my-intercept-mode
"Global minor mode for higher precedence evil keybindings."
:global t)
(my-intercept-mode)
(my-intercept-mode)
(dolist (state '(normal visual insert))
(dolist (state '(normal visual insert))
(evil-make-intercept-map
;; NOTE: This requires an evil version from 2018-03-20 or later
(evil-get-auxiliary-keymap my-intercept-mode-map state t t)
state))
(evil-define-key 'normal my-intercept-mode-map
(evil-define-key 'normal my-intercept-mode-map
(kbd "SPC f") 'find-file)
;; ...
#+end_src
;; ...
#+end_src
You can then define replacement keys:
#+begin_src emacs-lisp
(defun my-prefix-translations (_mode mode-keymaps &rest _rest)
You can then define replacement keys:
#+begin_src emacs-lisp
(defun my-prefix-translations (_mode mode-keymaps &rest _rest)
(evil-collection-translate-key 'normal mode-keymaps
"C-SPC" "SPC"
;; these need to be unbound first; this needs to be in same statement
@ -533,45 +533,45 @@ more.
"[[" "["
"]]" "]"))
(add-hook 'evil-collection-setup-hook #'my-prefix-translations)
(add-hook 'evil-collection-setup-hook #'my-prefix-translations)
(evil-collection-init)
#+end_src
(evil-collection-init)
#+end_src
By default, the first invocation of ~evil-collection-translate-key~ will make a
backup of the keymap. Each subsequent invocation will look up keys in the backup
instead of the original. This means that a call to
~evil-collection-translate-key~ will always have the same behavior even if
evaluated multiple times. When ~:destructive t~ is specified, keys are looked up
in the keymap as it is currently. This means that a call to
~evil-collection-translate-key~ that swapped two keys would continue to
swap/unswap them with each call. Therefore when ~:destructive t~ is used, all
cycles/swaps must be done within a single call to
~evil-collection-translate-key~. To make a comparison to Vim keybindings,
~:destructive t~ is comparable to Vim's ~map~, and ~:destructive nil~ is
comparable to Vim's ~noremap~ (where the "original" keybindings are those that
existed in the keymap when ~evil-collection-translate-key~ was first called).
You'll almost always want to use the default behavior (especially in your init
file). The limitation of ~:destructive nil~ is that you can't translate a key to
another key that was defined after the first ~evil-collection-translate-key~, so
~:destructive t~ may be useful for interactive experimentation.
By default, the first invocation of ~evil-collection-translate-key~ will make a
backup of the keymap. Each subsequent invocation will look up keys in the backup
instead of the original. This means that a call to
~evil-collection-translate-key~ will always have the same behavior even if
evaluated multiple times. When ~:destructive t~ is specified, keys are looked up
in the keymap as it is currently. This means that a call to
~evil-collection-translate-key~ that swapped two keys would continue to
swap/unswap them with each call. Therefore when ~:destructive t~ is used, all
cycles/swaps must be done within a single call to
~evil-collection-translate-key~. To make a comparison to Vim keybindings,
~:destructive t~ is comparable to Vim's ~map~, and ~:destructive nil~ is
comparable to Vim's ~noremap~ (where the "original" keybindings are those that
existed in the keymap when ~evil-collection-translate-key~ was first called).
You'll almost always want to use the default behavior (especially in your init
file). The limitation of ~:destructive nil~ is that you can't translate a key to
another key that was defined after the first ~evil-collection-translate-key~, so
~:destructive t~ may be useful for interactive experimentation.
~evil-collection-swap-key~ is also provided as a wrapper around
~evil-collection-translate-key~ that allows swapping keys:
#+begin_src emacs-lisp
(evil-collection-swap-key nil 'evil-motion-state-map
~evil-collection-swap-key~ is also provided as a wrapper around
~evil-collection-translate-key~ that allows swapping keys:
#+begin_src emacs-lisp
(evil-collection-swap-key nil 'evil-motion-state-map
";" ":")
;; is equivalent to
(evil-collection-translate-key nil 'evil-motion-state-map
;; is equivalent to
(evil-collection-translate-key nil 'evil-motion-state-map
";" ":"
":" ";")
#+end_src
#+end_src
In some cases, keys are bound through `evil-define-minor-mode-key` and may
need to be translated using ~evil-collection-translate-minor-mode-key~ and/or
~evil-collection-swap-minor-mode-key~.
In some cases, keys are bound through `evil-define-minor-mode-key` and may
need to be translated using ~evil-collection-translate-minor-mode-key~ and/or
~evil-collection-swap-minor-mode-key~.
#+begin_src emacs-lisp
#+begin_src emacs-lisp
(evil-collection-swap-minor-mode-key '(normal motion)
'(evil-snipe-local-mode evil-snipe-override-local-mode)
"k" "s"
@ -587,29 +587,29 @@ more.
;; Set this to t to make this swap the keys everytime
;; this expression is evaluated.
:destructive nil)
#+end_src
#+end_src
** Third-party packages
Third-party packages are provided by several parties:
Third-party packages are provided by several parties:
| Major mode | Evil bindings |
|------------+--------------------------|
| lispy | [[https://github.com/noctuid/lispyville][lispyville]] or [[https://github.com/sp3ctum/evil-lispy][evil-lispy]] |
| org | [[https://github.com/GuiltyDolphin/org-evil][org-evil]] or [[https://github.com/Somelauw/evil-org-mode][evil-org]] |
| markdown | [[https://github.com/Somelauw/evil-markdown][evil-markdown]] |
| ledger | [[https://github.com/atheriel/evil-ledger][evil-ledger]] |
| Major mode | Evil bindings |
|------------+--------------------------|
| lispy | [[https://github.com/noctuid/lispyville][lispyville]] or [[https://github.com/sp3ctum/evil-lispy][evil-lispy]] |
| org | [[https://github.com/GuiltyDolphin/org-evil][org-evil]] or [[https://github.com/Somelauw/evil-org-mode][evil-org]] |
| markdown | [[https://github.com/Somelauw/evil-markdown][evil-markdown]] |
| ledger | [[https://github.com/atheriel/evil-ledger][evil-ledger]] |
Should you know any suitable package not mentioned in this list, let us know and
file an issue.
Should you know any suitable package not mentioned in this list, let us know and
file an issue.
Other references:
Other references:
- [[https://github.com/syl20bnr/spacemacs/blob/master/doc/CONVENTIONS.org#key-bindings-conventions][Spacemacs]]
- [[https://github.com/hlissner/doom-emacs/tree/develop/modules/editor/evil][Doom Emacs]]
- [[https://github.com/syl20bnr/spacemacs/blob/master/doc/CONVENTIONS.org#key-bindings-conventions][Spacemacs]]
- [[https://github.com/hlissner/doom-emacs/tree/develop/modules/editor/evil][Doom Emacs]]
** FAQ
- Making SPC work similarly to [[https://github.com/syl20bnr/spacemacs][spacemacs]].
- Making SPC work similarly to [[https://github.com/syl20bnr/spacemacs][spacemacs]].
~evil-collection~ binds over SPC in many packages. To use SPC as a leader
key with the [[https://github.com/noctuid/general.el][general]] library:
@ -636,7 +636,7 @@ more.
See [[https://github.com/noctuid/evil-guide][noctuid's evil guide]] for other approaches.
- Unintialized mode maps in ~evil-collection-setup-hook~.
- Unintialized mode maps in ~evil-collection-setup-hook~.
~evil-collection-setup-hook~ is ran with a list of keymaps passed into it.
Some misconfigured modes may not have yet initialized their keymap at this
time so the value of the variable may be nil. In that case, an alternative
@ -652,21 +652,20 @@ more.
View [[https://github.com/emacs-evil/evil-collection/issues/196][196]] for more info.
** Modes left behind
Some modes might still remain unsupported by this package. Should you be
missing your ~<hjkl>~, please feel free to do a pull request.
Some modes might still remain unsupported by this package. Should you be
missing your ~<hjkl>~, please feel free to do a pull request.
** Contributing
We welcome any additional modes that are not already supported.
We welcome any additional modes that are not already supported.
All bindings in ~evil-collection~ are open to change so if there's
a better or more consistent binding, please [[https://github.com/emacs-evil/evil-collection/issues][open an issue]] or
[[https://github.com/emacs-evil/evil-collection/pulls][submit a pull request]].
All bindings in ~evil-collection~ are open to change so if there's
a better or more consistent binding, please [[https://github.com/emacs-evil/evil-collection/issues][open an issue]] or
[[https://github.com/emacs-evil/evil-collection/pulls][submit a pull request]].
Follow [[https://github.com/bbatsov/emacs-lisp-style-guide/][The Emacs Lisp Style Guide]] for coding conventions.
Follow [[https://github.com/bbatsov/emacs-lisp-style-guide/][The Emacs Lisp Style Guide]] for coding conventions.
[[https://github.com/erlang/otp/wiki/writing-good-commit-messages][Erlang/OTP]] has a good read for helpful commit messages.
[[https://github.com/erlang/otp/wiki/writing-good-commit-messages][Erlang/OTP]] has a good read for helpful commit messages.
#+LINK: EMMS https://www.gnu.org/software/emms/
#+LINK: evilmagit https://github.com/emacs-evil/evil-magit
#+LINK: evilmu4e https://github.com/JorisE/evil-mu4e
#+LINK: mu4e https://www.djcbsoftware.nl/code/mu/mu4e.html
#+LINK: EMMS https://www.gnu.org/software/emms/
#+LINK: evilmagit https://github.com/emacs-evil/evil-magit
#+LINK: evilmu4e https://github.com/JorisE/evil-mu4e
#+LINK: mu4e https://www.djcbsoftware.nl/code/mu/mu4e.html