From 294d5748620ce6bd8d612e6b5cf339f2c250fc66 Mon Sep 17 00:00:00 2001 From: Magnar Sveen Date: Wed, 25 Jul 2012 20:56:39 +0200 Subject: [PATCH] Update README --- README.md | 97 +++++++++++++++++++++++++----------- multiple-cursors.el | 118 ++++++++++++++++++++++++++++++++------------ 2 files changed, 154 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 0acf396..a129a57 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,94 @@ # multiple-cursors.el -An experiment in multiple cursors for emacs. Still very much in beta. +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. -The basic concept works, but there are definitely some kinks to work out. +## Basic usage -This extension is dependent on the mark-multiple library. +Start out with: - https://github.com/magnars/mark-multiple.el + (require 'multiple-cursors) -## Usage +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/add-multiple-cursors-to-region-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 "M-<") 'mc/mark-all-like-this) + +First mark the word, then add more cursors. + + +## More commands to play around with I've set up my key-bindings like so: - ;; Experimental multiple-cursors + ;; From active region to multiple cursors: (global-set-key (kbd "C-S-c C-S-c") 'mc/add-multiple-cursors-to-region-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) -To get out of multiple-cursors-mode, press `C-g`. +When you have an active region that spans multiple lines, the preceeding three +commands will add one cursor to each line. -You can also switch to multiple-cursors-mode by pressing C-g when in -mark-multiple-mode. This is symmetrical to how pressing C-g with an active -region deactivates it. Press C-g again to remove extra cursors. + ;; Rectangular region mode + (global-set-key (kbd "H-SPC") 'set-rectangular-region-anchor) -## Combining with mark-multiple +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. -Right now you can go from multiple marks to multiple cursors with C-g. + ;; 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) -The other way around is a bit more tricky: +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. - * What to do about overlapping marks? - * Expanding the marks should be possible, for instance using `mark-word` or - `expand-region` - * Killing or copying needs to keep a kill-ring for each cursor. +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`. -So basically `mark-multiple` isn't ready for prime time as a full blown multiple -marks library. For this to work as expected, I think parts of mark-multiple -needs to be rewritten, and possibly integrated into multiple-cursors. +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 them all. + +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. -For now, mark-multiple is an excellent tool to place your cursors where you need -them to be. ## Contribute -There's plenty wrong with this implementation still. I'm actively trying things -out, and also working on combining it with -[mark-multiple.el](https://github.com/magnars/mark-multiple.el) to get a more -comprehensive tool. - -Still, if you've got something to contribute, please do not hesitate to open -an issue, and we can take a look together before you dive into the elisp. :-) +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: diff --git a/multiple-cursors.el b/multiple-cursors.el index ef09102..4714003 100644 --- a/multiple-cursors.el +++ b/multiple-cursors.el @@ -20,55 +20,109 @@ ;;; Commentary: -;; An experiment in multiple cursors for emacs. Still very much in beta. +;; 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) +;; +;; 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/add-multiple-cursors-to-region-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 "M-<") 'mc/mark-all-like-this) +;; +;; First mark the word, then add more cursors. +;; +;; +;; ## More commands to play around with ;; -;; The basic concept works, but there are definitely some kinks to work out. - -;; This extension is dependent on the mark-multiple library. -;; https://github.com/magnars/mark-multiple.el - -;; ** Usage - ;; I've set up my key-bindings like so: ;; -;; ;; Experimental multiple-cursors +;; ;; From active region to multiple cursors: ;; (global-set-key (kbd "C-S-c C-S-c") 'mc/add-multiple-cursors-to-region-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) ;; -;; To get out of multiple-cursors-mode, press `C-g`. - -;; ** Contribute - -;; There's plenty wrong with this implementation still. I'm actively trying things -;; out, and also working on combining it with -;; [mark-multiple.el](https://github.com/magnars/mark-multiple.el) to get a more -;; comprehensive tool. +;; When you have an active region that spans multiple lines, the preceeding three +;; commands will add one cursor to each line. ;; -;; Still, if you've got something to contribute, please do not hesitate to open -;; an issue, and we can take a look together before you dive into the elisp. :-) +;; ;; 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. +;; +;; 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`. +;; +;; 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 them all. +;; +;; 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 - -;; ## Combining with mark-multiple ;; -;; Right now you can go from multiple marks to multiple cursors with C-g. +;; To fetch the test dependencies: ;; -;; The other way around is a bit more tricky: +;; $ cd /path/to/multiple-cursors +;; $ git submodule update --init ;; -;; * What to do about overlapping marks? -;; * Expanding the marks should be possible, for instance using `mark-word` or -;; `expand-region` -;; * Killing or copying needs to keep a kill-ring for each cursor. +;; Run the tests with: ;; -;; So basically `mark-multiple` isn't ready for prime time as a full blown multiple -;; marks library. For this to work as expected, I think parts of mark-multiple -;; needs to be rewritten, and possibly integrated into multiple-cursors. +;; $ ./util/ecukes/ecukes --graphical ;; -;; For now, mark-multiple is an excellent tool to place your cursors where you need -;; them to be. ;;; Code: