[elpa] externals/cursor-undo 2264853e77: * cursor-undo.el: Fix cursor-undo for read-only buffers.

[Luke Lee]

branch: externals/cursor-undo
commit 2264853e77872122a085fb2733b43c80337c44ca
Author: Luke Lee <luke@gauss>
Commit: Luke Lee <luke@gauss>

    * cursor-undo.el: Fix cursor-undo for read-only buffers.
    (cundo-track-screen-start, cundo-track-prev-point): new functions to
    make `def-cursor-undo' more clean, also fix read-only buffer issues.
    (def-cursor-undo): use the above functions to fix the issue.
    * README.org: Newly added README file to provide more info.
---
 README.org     | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 cursor-undo.el |  18 +++++++---
 2 files changed, 126 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..d192a5a4b4
--- /dev/null
+++ b/README.org
@@ -0,0 +1,112 @@
+# Cursor Undo Mode    -*- mode: org; -*-
+
+* _About_
+
+Cursor-undo allows you to undo cursor movement commands using the
+Emacs standard `undo' command.
+
+For frequent cursor movements such as up/down/left/right, it combines
+the movements of the same direction into a single undo entry.  This
+prevents the undo command from reversing each individual character
+movement separately.  For example, if you move the cursor 20
+characters to the right and then 10 lines up, the first undo will go
+down 10 lines back, and the next undo move back 20 characters left.
+On the other hand, for search commands that often jump across multiple
+pages, each search command has its own undo entry, allowing you to
+undo them one at a time rather than as a combined operation.
+
+* _A "Brief" History_
+
+This cursor-undo functionality has existed in my local Emacs init file
+for over 11+ years, since version 0 on 2013-06-26.  It was originally
+intended to support my ELPA package 
[[https://elpa.gnu.org/packages/brief.html][BriefMode]] only, but I later found
+it would be more useful if implemented in a more generalized way.  For
+years I have hoped for an official implementation of this feature,
+which is commonly seen among various editors.  Considering my
+implementation using advice functions a bit inelegant so I have always
+hesitated to release it till recently.
+
+Until there is official support for the cursor undo feature, this
+package serves most common daily needs.  The core design is to align
+with Emacs's native `undo' function by recording cursor positions and
+screen-relative position undo entries in the `buffer-undo-list' in
+accordance with its documentation.
+
+As this package primarily consists of advice functions to wrap cursor
+movement commands, each cursor movement command needs to be manually
+wrapped with `def-cursor-undo'.  For interactive functions that
+heavily invoke advised cursor movement commands, you may even need to
+advise them with `disable-cursor-tracking' to prevent generating
+numerous distinct cursor undo entries from a single command.  For user
+convenience, I have prepared ready `def-cursor-undo' advice sets for
+standard Emacs cursor movement commands, Brief Editor mode, Viper
+mode, and EVIL mode.
+
+* _Usage_
+
+This package is released as a standard 
[[https://elpa.gnu.org/packages/cursor-undo.html][ELPA package]].  Just go to 
Emacs
+main menu -> "Options" -> "Manage Emacs Packages" and install it.
+Once this package is installed, you only need to enable cursor-undo
+mode by adding the following line into your Emacs init file .emacs or
+init.el:
+
+#+begin_src
+  (cursor-undo 1)
+#+end_src
+
+That's all.  You can now move your cursor around and use stand Emacs
+`undo' (C-_, C-/ or C-x u) to move it back.  Even in read-only buffers
+you can still undo cursor movements.  This is convenient especially
+when browsing a huge file.
+
+* _Notes for read-only buffers_
+
+Notice that the original `undo' cannot be performed in read-only
+buffers.  Here, I also advised the undo operation in read-only buffers
+as long as the pending undo list is still a cursor movement.
+
+This also enables a editing trick: If you are just editing a big file
+and moving the cursor to browse other parts but forgot where you were,
+you can undo cursor movements to go back to your last edited position
+by long-holding <undo> until the last editing command.  However, by
+doing so you risk missing your last edited operation as it might flash
+by so quickly that you don't even notice but keep undoing other cursor
+commands you don't want to undo.
+
+In this case, you can switch the buffer to read-only mode (by setting
+`buffer-read-only' to t), then long press <undo> until the undo
+command warns you that you're trying to edit a read-only buffer.  At
+this point, you're exactly at the latest editing position you are
+looking for.  You can then safely set `buffer-read-only' flag back to
+NIL and continue your editing.
+
+* _Notes for EVIL mode user_
+
+If you choose to use the default Emacs `undo' system, you should be
+able to use `evil-undo' to undo cursor movements.  If your choice is
+tree-undo or another undo system, you might need to use Emacs default
+`undo' (C-_, C-/ or C-x u ...) to undo cursor movements.
+
+
+* _Notes for Viper mode user_
+
+The default `viper-undo' is advised to allow cursor-undo.  If you find
+the advised function not working properly, consider comment out the
+following source code `(define-advice viper-undo ...' to restore the
+original `viper-undo' function and use Emacs default `undo' (C-_, C-/
+or C-x u ...)  to undo cursor movements.
+
+* _Technical notes_
+
+Why do I use advice functions instead of the more generalized pre/post
+command hooks?  I bet you wouldn't like all the cursor movements in
+your debugging session being recorded as undo entries; when you start
+`undo'ing you will find the cursor replaying your previous debugging
+session in reverse order.  Similar effects happens in `semantic' mode
+and many others.  If it record *every* movement you will soon find it
+difficult to use in many situations.  Therefore, only the chosen
+editing key commands are advised with `def-cursor-undo'.  If you find
+something missing, just advise it with your own `def-cursor-undo'.
+
+
+Luke Lee
diff --git a/cursor-undo.el b/cursor-undo.el
index aafa26957b..b16175d81b 100644
--- a/cursor-undo.el
+++ b/cursor-undo.el
@@ -5,7 +5,7 @@
 ;; Author:       Luke Lee <luke.yx.lee@gmail.com>
 ;; Maintainer:   Luke Lee <luke.yx.lee@gmail.com>
 ;; Keywords:     undo, cursor
-;; Version:      1.1.2
+;; Version:      1.1.3
 
 ;; GNU Emacs is free software: you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -135,6 +135,17 @@
 ;; "Warning: Unused lexical variable ‘prev-screen-start’".
 (defvar prev-screen-start)
 
+(defun cundo-track-screen-start (prv-screen-start)
+  (let ((entry (list 'apply 'cundo-restore-win prv-screen-start)))
+    (if (eq buffer-undo-list 't)
+        (setq buffer-undo-list entry)
+      (push entry buffer-undo-list))))
+
+(defun cundo-track-prev-point (prev-point)
+  (if (eq buffer-undo-list 't)
+      (setq buffer-undo-list (list prev-point))
+    (push prev-point buffer-undo-list)))
+
 ;;;###autoload
 (defmacro def-cursor-undo (func-sym &optional no-combine screen-pos no-move)
   "Define an advice for FUNC-SYM to track cursor movements in the undo buffer.
@@ -227,10 +238,9 @@ relative screen position (screen-pos=NIL) nor `point' 
position (no-move=t)."))
                       (numberp (cadr buffer-undo-list))
                       (= prev-point (cadr buffer-undo-list))))
            ,@(if screen-pos
-                 '((push `(apply cundo-restore-win ,prev-screen-start)
-                         buffer-undo-list)))
+                 '((cundo-track-screen-start prev-screen-start)))
            ,@(unless no-move
-               '((push prev-point buffer-undo-list)))
+               '((cundo-track-prev-point prev-point)))
            ;;(abbrevmsg (format "c=%S,%S b=%S" last-command this-command
            ;;                   buffer-undo-list) 128) ;; DBG
            (undo-boundary))