[elpa] externals/lentic 3b1d0cb77a 154/333: Split lentic.el code into -mode and -dev.

[ELPA Syncer]

branch: externals/lentic
commit 3b1d0cb77a45a4b8cdbd0d70c33fe2a881f4f345
Author: Phillip Lord <phillip.lord@newcastle.ac.uk>
Commit: Phillip Lord <phillip.lord@newcastle.ac.uk>

    Split lentic.el code into -mode and -dev.
    
    Previously lentic.el contained a minor mode, and some dev functionality.
    All this has been moved into different files now to enable the use
    of lentic entirely as an API only.
---
 .dir-locals.el |   2 +-
 lentic-dev.el  |  87 +++++++++++++++++++++++--
 lentic-mode.el | 198 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 lentic.el      | 193 ++-----------------------------------------------------
 4 files changed, 283 insertions(+), 197 deletions(-)

diff --git a/.dir-locals.el b/.dir-locals.el
index 64222d423a..d044278857 100644
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -1,4 +1,4 @@
 ((emacs-lisp-mode
   .
-  ((lentic-init 'lentic-orgel-org-init)
+  ((lentic-init . lentic-orgel-org-init)
    (eval . (require 'm-buffer)))))
diff --git a/lentic-dev.el b/lentic-dev.el
index d180c3674c..09b49b88f2 100644
--- a/lentic-dev.el
+++ b/lentic-dev.el
@@ -1,4 +1,4 @@
-;; lentic-dev.el --- Tools for developers -*- lexical-binding: t -*-
+;;; lentic-dev.el --- Tools for developers -*- lexical-binding: t -*-
 
 ;;; Header:
 
@@ -7,19 +7,19 @@
 ;; Author: Phillip Lord <phillip.lord@newcastle.ac.uk>
 ;; Maintainer: Phillip Lord <phillip.lord@newcastle.ac.uk>
 ;; The contents of this file are subject to the GPL License, Version 3.0.
-;;
+
 ;; Copyright (C) 2014, Phillip Lord, Newcastle University
-;;
+
 ;; This program is free software: you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
 ;; (at your option) any later version.
-;;
+
 ;; This program is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
-;;
+
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
@@ -33,9 +33,79 @@
 ;; #+begin_src emacs-lisp
 (require 'lentic)
 
-(defvar lentic-dev-insert-face 'font-lock-keyword-face)
+;; #+end_src
+
+;; ** Manual Updates
+
+;; Usually, lentic uses Emacs hooks to percolate changes in one buffer to
+;; another. Unfortunately, all the hooks that do this not only silently discard
+;; errors, but they delete the offending function from the hook. So, 
post-mortem
+;; debugging is hard. Step-through is also hard since it happens in the command
+;; loop.
 
-(defun lentic-dev-rotate-face ()
+;; Lentic has a function for disabling its functionality (due to breakage
+;; rather than just normal switching it off), called `linked-buffer-emergency'
+;; (and the inverse `linked-buffer-unemergency'). In this emergency state, we
+;; can still run the hooks manually, which is by far the best way to debug 
them.
+
+;; For the `lentic-test-after-change-function' to work `lentic-emergency-debug'
+;; must be set. It is also critical that only a single change has happened 
before
+;; this function is called -- otherwise the result of the previous change are
+;; deleted, and the lentic buffers will update in an inconsistent and haphazard
+;; way.
+
+
+;; #+begin_src emacs-lisp
+(defun lentic-dev-after-change-function ()
+  "Run the change functions out of the command loop.
+Using this function is the easiest way to test an new
+`lentic-clone' method, as doing so in the command loop is
+painful for debugging. Set variable `lentic-emergency' to
+true to disable command loop functionality."
+  (interactive)
+  (message "Running after change with args: %s"
+           lentic-emergency-last-change)
+  (apply 'lentic-after-change-function-1
+         lentic-emergency-last-change))
+
+(defun lentic-dev-post-command-hook ()
+  "Run the post-command functions out of the command loop.
+Using this function is the easiest way to test an new
+`lentic-convert' method, as doing so in the command loop is
+painful for debugging. Set variable `lentic-emergency' to
+true to disable command loop functionality."
+  (interactive)
+  (lentic-post-command-hook-1))
+
+(defun lentic-dev-reinit ()
+  "Recall the init function regardless of current status.
+This can help if you have change the config object and need
+to make sure there is a new one."
+  (interactive)
+  (funcall lentic-init))
+
+
+;; #+end_src
+
+;; ** Font-Lock changes
+
+;; These commands enable or disable fontification of changes that lentic has
+;; percolated. This is very useful for incremental changes; it's the only
+;; practical way of seeing what has been copied.
+
+;; The exact behaviour of this depends on the mode of the buffer displaying the
+;; lentic buffer. Sometimes, the natural buffer fontification functions just
+;; change the font back to whatever the syntax suggests. In this case, try
+;; switching off `font-lock-mode'.
+
+;; #+begin_src emacs-lisp
+
+(defvar lentic-dev-insert-face
+  "Start face to use for inserted text."
+  'font-lock-keyword-face)
+
+(defun lentic-dev-random-face ()
+  "Change the insertion face to a random one."
   (interactive)
   (setq lentic-dev-insert-face
         (nth (random (length (face-list)))
@@ -60,6 +130,7 @@
 
 (defvar lentic-dev-enable-insertion-marking nil)
 (defun lentic-dev-enable-insertion-marking ()
+  "Enable font locking properties for inserted text."
   (interactive)
   (if lentic-enable-insertion-marking
       (progn
@@ -73,4 +144,6 @@
     (message "Insertion marking on")))
 
 (provide 'lentic-dev)
+;;; lentic-dev.el ends here
+
 ;; #+end_src
diff --git a/lentic-mode.el b/lentic-mode.el
new file mode 100644
index 0000000000..a4b629f3c7
--- /dev/null
+++ b/lentic-mode.el
@@ -0,0 +1,198 @@
+;;; lentic-mode.el --- minor mode for lentic buffers -*- lexical-binding: t -*-
+
+;;; Header:
+
+;; This file is not part of Emacs
+
+;; Author: Phillip Lord <phillip.lord@newcastle.ac.uk>
+;; Maintainer: Phillip Lord <phillip.lord@newcastle.ac.uk>
+;; The contents of this file are subject to the GPL License, Version 3.0.
+
+;; Copyright (C) 2014, Phillip Lord, Newcastle University
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; A minor mode for creating and manipulated lentic buffers.
+
+;;; Code:
+
+;; ** Window and Buffer Functions
+
+;; #+begin_src emacs-lisp
+(defun lentic-mode-move-lentic-window ()
+  "Move the lentic buffer into the current window.
+If the lentic is currently being displayed in another window,
+then the current-buffer will be moved into that window. See also
+`lentic-mode-swap-buffer-windows'."
+  (interactive)
+  (let ((before-window-start
+         (window-start (get-buffer-window)))
+        (before-window-point
+         (point)))
+    (lentic-mode-swap-buffer-windows
+     (current-buffer)
+     (lentic-that lentic-config))
+    (set-window-start
+     (selected-window)
+     before-window-start)
+    (goto-char before-window-point)))
+
+(defun lentic-mode-swap-lentic-window ()
+  "Swap the window of the buffer and lentic.
+If both are current displayed, swap the windows they
+are displayed in, which keeping current buffer.
+See also `lentic-mode-move-lentic-window'."
+  (interactive)
+  (lentic-mode-swap-buffer-windows
+   (current-buffer)
+   (lentic-that lentic-config))
+  (when (window-live-p
+         (get-buffer-window
+          (current-buffer)))
+    (select-window
+     (get-buffer-window
+      (current-buffer)))))
+
+(defun lentic-mode-swap-buffer-windows (a b)
+  "Swaps the window that two buffers are displayed in.
+A and B are the buffers."
+  (let ((window-a (get-buffer-window a))
+        (window-b (get-buffer-window b)))
+    (when window-a
+      (set-window-buffer
+       window-a b))
+    (when window-b
+      (set-window-buffer
+       window-b a))))
+
+(defun lentic-mode-create-in-selected-window ()
+  "Create a lentic buffer and move it to the current window."
+  (interactive)
+  (let ((before-window-start
+         (window-start (get-buffer-window)))
+        (before-window-point
+         (point)))
+    (lentic-ensure-init)
+    (set-window-buffer
+     (selected-window)
+     (lentic-create lentic-config))
+    (set-window-start
+     (selected-window)
+     before-window-start)
+    (goto-char before-window-point)))
+
+(defun lentic-mode-split-window-below ()
+  "Create a lentic buffer in a new window below."
+  (interactive)
+  (lentic-ensure-init)
+  (set-window-buffer
+   (split-window-below)
+   (lentic-create lentic-config)))
+
+(defun lentic-mode-split-window-right ()
+  "Create a lentic buffer in a new window right."
+  (interactive)
+  (lentic-ensure-init)
+  (set-window-buffer
+   (split-window-right)
+   (lentic-create lentic-config)))
+
+
+;; ** Minor Mode
+
+
+;; #+begin_src emacs-lisp
+;;;###autoload
+(defun lentic-mode-toggle-auto-sync-point ()
+  (interactive)
+  (lentic-when-lentic
+   (oset lentic-config :sync-point
+         (not (oref lentic-config :sync-point)))))
+
+(defvar lentic-mode-map (make-sparse-keymap)
+  "Keymap for lentic-minor-mode")
+
+(define-key lentic-mode-map
+  (kbd "C-c ,s") 'lentic-mode-swap-lentic-window)
+
+(define-key lentic-mode-map
+  (kbd "C-c ,h") 'lentic-mode-move-lentic-window)
+
+;;;###autoload
+(define-minor-mode lentic-mode
+  :lighter "lb"
+  :keymap lentic-mode-map)
+
+(easy-menu-change
+ '("Edit")
+ "Lentic"
+ '(["Create Here" lentic-mode-create-in-selected-window]
+   ["Split Below" lentic-mode-split-window-below]
+   ["Split Right" lentic-mode-split-window-right]
+   ["Move Here" lentic-mode-move-lentic-window :active lentic-config]
+   ["Swap" lentic-mode-swap-buffer-windows :active lentic-config]))
+
+;;;###autoload
+(defun lentic-mode-insert-file-local (init-function)
+  (interactive
+   (list (completing-read
+          "Lentic init function: "
+          (mapcar
+           'symbol-name
+           lentic-init-functions)
+          'identity 'confirm)))
+  (save-excursion
+    (goto-char (point-max))
+    (let ((start (point)))
+      (insert
+       (format
+        ;; split this string or we get local variable not terminated properly
+        ;; errors.
+        (concat "\nLocal"
+                " Variables:\nlentic-init: %s\nEnd:\n") init-function))
+      (comment-region start (point)))))
+
+(defvar lentic-start-mode-map (make-sparse-keymap))
+
+(define-key lentic-start-mode-map
+  (kbd "C-c ,b") 'lentic-mode-split-window-below)
+
+(define-key lentic-start-mode-map
+  (kbd "C-c ,r") 'lentic-mode-split-window-right)
+
+(define-key lentic-start-mode-map
+  (kbd "C-c ,f") 'lentic-mode-insert-file-local)
+
+(define-key lentic-start-mode-map
+  (kbd "C-c ,c") 'lentic-mode-create-in-selected-window)
+
+;;;###autoload
+(define-minor-mode lentic-start-mode
+  :lighter ""
+  :keymap lentic-start-mode-map)
+
+;;;###autoload
+(define-globalized-minor-mode global-lentic-start-mode
+  lentic-start-mode
+  lentic-start-on)
+
+(defun lentic-start-on ()
+  (lentic-start-mode 1))
+;; #+end_src
+
+(provide 'lentic-mode)
+
+;;; lentic-mode.el ends here
diff --git a/lentic.el b/lentic.el
index 2a1f23b4d4..43bee43f69 100644
--- a/lentic.el
+++ b/lentic.el
@@ -473,51 +473,6 @@ ERR is the error. HOOK is the hook type."
     (princ (error-message-string err)))
   (select-window (get-buffer-window "*lentic-fail*")))
 
-(defun lentic-move-lentic-window ()
-  "Move the lentic into the current window.
-If the lentic is currently being displayed in another
-window, then the current-buffer will be moved into that window.
-See also `lentic-swap-buffer-windows'."
-  (interactive)
-  (let ((before-window-start
-         (window-start (get-buffer-window)))
-        (before-window-point
-         (point)))
-    (lentic-swap-buffer-windows
-     (current-buffer)
-     (lentic-that lentic-config))
-    (set-window-start
-     (selected-window)
-     before-window-start)
-    (goto-char before-window-point)))
-
-(defun lentic-swap-lentic-window ()
-  "Swap the window of the buffer and lentic.
-If both are current displayed, swap the windows they
-are displayed in, which keeping current buffer.
-See also `lentic-move-lentic-window'."
-  (interactive)
-  (lentic-swap-buffer-windows
-   (current-buffer)
-   (lentic-that lentic-config))
-  (when (window-live-p
-         (get-buffer-window
-          (current-buffer)))
-    (select-window
-     (get-buffer-window
-      (current-buffer)))))
-
-(defun lentic-swap-buffer-windows (a b)
-  "Swaps the window that two buffers are displayed in.
-A and B are the buffers."
-  (let ((window-a (get-buffer-window a))
-        (window-b (get-buffer-window b)))
-    (when window-a
-      (set-window-buffer
-       window-a b))
-    (when window-b
-      (set-window-buffer
-       window-b a))))
 
 (defun lentic-ensure-init ()
   "Ensure that the `lentic-init' has been run."
@@ -534,37 +489,6 @@ A and B are the buffers."
   (lentic-ensure-init)
   (lentic-create lentic-config))
 
-(defun lentic-create-in-selected-window ()
-  "Create a lentic buffer and move it to the current window."
-  (interactive)
-  (let ((before-window-start
-         (window-start (get-buffer-window)))
-        (before-window-point
-         (point)))
-    (lentic-ensure-init)
-    (set-window-buffer
-     (selected-window)
-     (lentic-create lentic-config))
-    (set-window-start
-     (selected-window)
-     before-window-start)
-    (goto-char before-window-point)))
-
-(defun lentic-split-window-below ()
-  "Create a lentic buffer in a new window below."
-  (interactive)
-  (lentic-ensure-init)
-  (set-window-buffer
-   (split-window-below)
-   (lentic-create lentic-config)))
-
-(defun lentic-split-window-right ()
-  "Create a lentic buffer in a new window right."
-  (interactive)
-  (lentic-ensure-init)
-  (set-window-buffer
-   (split-window-right)
-   (lentic-create lentic-config)))
 
 (defvar lentic-emergency-last-change nil)
 (make-variable-buffer-local 'lentic-emergency-last-change)
@@ -719,93 +643,12 @@ same top-left location. Update details depend on CONF."
        (get-buffer-window-list (lentic-that conf))))))
 ;; #+end_src
 
-;; ** Minor Mode
 
-;; #+begin_src emacs-lisp
-;;;###autoload
-(defun lentic-toggle-auto-sync-point ()
-  (interactive)
-  (lentic-when-lentic
-   (oset lentic-config :sync-point
-         (not (oref lentic-config :sync-point)))))
+;; ** Batch Functions
 
-(defvar lentic-mode-map (make-sparse-keymap)
-  "Keymap for lentic-minor-mode")
-
-(define-key lentic-mode-map
-  (kbd "C-c ,s") 'lentic-swap-lentic-window)
-
-(define-key lentic-mode-map
-  (kbd "C-c ,h") 'lentic-move-lentic-window)
-
-;;;###autoload
-(define-minor-mode lentic-mode
-  :lighter "lb"
-  :keymap lentic-mode-map)
-
-(easy-menu-change
- '("Edit")
- "Lentic"
- '(["Create Here" lentic-create-in-selected-window]
-   ["Split Below" lentic-split-window-below]
-   ["Split Right" lentic-split-window-right]
-   ["Move Here" lentic-move-lentic-window :active lentic-config]
-   ["Swap" lentic-swap-buffer-windows :active lentic-config]))
-
-;;;###autoload
-(defun lentic-insert-file-local (init-function)
-  (interactive
-   (list (completing-read
-          "Lentic init function: "
-          (mapcar
-           'symbol-name
-           lentic-init-functions)
-          'identity 'confirm)))
-  (save-excursion
-    (goto-char (point-max))
-    (let ((start (point)))
-      (insert
-       (format
-        ;; split this string or we get local variable not terminated properly
-        ;; errors.
-        (concat "\nLocal"
-                " Variables:\nlentic-init: %s\nEnd:\n") init-function))
-      (comment-region start (point)))))
-
-(defvar lentic-start-mode-map (make-sparse-keymap))
-
-(define-key lentic-start-mode-map
-  (kbd "C-c ,b") 'lentic-split-window-below)
-
-(define-key lentic-start-mode-map
-  (kbd "C-c ,r") 'lentic-split-window-right)
-
-(define-key lentic-start-mode-map
-  (kbd "C-c ,f") 'lentic-insert-file-local)
-
-(define-key lentic-start-mode-map
-  (kbd "C-c ,c") 'lentic-create-in-selected-window)
-
-;;;###autoload
-(define-minor-mode lentic-start-mode
-  :lighter ""
-  :keymap lentic-start-mode-map)
-
-;;;###autoload
-(define-globalized-minor-mode global-lentic-start-mode
-  lentic-start-mode
-  lentic-start-on)
-
-(defun lentic-start-on ()
-  (lentic-start-mode 1))
-;; #+end_src
-
-;; ** Test Functions
-
-;; Functions which are used for testing new lentic-configurations; as such
-;; they are either batch operation functionality, or interactive commands to 
run
-;; the various hook commands rather than from the post-command or after-change
-;; hook functionality.
+;; These functions are for batch operation on lentic buffers. Mostly, these
+;; are useful for writing tests, but they can be useful for generating
+;; the lentic form of a file during any automated pipeline.
 
 ;; #+begin_src emacs-lisp
 (defun lentic-batch-clone-and-save-with-config (filename init)
@@ -843,34 +686,6 @@ Return the lentic contents without properties."
       (kill-buffer))
     retn))
 
-(defun lentic-test-after-change-function ()
-  "Run the change functions out of the command loop.
-Using this function is the easiest way to test an new
-`lentic-clone' method, as doing so in the command loop is
-painful for debugging. Set variable `lentic-emergency' to
-true to disable command loop functionality."
-  (interactive)
-  (message "Running after change with args: %s"
-           lentic-emergency-last-change)
-  (apply 'lentic-after-change-function-1
-         lentic-emergency-last-change))
-
-(defun lentic-test-post-command-hook ()
-  "Run the post-command functions out of the command loop.
-Using this function is the easiest way to test an new
-`lentic-convert' method, as doing so in the command loop is
-painful for debugging. Set variable `lentic-emergency' to
-true to disable command loop functionality."
-  (interactive)
-  (lentic-post-command-hook-1))
-
-(defun lentic-test-reinit ()
-  "Recall the init function regardless of current status.
-This can help if you have change the config object and need
-to make sure there is a new one."
-  (interactive)
-  (funcall lentic-init))
-
 (provide 'lentic)
 
 ;; #+END_SRC