branch: elpa/multiple-cursors
commit 487e8be4a9139e03c666acaf872f512564caf572
Author: Magnar Sveen <[email protected]>
Commit: Magnar Sveen <[email protected]>
Added docstrings to each function.
---
multiple-cursors.el | 42 ++++++++++++++++++++++++++++++++++++++++--
1 file changed, 40 insertions(+), 2 deletions(-)
diff --git a/multiple-cursors.el b/multiple-cursors.el
index 14f23f1..dcf8d28 100644
--- a/multiple-cursors.el
+++ b/multiple-cursors.el
@@ -57,29 +57,39 @@
:group 'multiple-cursors)
(defun mc/make-cursor-overlay-at-eol (pos)
+ "Create overlay to look like cursor at end of line."
(let ((overlay (make-overlay pos pos nil nil t)))
(overlay-put overlay 'after-string (propertize " " 'face 'mc/cursor-face))
overlay))
(defun mc/make-cursor-overlay-inline (pos)
+ "Create overlay to look like cursor inside text."
(let ((overlay (make-overlay pos (1+ pos) nil nil t)))
(overlay-put overlay 'face 'mc/cursor-face)
overlay))
(defun mc/make-cursor-overlay-at-point ()
+ "Create overlay to look like cursor.
+Special case for end of line, because overlay over a newline
+highlights the entire width of the window."
(if (eolp)
(mc/make-cursor-overlay-at-eol (point))
(mc/make-cursor-overlay-inline (point))))
(defun mc/add-cursor-at-point ()
+ "Add a fake cursor where point is.
+Also makes a copy of the kill-ring to be used by this cursor."
(let ((overlay (mc/make-cursor-overlay-at-point)))
(overlay-put overlay 'type 'additional-cursor)
(overlay-put overlay 'kill-ring kill-ring)
(overlay-put overlay 'priority 100)))
-(setq mc--unsupported-cmds '())
+(defvar mc--unsupported-cmds '()
+ "List of commands that does not work well with multiple cursors.")
(defmacro unsupported-cmd (cmd)
+ "Adds command to list of unsupported commands and prevents it
+from being executed if in multiple-cursors-mode."
`(progn
(push (quote ,cmd) mc--unsupported-cmds)
(defadvice ,cmd (around unsupported-advice activate)
@@ -87,8 +97,10 @@
(unless multiple-cursors-mode
ad-do-it))))
+;; Commands that makes a giant mess of multiple cursors
(unsupported-cmd yank-pop)
+;; Commands that should be mirrored by all cursors
(setq mc--cmds '(self-insert-command
previous-line
next-line
@@ -109,6 +121,11 @@
move-start-of-line-or-prev-line))
(defun mc/execute-command-for-all-cursors (cmd)
+ "Calls CMD interactively for each cursor.
+It works by moving point to the fake cursor, setting
+up the proper kill-ring, and then removing the cursor.
+After executing the command, it sets up a new fake
+cursor with updated info."
(let ((current-kill-ring kill-ring))
(save-excursion
(mapc #'(lambda (o)
@@ -123,6 +140,14 @@
(setq kill-ring current-kill-ring)))
(defun mc/execute-this-command-for-all-cursors ()
+ "Used with post-command-hook to execute supported commands for
+all cursors. It also checks a list of explicitly unsupported
+commands that is prevented even for the original cursor, to
+inform about the lack of support.
+
+Commands that are neither supported nor explicitly unsupported
+is executed normally for point, but skipped for the fake
+cursors."
(if (memq this-original-command mc--unsupported-cmds)
(message "%S is not supported with multiple cursors"
this-original-command)
(if (not (memq this-original-command mc--cmds))
@@ -130,13 +155,18 @@
(mc/execute-command-for-all-cursors this-original-command))))
(defun mc/remove-additional-cursors ()
+ "Remove all fake cursors.
+Do not use to conclude editing with multiple cursors. For that
+you should disable multiple-cursors-mode."
(mapc #'(lambda (o)
(when (eq (overlay-get o 'type) 'additional-cursor)
(delete-overlay o)))
(overlays-in (point-min) (point-max))))
(defvar mc/keymap nil
- "Keymap while multiple cursors are active.")
+ "Keymap while multiple cursors are active.
+Main goal of the keymap is to rebind C-g to conclude multiple
+cursors editing.")
(if mc/keymap
nil
(setq mc/keymap (make-sparse-keymap))
@@ -151,6 +181,12 @@
(t (add-hook 'post-command-hook
'mc/execute-this-command-for-all-cursors t t))))
(defun mc/add-multiple-cursors-to-region-lines ()
+ "Add one cursor to each line of the active region.
+Starts from mark and moves in straight down or up towards the
+line point is on.
+
+Could possibly be used to mark multiple regions with
+mark-multiple if point and mark is on different columns."
(interactive)
(when (not (use-region-p))
(error "Mark a set of lines first."))
@@ -167,12 +203,14 @@
(multiple-cursors-mode)))
(defun mc/edit-ends-of-lines ()
+ "Add one cursor to the end of each line in the active region."
(interactive)
(mc/add-multiple-cursors-to-region-lines)
(mc/execute-command-for-all-cursors 'end-of-line)
(end-of-line))
(defun mc/edit-beginnings-of-lines ()
+ "Add one cursor to the beginning of each line in the active region."
(interactive)
(mc/add-multiple-cursors-to-region-lines)
(mc/execute-command-for-all-cursors 'beginning-of-line)
