[elpa] scratch/add-vdiff b77efe3 008/258: Add README and improve docstrings

[Justin Burkett]

branch: scratch/add-vdiff
commit b77efe396da9a1174303444b5702434b852b632f
Author: justbur <address@hidden>
Commit: justbur <address@hidden>

    Add README and improve docstrings
---
 README.org |  76 ++++++++++++++++++++++++++
 vdiff.el   | 180 +++++++++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 217 insertions(+), 39 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..fec4d05
--- /dev/null
+++ b/README.org
@@ -0,0 +1,76 @@
+* vdiff
+
+A tool like vimdiff for Emacs 
+
+** Introduction
+
+vdiff is a diff tool for Emacs that is made to behave like vimdiff, meaning 
diff
+information is displayed in buffers as you edit them. There are commands for
+cycling through the changes detected by =diff= and applying changes from one
+buffer to the other. 
+
+ediff is a powerful diff tool built into Emacs, but it works differently. In
+ediff you control the diffed buffers through a third control buffer, which 
works
+great until you want to edit the buffers directly. I prefer the way vimdiff
+works, but I am also not necessarily interested in perfectly emulating
+vimdiff. vdiff does not assume you use evil-mode, but is compatible with it.
+
+vdiff is a work in progress, so use it at your own risk. Contributions are very
+welcome. A rough TODO list is
+
+1. Implement folding
+2. Improve scrolling/syncing position between buffers
+3. Three way diffs
+4. Other missing features from vimdiff
+
+** Installation and Usage
+
+It will be on MELPA eventually. For now, you have to clone this repository and
+modify =load-path=. Here's an example =use-package= declaration.
+
+#+BEGIN_SRC emacs-lisp
+(use-package vdiff
+  :load-path "path/to/vdiff"
+  :commands (vdiff-buffers vdiff-files)
+  :config
+  (define-key vdiff-mode-map (kbd "C-c") vdiff-mode-prefix-map))
+#+END_SRC
+
+The last line puts the main vdiff commands under the =C-c= prefix. With this
+declaration the key bindings in vdiff buffers are
+
+| Key     | Command                         | Description                      
                  |
+|---------+---------------------------------+----------------------------------------------------|
+| =C-c n= | =vdiff-next-change=             | Move to next change in buffer    
                  |
+| =C-c p= | =vdiff-previous-change=         | Move to previous change in 
buffer                  |
+| =C-c g= | =vdiff-goto-corresponding-line= | Jump to the corresponding line 
in the other buffer |
+| =C-c s= | =vdiff-send-changes=            | Send this hunk (or all in 
region) to other buffer  |
+| =C-c r= | =vdiff-receive-changes=         | Receive the corresponding hunk 
from other buffer   |
+| =C-c w= | =vdiff-save-buffers=            | Save both buffers                
                  |
+| =C-l=   | =vdiff-sync-and-center=         | Recenter both buffers at current 
line              |
+
+** Further customization
+   
+The current customization options and there defaults are
+   
+#+BEGIN_SRC emacs-lisp
+  ;; Whether to lock scrolling by default when starting vdiff
+  (setq vdiff-lock-scrolling t)
+
+  ;; external diff program/command to use
+  (setq vdiff-diff-program "diff")
+
+  ;; Extra arguments to pass to diff. If this is set wrong, you may
+  ;; break vdiff.
+  (setq vdiff-diff-program-args "")
+
+  ;; Commands that should be executed in other vdiff buffer to keep lines in
+  ;; sync. There is no need to include commands that scroll the buffer here,
+  ;; because those are handled differently.
+  (setq vdiff-mirrored-commands '(next-line
+                                  previous-line
+                                  evil-next-line
+                                  evil-previous-line
+                                  beginning-of-buffer
+                                  end-of-buffer))
+#+END_SRC
diff --git a/vdiff.el b/vdiff.el
index 18dd575..cb3c4ac 100644
--- a/vdiff.el
+++ b/vdiff.el
@@ -1,4 +1,4 @@
-;;; vdiff.el --- Like vimdiff  -*- lexical-binding: t; -*-
+;;; vdiff.el --- Like vimdif for Emacs -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2016 Justin Burkett
 
@@ -23,67 +23,162 @@
 
 ;;; Commentary:
 
+;; A tool like vimdiff for Emacs 
+
+;; ** Introduction
+
+;; vdiff is a diff tool for Emacs that is made to behave like vimdiff, meaning 
diff
+;; information is displayed in buffers as you edit them. There are commands for
+;; cycling through the changes detected by =diff= and applying changes from one
+;; buffer to the other. 
+
+;; ediff is a powerful diff tool built into Emacs, but it works differently. In
+;; ediff you control the diffed buffers through a third control buffer, which 
works
+;; great until you want to edit the buffers directly. I prefer the way vimdiff
+;; works, but I am also not necessarily interested in perfectly emulating
+;; vimdiff. vdiff does not assume you use evil-mode, but is compatible with it.
+
+;; vdiff is a work in progress, so use it at your own risk. Contributions are 
very
+;; welcome. A rough TODO list is
+
+;; 1. Implement folding
+;; 2. Improve scrolling/syncing position between buffers
+;; 3. Three way diffs
+;; 4. Other missing features from vimdiff
+
+;; ** Installation and Usage
+
+;; It will be on MELPA eventually. For now, you have to clone this repository 
and
+;; modify =load-path=. Here's an example =use-package= declaration.
+
+;; (use-package vdiff
+;;   :load-path "path/to/vdiff"
+;;   :commands (vdiff-buffers vdiff-files)
+;;   :config
+;;   (define-key vdiff-mode-map (kbd "C-c") vdiff-mode-prefix-map))
+
+;; The last line puts the main vdiff commands under the =C-c= prefix. With this
+;; declaration the key bindings in vdiff buffers are
+
+;; | Key     | Command                         | Description                   
                     |
+;; 
|---------+---------------------------------+----------------------------------------------------|
+;; | =C-c n= | =vdiff-next-change=             | Move to next change in buffer 
                     |
+;; | =C-c p= | =vdiff-previous-change=         | Move to previous change in 
buffer                  |
+;; | =C-c g= | =vdiff-goto-corresponding-line= | Jump to the corresponding 
line in the other buffer |
+;; | =C-c s= | =vdiff-send-changes=            | Send this hunk (or all in 
region) to other buffer  |
+;; | =C-c r= | =vdiff-receive-changes=         | Receive the corresponding 
hunk from other buffer   |
+;; | =C-c w= | =vdiff-save-buffers=            | Save both buffers             
                     |
+;; | =C-l=   | =vdiff-sync-and-center=         | Recenter both buffers at 
current line              |
+
+;; ** Further customization
+   
+;; The current customization options and there defaults are
+   
+;;   ;; Whether to lock scrolling by default when starting vdiff
+;;   (setq vdiff-lock-scrolling t)
+
+;;   ;; external diff program/command to use
+;;   (setq vdiff-diff-program "diff")
+
+;;   ;; Extra arguments to pass to diff. If this is set wrong, you may
+;;   ;; break vdiff.
+;;   (setq vdiff-diff-program-args "")
+
+;;   ;; Commands that should be executed in other vdiff buffer to keep lines in
+;;   ;; sync. There is no need to include commands that scroll the buffer here,
+;;   ;; because those are handled differently.
+;;   (setq vdiff-mirrored-commands '(next-line
+;;                                   previous-line
+;;                                   evil-next-line
+;;                                   evil-previous-line
+;;                                   beginning-of-buffer
+;;                                   end-of-buffer))
+;; 
+
 ;;; Code:
 
+(defgroup vdiff nil
+  "Diff tool that is like vimdiff"
+  :tag "Vdiff"
+  :group 'tools)
+
 (defcustom vdiff-lock-scrolling t
   "Whether to lock scrolling by default when starting
-  `vdiff-mode'.")
+`vdiff-mode'."
+  :group 'vdiff
+  :type 'boolean)
 
 (defcustom vdiff-diff-program "diff"
-  "diff program to use.")
+  "diff program to use."
+  :group 'vdiff
+  :type 'string)
 
 (defcustom vdiff-diff-program-args ""
   "Extra arguments to pass to diff. If this is set wrong, you may
-break vdiff.")
-
-(defcustom vdiff-copied-commands '(next-line
-                                   previous-line
-                                   evil-next-line
-                                   evil-previous-line
-                                   beginning-of-buffer
-                                   end-of-buffer)
+break vdiff. It is empty by default."
+  :group 'vdiff
+  :type 'string)
+
+(defcustom vdiff-mirrored-commands '(next-line
+                                     previous-line
+                                     evil-next-line
+                                     evil-previous-line
+                                     beginning-of-buffer
+                                     end-of-buffer)
   "Commands that should be executed in other vdiff buffer to keep
-lines in sync.")
-
-(defvar vdiff-buffers nil)
-(defvar vdiff-temp-files (list (make-temp-file "vdiff-temp-a-")
-                               (make-temp-file "vdiff-temp-b-")))
-(defvar vdiff-process-buffer " *vdiff*")
-(defvar vdiff-diff-data nil)
-(defvar vdiff-diff-code-regexp
+lines in sync. There is no need to include commands that scroll
+the buffer here, because those are handled differently."
+  :group 'vdiff
+  :type '(repeat symbol))
+
+(defvar vdiff--buffers nil)
+(defvar vdiff--temp-files (list (make-temp-file "vdiff--temp-a-")
+                               (make-temp-file "vdiff--temp-b-")))
+(defvar vdiff--process-buffer " *vdiff*")
+(defvar vdiff--diff-data nil)
+(defvar vdiff--diff-code-regexp
   "^\\([0-9]+\\),?\\([0-9]+\\)?\\([adc]\\)\\([0-9]+\\),?\\([0-9]+\\)?")
-(defvar vdiff-inhibit-window-switch nil)
-(defvar vdiff-scroll-command-cnt 0)
-(defvar vdiff-inhibit-sync nil)
-(defvar vdiff-line-map nil)
+(defvar vdiff--inhibit-window-switch nil)
+(defvar vdiff--scroll-command-cnt 0)
+(defvar vdiff--inhibit-sync nil)
+(defvar vdiff--line-map nil)
 
 ;; * Utilities
 
-(defun vdiff-maybe-int (str)
-  (when str (string-to-int str)))
+(defun vdiff--maybe-int (str)
+  (let ((num (and str (string-to-number str))))
+    (when (and (numberp num)
+               (> num 0))
+      num)))
+
+(defun vdiff--buffer-a-p ()
+  (eq (current-buffer) (car vdiff--buffers)))
 
-(defun vdiff-buffer-a-p ()
-  (eq (current-buffer) (car vdiff-buffers)))
+(defun vdiff--buffer-b-p ()
+  (eq (current-buffer) (cadr vdiff--buffers)))
 
-(defun vdiff-buffer-b-p ()
-  (eq (current-buffer) (cadr vdiff-buffers)))
+(defun vdiff--buffer-p ()
+  (memq (current-buffer) vdiff--buffers))
 
-(defun vdiff-buffer-p ()
-  (memq (current-buffer) vdiff-buffers))
+(defun vdiff--other-buffer ()
+  (if (vdiff--buffer-a-p)
+      (cadr vdiff--buffers)
+    (car vdiff--buffers)))
 
-(defun vdiff-other-buffer ()
-  (if (vdiff-buffer-a-p)
-      (cadr vdiff-buffers)
-    (car vdiff-buffers)))
+(defun vdiff--other-window ()
+  (get-buffer-window (vdiff--other-buffer)))
 
-(defun vdiff-other-window ()
-  (get-buffer-window (vdiff-other-buffer)))
+(defun vdiff--min-window-width ()
+  (apply #'min
+         (mapcar (lambda (buf)
+                   (window-width (get-buffer-window buf)))
+                 vdiff--buffers)))
 
-(defun vdiff-move-to-line (n)
+(defun vdiff--move-to-line (n)
   (goto-char (point-min))
   (forward-line (1- n)))
 
-(defun vdiff-overlay-at-point (&optional prior pos)
+(defun vdiff--overlay-at-point (&optional prior pos)
   (let ((pos (or pos (point))))
     (catch 'yes
       (dolist (ovr (overlays-at
@@ -275,6 +370,9 @@ lines in sync.")
 ;; * Moving changes
 
 (defun vdiff-send-changes (beg end &optional receive)
+  "Send these changes to other vdiff buffer. If the region is
+active, send all changes found in the region. Otherwise use the
+changes under point or on the immediately preceding line."
   (interactive
    (if (region-active-p)
        (list (region-beginning) (region-end))
@@ -296,6 +394,10 @@ lines in sync.")
     (vdiff-refresh)))
 
 (defun vdiff-receive-changes (beg end)
+  "Receive the changes corresponding to this position from the
+other vdiff buffer. If the region is active, receive all
+corresponding changes found in the region. Otherwise use the
+changes under point or on the immediately preceding line."
   (interactive
    (if (region-active-p)
        (list (region-beginning) (region-end))