Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/gabesoft/evil-mc

Multiple cursors implementation for evil-mode
https://github.com/gabesoft/evil-mc

emacs evil multiple-cursors vim

Last synced: 29 days ago
JSON representation

Multiple cursors implementation for evil-mode

Lists

README 

        
: ▓█████ ██▒   █▓ ██▓ ██▓        ███▄ ▄███▓ ▄████▄  

: ▓█   ▀▓██░   █▒▓██▒▓██▒       ▓██▒▀█▀ ██▒▒██▀ ▀█  

: ▒███   ▓██  █▒░▒██▒▒██░       ▓██    ▓██░▒▓█    ▄ 

: ▒▓█  ▄  ▒██ █░░░██░▒██░       ▒██    ▒██ ▒▓▓▄ ▄██▒

: ░▒████▒  ▒▀█░  ░██░░██████▒   ▒██▒   ░██▒▒ ▓███▀ ░

: ░░ ▒░ ░  ░ ▐░  ░▓  ░ ▒░▓  ░   ░ ▒░   ░  ░░ ░▒ ▒  ░

:  ░ ░  ░  ░ ░░   ▒ ░░ ░ ▒  ░   ░  ░      ░  ░  ▒   

:    ░       ░░   ▒ ░  ░ ░      ░      ░   ░        

:    ░  ░     ░   ░      ░  ░          ░   ░ ░      

:            ░                             ░        



 [[https://travis-ci.org/gabesoft/evil-mc][https://travis-ci.org/gabesoft/evil-mc.svg?branch=master]] [[http://melpa.org/#/evil-mc][file:http://melpa.org/packages/evil-mc-badge.svg?style=flat-square]] [[http://melpa.org/#/evil-mc][file:http://stable.melpa.org/packages/evil-mc-badge.svg?style=flat-square]]



** Multiple cursors implementation for evil-mode

*** Synopsis

*evil-mc* provides multiple cursors functionality for Emacs when used with *evil-mode* 

*** Usage

Start with:

#+BEGIN_SRC emacs-lisp

 (require 'evil-mc)

#+END_SRC

**** Local Setup

To enable or disable *evil-mc* mode for a single buffer use:\\

#+BEGIN_SRC emacs-lisp

(evil-mc-mode  1) ;; enable

(evil-mc-mode -1) ;; disable

#+END_SRC

**** Global Setup

To enable or disable *evil-mc* mode for all buffers use:\\

#+BEGIN_SRC emacs-lisp

(global-evil-mc-mode  1) ;; enable

(global-evil-mc-mode -1) ;; disable

#+END_SRC

**** Basic Usage

The main commands used to create or delete cursors are:



#+BEGIN_SRC emacs-lisp

(evil-mc-make-all-cursors)

;; Create cursors for all strings that match the selected 

;; region or the symbol under cursor.



(evil-mc-undo-all-cursors)

;; Remove all cursors.



(evil-mc-make-and-goto-next-match)

;; Make a cursor at point and go to the next match of the 

;; selected region or the symbol under cursor.



(evil-mc-skip-and-goto-next-match)

;; Go to the next match of the selected region or the symbol under 

;; cursor without creating a cursor at point.

#+END_SRC



The above commands as well as others, detailed below, are setup with key bindings

when the *evil-mc* mode is enabled. The keys are defined in ~evil-mc-key-map~. You can 

take a look at that variable declaration in [[https://github.com/gabesoft/evil-mc/blob/master/evil-mc.el][evil-mc.el]] to see all key bindings. But,

in short, ~C-n~ / ~C-p~ are used for creating cursors, and ~M-n~ / ~M-p~

are used for cycling through cursors. The commands that create cursors wrap around; but, 

the ones that cycle them do not. 

To skip creating a cursor forward use ~C-t~ or ~grn~ and backward ~grp~. 

Finally use ~gru~ to "undo" the last added cursor, and ~grq~ to remove all cursors.



Optionally set up visual mode keybindings for ~I~ and ~A~ to create cursors at the

beginning or end of every visually selected line.



#+BEGIN_SRC emacs-lisp

(evil-define-key 'visual evil-mc-key-map

  "A" #'evil-mc-make-cursor-in-visual-selection-end

  "I" #'evil-mc-make-cursor-in-visual-selection-beg)

#+END_SRC



For an example of setting up *evil-mc* see this [[https://github.com/gabesoft/evil-mc/blob/master/evil-mc-setup.el][setup file]]

**** Commands

Here's a detailed list of all commands used to create, navigate through, or delete cursors:\\

/All the commands below assume that there is a real cursor and possibly some fake cursors./



#+BEGIN_SRC emacs-lisp

(evil-mc-make-all-cursors)

;; Make a cursor for every match of the selected region or the symbol at point.



(evil-mc-undo-all-cursors)

;; Remove all cursors.



(evil-mc-undo-last-added-cursor)

;; Remove the last added cursor and move point to its position.



(evil-mc-make-and-goto-next-match)

;; Make a cursor at point, and go to the next match of the 

;; selected region or the symbol at point.



(evil-mc-make-and-goto-prev-match)

;; Make a cursor at point, and go to the previous match of the 

;; selected region or the symbol at point.



(evil-mc-skip-and-goto-next-match)

;; Go to the next match of the selected region or symbol at point

;; without making a cursor at point. This command can be used to

;; remove unwanted cursors.



(evil-mc-skip-and-goto-prev-match)

;; Go to the previous match of the selected region or symbol at point

;; without making a cursor at point. This command can be used to

;; remove unwanted cursors.



(evil-mc-make-and-goto-prev-cursor)

;; Make a cursor at point and move point to the cursor

;; closest to it when searching backwards.



(evil-mc-make-and-goto-next-cursor)

;; Make a cursor at point and move point to the cursor

;; closest to it when searching forwards.



(evil-mc-skip-and-goto-prev-cursor)

;; Move point to the cursor closest to it when searching backwards

;; without making a cursor at point. This command can be used to

;; remove unwanted cursors.



(evil-mc-skip-and-goto-next-cursor)

;; Move point to the cursor closest to it when searching forwards

;; without making a cursor at point. This command can be used to

;; remove unwanted cursors.



(evil-mc-make-and-goto-first-cursor)

;; Make a cursor at point and move point to the cursor at the first position.



(evil-mc-make-and-goto-last-cursor)

;; Make a cursor at point and move point to the cursor at the last position.



(evil-mc-make-cursor-here)

;; Create a cursor at point. This command should be used with `evil-mc-pause-cursors'.



(evil-mc-pause-cursors)

;; Pause all fake cursors. This can be used with `evil-mc-make-cursor-here'



(evil-mc-resume-cursors)

;; Call to resume paused cursors.



(evil-mc-make-cursor-in-visual-selection-beg)

;; Create cursors at the beginning of every visually selected line.



(evil-mc-make-cursor-in-visual-selection-end)

;; Create cursors at the end of every visually selected line.

#+END_SRC



**** Customization

*evil-mc* can be customized in several ways:



- Every known command is executed using a command handler defined in a variable

  called ~evil-mc-known-commands~ in [[https://github.com/gabesoft/evil-mc/blob/master/evil-mc-known-commands.el][evil-mc-known-commands.el]]. Those can be overridden by 

  defining the ~evil-mc-custom-known-commands~ variable. See the documentation of 

  that variable in [[https://github.com/gabesoft/evil-mc/blob/master/evil-mc.el][evil-mc.el]] for more info.

- Some minor modes are incompatible with *evil-mc*. Those modes are defined in 

  ~evil-mc-incompatible-minor-modes~ and can be overridden by defining that variable.

- In addition there are two hooks that can be used to temporarily disable or enable 

  additional functionality while there are multiple cursors active

  #+BEGIN_SRC emacs-lisp

  evil-mc-before-cursors-created

  ;; this hook runs just before the first cursor is created



  evil-mc-after-cursors-created

  ;; this hook runs just after the last cursor is deleted

  #+END_SRC



*** Mode line text and colors

There are 4 variables, that can change the mode lines text, and its color.



**** Only one cursor

The ~emc~ text can be hidden, by setting this variable to ~nil~.

(default: ~t~)

#+BEGIN_SRC

(setq evil-mc-one-cursor-show-mode-line-text t)

#+END_SRC



**** Two or more cursors, resumed (unpaused)

The resumed mode line text, can have two different colors:

- The cursors color, when this variable is ~t~.

- The default colors, when this variable is ~nil~.

(default: ~t~)

#+BEGIN_SRC

(setq evil-mc-mode-line-text-cursor-color t)

#+END_SRC



**** Two or more cursors, paused

The ~(paused)~ text can be hidden, by setting this variable to ~nil~.

(default: ~t~)

#+BEGIN_SRC

(setq evil-mc-mode-line-text-paused t)

#+END_SRC



The paused mode line text can have three different colors:

- Inverse colors, when the inverse colors variable is ~t~.

- Cursors color, when the inverse colors variable is ~nil~, and the cursor color variable is ~t~.

- Default colors, when both the inverse and cursor color variables are ~nil~.

(default: ~t~, for both the inverse and cursor variables)

#+BEGIN_SRC

(setq evil-mc-mode-line-text-inverse-colors t)

(setq evil-mc-mode-line-text-cursor-color t)

#+END_SRC



*** Notes

- Most evil motions and operators are supported but not every single command will work. 

- If the cursors don't seem to work during a command, either the command is

  not known (see ~evil-mc-known-commands~ in [[https://github.com/gabesoft/evil-mc/blob/master/evil-mc-known-commands.el][evil-mc-known-commands.el]]) or some minor modes

  could be interfering with the evil-mc operations. 

- Issues and pull requests are welcome. 



**** Debugging

- When a command does not work, and you want to get more information,

  you can enable (or disable) debugging by running any of the commands 

  below interactively.

  #+BEGIN_SRC emacs-lisp

  (evil-mc-executing-debug-on)

  ;; Turn debug on while executing a command.



  (evil-mc-executing-debug-off)

  ;; Turn debug off while executing a command.



  (evil-mc-recording-debug-on)

  ;; Turn debug on while recording a command.



  (evil-mc-recording-debug-off)

  ;; Turn debug off while recording a command.



  (evil-mc-all-debug-on)

  ;; Turn all debug on.



  (evil-mc-all-debug-off)

  ;; Turn all debug off.

  #+END_SRC



**** Limitations

- After an undo command the cursors will return to their original positions

  if [[http://www.emacswiki.org/emacs/UndoTree][undo-tree]] mode is enabled and ~evil-repeat~ has not been used.

- Redo may cause the real cursor to get out of sync with the others.

  This can be worked around by setting a mark and returning to it after a redo.

- Jumps work if [[https://github.com/bling/evil-jumper][evil-jumper]] mode is enabled

- Search commands such as ~evil-search-forward~, ~evil-search-backward~, and ~evil-search-next~ are not supported



**** Known issues

- Only named commands can be executed by the fake cursors.

- There could be a performance penalty when there are too many cursors (30+).

- Paste will not work when [[https://github.com/syl20bnr/spacemacs][spacemacs]]' paste micro state is enabled.

  This is due to the fact that ~evil-paste-pop~ and ~evil-paste-pop-next~ 

  commands are not supported.

- ~evil-repeat~ works only for some commands. 

  In particular it doesn't work for delete. It will also interfere with the 

  cursor positions during an undo or redo operation.



* 

: .__                                            .___.__  __  .__                

: |  |__ _____  ______ ______ ___.__.   ____   __| _/|__|/  |_|__| ____    ____  

: |  |  \\__  \ \____ \\____ <   |  | _/ __ \ / __ | |  \   __\  |/    \  / ___\ 

: |   Y  \/ __ \|  |_> >  |_> >___  | \  ___// /_/ | |  ||  | |  |   |  \/ /_/  >

: |___|  (____  /   __/|   __// ____|  \___  >____ | |__||__| |__|___|  /\___  / 

:      \/     \/|__|   |__|   \/           \/     \/                  \//_____/