Skip to content

Latest commit

 

History

History
257 lines (209 loc) · 10.8 KB

README.org

File metadata and controls

257 lines (209 loc) · 10.8 KB
Raw
▓█████ ██▒   █▓ ██▓ ██▓        ███▄ ▄███▓ ▄████▄  
▓█   ▀▓██░   █▒▓██▒▓██▒       ▓██▒▀█▀ ██▒▒██▀ ▀█  
▒███   ▓██  █▒░▒██▒▒██░       ▓██    ▓██░▒▓█    ▄ 
▒▓█  ▄  ▒██ █░░░██░▒██░       ▒██    ▒██ ▒▓▓▄ ▄██▒
░▒████▒  ▒▀█░  ░██░░██████▒   ▒██▒   ░██▒▒ ▓███▀ ░
░░ ▒░ ░  ░ ▐░  ░▓  ░ ▒░▓  ░   ░ ▒░   ░  ░░ ░▒ ▒  ░
 ░ ░  ░  ░ ░░   ▒ ░░ ░ ▒  ░   ░  ░      ░  ░  ▒   
   ░       ░░   ▒ ░  ░ ░      ░      ░   ░        
   ░  ░     ░   ░      ░  ░          ░   ░ ░      
           ░                             ░

https://travis-ci.org/gabesoft/evil-mc.svg?branch=master http://melpa.org/packages/evil-mc-badge.svg?style=flat-square 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:

(require 'evil-mc)

Local Setup

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

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

Global Setup

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

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

Basic Usage

The main commands used to create or delete cursors are:

(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.

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 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.

(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)

For an example of setting up evil-mc see this 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.

(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.

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

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)

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

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)

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

Two or more cursors, paused

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

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

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)

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

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 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. 
    (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.

Limitations

  • After an undo command the cursors will return to their original positions if 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 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 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  \/ __ \|  |_> >  |_> >___  | \  ___// /_/ | |  ||  | |  |   |  \/ /_/  >
|___|  (____  /   __/|   __// ____|  \___  >____ | |__||__| |__|___|  /\___  / 
     \/     \/|__|   |__|   \/           \/     \/                  \//_____/