From 839c6ef0774e76a3da1c76b63786775668779a8c Mon Sep 17 00:00:00 2001 From: Magnar Sveen Date: Sun, 18 Nov 2012 16:36:37 +0100 Subject: [PATCH] Update README with command overview and tips-n-tricks. --- README.md | 66 +++++++++++--------- multiple-cursors.el | 146 ++++++++++++++++++++++++++------------------ 2 files changed, 126 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 1e87ee4..819a337 100644 --- a/README.md +++ b/README.md @@ -35,46 +35,56 @@ insert a newline in multiple-cursors-mode, use `C-j`. You can [watch an intro to multiple-cursors at Emacs Rocks](http://emacsrocks.com/e13.html). -## More commands to play around with +## Command overview -I've set up my key-bindings like so: +### Mark one more occurrence - ;; From active region to multiple cursors: - (global-set-key (kbd "C-S-c C-S-c") 'mc/edit-lines) - (global-set-key (kbd "C-S-c C-e") 'mc/edit-ends-of-lines) - (global-set-key (kbd "C-S-c C-a") 'mc/edit-beginnings-of-lines) + - `mc/mark-next-like-this`: Adds a cursor and region at the next part of the buffer forwards that matches the current region. + - `mc/mark-next-word-like-this`: Like `mc/mark-next-like-this` but only for whole words. + - `mc/mark-next-symbol-like-this`: Like `mc/mark-next-like-this` but only for whole symbols. + - `mc/mark-previous-like-this`: Adds a cursor and region at the next part of the buffer backwards that matches the current region. + - `mc/mark-previous-word-like-this`: Like `mc/mark-previous-like-this` but only for whole words. + - `mc/mark-previous-symbol-like-this`: Like `mc/mark-previous-like-this` but only for whole symbols. + - `mc/mark-more-like-this-extended`: Use arrow keys to quickly mark/skip next/previous occurances. -When you have an active region that spans multiple lines, the preceeding three -commands will add one cursor to each line. +### Mark many occurrences - ;; Rectangular region mode - (global-set-key (kbd "H-SPC") 'set-rectangular-region-anchor) + - `mc/mark-all-like-this`: Marks all parts of the buffer that matches the current region. + - `mc/mark-all-words-like-this`: Like `mc/mark-all-like-this` but only for whole words. + - `mc/mark-all-symbols-like-this`: Like `mc/mark-all-like-this` but only for whole symbols. + - `mc/mark-all-in-region`: Prompts for a string to match in the region, adding cursors to all of them. + - `mc/mark-all-like-this-in-defun`: Marks all parts of the current defun that matches the current region. + - `mc/mark-all-words-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole words. + - `mc/mark-all-symbols-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole symbols. + - `mc/mark-all-like-this-dwim`: Tries to be smart about marking everything you want. Can be pressed multiple times. -Think of this one as `set-mark` except you're marking a rectangular region. It is -an exceedingly quick way of adding multiple cursors to multiple lines. +### Special - ;; Mark more like this - (global-set-key (kbd "M-æ") 'mc/mark-all-like-this) - (global-set-key (kbd "C-å") 'mc/mark-previous-like-this) - (global-set-key (kbd "C-æ") 'mc/mark-next-like-this) - (global-set-key (kbd "C-Æ") 'mc/mark-more-like-this-extended) - (global-set-key (kbd "M-å") 'mc/mark-all-in-region) + - `set-rectangular-region-anchor`: Think of this one as `set-mark` except you're marking a rectangular region. + - `mc/mark-sgml-tag-pair`: Mark the current opening and closing tag. -Okay, yes, I have a crazy norwegian keyboard. Regardless, these will look at -whatever you've got selected at the moment, and mark more places like that in -the buffer. +## Tips and tricks -If you would like to keep the global bindings clean, and get custom keybindings -when the region is active, you can try [region-bindings-mode](https://github.com/fgallina/region-bindings-mode). +- To get out of multiple-cursors-mode, press `` or `C-g`. The latter will + first disable multiple regions before disabling multiple cursors. If you want to + insert a newline in multiple-cursors-mode, use `C-j`. + +- Sometimes you end up with cursors outside of your view. You can + scroll the screen to center on each cursor with `C-v` and `M-v`. + +- Try pressing `mc/mark-next-like-this` with no region selected. It will just add a cursor + on the next line. + +- Try pressing `mc/mark-all-like-this-dwim` on a tagname in html-mode. + +- Notice that the number of cursors active can be seen in the modeline. + +- If you would like to keep the global bindings clean, and get custom keybindings + when the region is active, you can try [region-bindings-mode](https://github.com/fgallina/region-bindings-mode). BTW, I highly recommend adding `mc/mark-next-like-this` to a key binding that's right next to the key for `er/expand-region`. -## Scrolling - -Sometimes you end up with cursors outside of your view. You can scroll the -screen to center on each cursor with `C-v` and `M-v`. - ## Unknown commands Multiple-cursors uses two lists of commands to know what to do: the run-once list diff --git a/multiple-cursors.el b/multiple-cursors.el index 31c3bb9..749b181 100644 --- a/multiple-cursors.el +++ b/multiple-cursors.el @@ -23,106 +23,136 @@ ;; Multiple cursors for Emacs. This is some pretty crazy functionality, so yes, ;; there are kinks. Don't be afraid tho, I've been using it since 2011 with ;; great success and much merriment. -;; + ;; ## Basic usage -;; + ;; Start out with: -;; + ;; (require 'multiple-cursors) -;; + +;; Then you have to set up your keybindings - multiple-cursors doesn't presume to +;; know how you'd like them laid out. Here are some examples: + ;; When you have an active region that spans multiple lines, the following will ;; add a cursor to each line: -;; + ;; (global-set-key (kbd "C-S-c C-S-c") 'mc/edit-lines) -;; + ;; When you want to add multiple cursors not based on continuous lines, but based on ;; keywords in the buffer, use: -;; + ;; (global-set-key (kbd "C->") 'mc/mark-next-like-this) ;; (global-set-key (kbd "C-<") 'mc/mark-previous-like-this) ;; (global-set-key (kbd "C-c C-<") 'mc/mark-all-like-this) -;; + ;; First mark the word, then add more cursors. -;; + ;; To get out of multiple-cursors-mode, press `` or `C-g`. The latter will ;; first disable multiple regions before disabling multiple cursors. If you want to ;; insert a newline in multiple-cursors-mode, use `C-j`. -;; -;; -;; ## More commands to play around with -;; -;; I've set up my key-bindings like so: -;; -;; ;; From active region to multiple cursors: -;; (global-set-key (kbd "C-S-c C-S-c") 'mc/edit-lines) -;; (global-set-key (kbd "C-S-c C-e") 'mc/edit-ends-of-lines) -;; (global-set-key (kbd "C-S-c C-a") 'mc/edit-beginnings-of-lines) -;; -;; When you have an active region that spans multiple lines, the preceeding three -;; commands will add one cursor to each line. -;; -;; ;; Rectangular region mode -;; (global-set-key (kbd "H-SPC") 'set-rectangular-region-anchor) -;; -;; Think of this one as `set-mark` except you're marking a rectangular region. It is -;; an exceedingly quick way of adding multiple cursors to multiple lines. -;; -;; ;; Mark more like this -;; (global-set-key (kbd "M-æ") 'mc/mark-all-like-this) -;; (global-set-key (kbd "C-å") 'mc/mark-previous-like-this) -;; (global-set-key (kbd "C-æ") 'mc/mark-next-like-this) -;; (global-set-key (kbd "C-Æ") 'mc/mark-more-like-this-extended) -;; (global-set-key (kbd "M-å") 'mc/mark-all-in-region) -;; -;; Okay, yes, I have a crazy norwegian keyboard. Regardless, these will look at -;; whatever you've got selected at the moment, and mark more places like that in -;; the buffer. -;; + +;; ## Video + +;; You can [watch an intro to multiple-cursors at Emacs Rocks](http://emacsrocks.com/e13.html). + +;; ## Command overview + +;; ### Mark one more occurrence + +;; - `mc/mark-next-like-this`: Adds a cursor and region at the next part of the buffer forwards that matches the current region. +;; - `mc/mark-next-word-like-this`: Like `mc/mark-next-like-this` but only for whole words. +;; - `mc/mark-next-symbol-like-this`: Like `mc/mark-next-like-this` but only for whole symbols. +;; - `mc/mark-previous-like-this`: Adds a cursor and region at the next part of the buffer backwards that matches the current region. +;; - `mc/mark-previous-word-like-this`: Like `mc/mark-previous-like-this` but only for whole words. +;; - `mc/mark-previous-symbol-like-this`: Like `mc/mark-previous-like-this` but only for whole symbols. +;; - `mc/mark-more-like-this-extended`: Use arrow keys to quickly mark/skip next/previous occurances. + +;; ### Mark many occurrences + +;; - `mc/mark-all-like-this`: Marks all parts of the buffer that matches the current region. +;; - `mc/mark-all-words-like-this`: Like `mc/mark-all-like-this` but only for whole words. +;; - `mc/mark-all-symbols-like-this`: Like `mc/mark-all-like-this` but only for whole symbols. +;; - `mc/mark-all-in-region`: Prompts for a string to match in the region, adding cursors to all of them. +;; - `mc/mark-all-like-this-in-defun`: Marks all parts of the current defun that matches the current region. +;; - `mc/mark-all-words-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole words. +;; - `mc/mark-all-symbols-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole symbols. +;; - `mc/mark-all-like-this-dwim`: Tries to be smart about marking everything you want. Can be pressed multiple times. + +;; ### Special + +;; - `set-rectangular-region-anchor`: Think of this one as `set-mark` except you're marking a rectangular region. +;; - `mc/mark-sgml-tag-pair`: Mark the current opening and closing tag. + +;; ## Tips and tricks + +;; - To get out of multiple-cursors-mode, press `` or `C-g`. The latter will +;; first disable multiple regions before disabling multiple cursors. If you want to +;; insert a newline in multiple-cursors-mode, use `C-j`. + +;; - Sometimes you end up with cursors outside of your view. You can +;; scroll the screen to center on each cursor with `C-v` and `M-v`. + +;; - Try pressing `mc/mark-next-like-this` with no region selected. It will just add a cursor +;; on the next line. + +;; - Try pressing `mc/mark-all-like-this-dwim` on a tagname in html-mode. + +;; - Notice that the number of cursors active can be seen in the modeline. + +;; - If you would like to keep the global bindings clean, and get custom keybindings +;; when the region is active, you can try [region-bindings-mode](https://github.com/fgallina/region-bindings-mode). + ;; BTW, I highly recommend adding `mc/mark-next-like-this` to a key binding that's ;; right next to the key for `er/expand-region`. -;; -;; + ;; ## Unknown commands -;; + ;; Multiple-cursors uses two lists of commands to know what to do: the run-once list ;; and the run-for-all list. It comes with a set of defaults, but it would be beyond silly ;; to try and include all the known Emacs commands. -;; + ;; So that's why multiple-cursors occasionally asks what to do about a command. It will ;; then remember your choice by saving it in `~/.emacs.d/.mc-lists.el`. You can change ;; the location with: -;; + ;; (setq mc/list-file "/my/preferred/file") -;; -;; + ;; ## Known limitations -;; + ;; * isearch-forward and isearch-backward aren't supported with multiple cursors. ;; You should feel free to add a simplified version that can work with it. ;; * Commands run with `M-x` won't be repeated for all cursors. ;; * All key bindings that refer to lambdas are always run for all cursors. If you ;; need to limit it, you will have to give it a name. ;; * Redo might screw with your cursors. Undo works very well. -;; -;; + ;; ## Contribute -;; + ;; Yes, please do. There's a suite of tests, so remember to add tests for your ;; specific feature, or I might break it later. -;; + ;; You'll find the repo at: -;; + ;; https://github.com/magnars/multiple-cursors.el -;; + ;; To fetch the test dependencies: -;; + ;; $ cd /path/to/multiple-cursors ;; $ git submodule update --init -;; + ;; Run the tests with: -;; + ;; $ ./util/ecukes/ecukes --graphical -;; + +;; ## Contributors + +;; * [Takafumi Arakaki](https://github.com/tkf) made .mc-lists.el diff friendly +;; * [Marco Baringer](https://github.com/segv) contributed looping to mc/cycle and adding cursors without region for mark-more. +;; * [Ivan Andrus](https://github.com/gvol) added showing number of cursors in mode-line +;; * [Fuco](https://github.com/Fuco1) added the first version of `mc/mark-all-like-this-dwim` + +;; Thanks! + ;;; Code: (require 'mc-edit-lines)