[elpa] master ab13a16 093/271: Add back optional timer. Improve docs.

[Jackson Ray Hamilton]

branch: master
commit ab13a16a4ed03bcce0cbae4166cf693f59da546d
Author: Jackson Ray Hamilton <address@hidden>
Commit: Jackson Ray Hamilton <address@hidden>

    Add back optional timer. Improve docs.
---
 README.md           |   13 +++++++------
 context-coloring.el |   49 ++++++++++++++++++++++++++-----------------------
 2 files changed, 33 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 14a71d6..deccbb8 100644
--- a/README.md
+++ b/README.md
@@ -17,13 +17,14 @@ JavaScript programmers often leverage closures to bind 
nearby data to
 functions. Lexical scope information at-a-glance can assist a programmer in
 understanding the overall structure of a program. It can also help curb nasty
 bugs, like implicit globals and name shadowing. A rainbow can indicate 
excessive
-complexity. A spot of contrast following by an assignment expression could be a
-side-effect... or, a specially-constructed object's private state could be 
being
-manipulated.
+complexity. A spot of contrast followed by an assignment expression could be a
+side-effect... or, a specially-constructed object's private state could be
+undergoing change.
 
 This coloring scheme is probably more useful than conventional JavaScript
-*syntax* highlighting. Highlighting keywords can help detect spelling errors, 
or
-alert one to unclosed string literals; but so can a [linter][].
+*syntax* highlighting. Highlighting keywords can help one to detect spelling
+errors, or alert one to unclosed string literals; but so can a [linter][], 
which
+can also be integrated into your workflow via [flycheck][].
 
 ## Features
 
@@ -49,6 +50,6 @@ Requires Emacs 24+ and [Node.js 0.10+][node].
 ```
 
 [linter]: https://github.com/jacksonrayhamilton/jslinted
-[emacs integration]: 
https://github.com/jacksonrayhamilton/jslinted#emacs-integration
+[flycheck]: https://github.com/flycheck/flycheck
 [node]: http://nodejs.org/download/
 [load path]: 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html
diff --git a/context-coloring.el b/context-coloring.el
index 2ddfccc..28fa8e3 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -85,10 +85,6 @@
   "Context coloring face, depth 6."
   :group 'context-coloring-faces)
 
-(defconst context-coloring-face-count 7
-  "Number of faces defined for highlighting delimiter levels.
-Determines depth at which to cycle through faces again.")
-
 (defface context-coloring-depth--1-italic-face
   '((default (:inherit context-coloring-depth--1-face :slant italic)))
   "Context coloring face, depth -1; italic; comments."
@@ -129,6 +125,10 @@ Determines depth at which to cycle through faces again.")
   "Context coloring face, depth 6; bold."
   :group 'context-coloring-faces)
 
+(defconst context-coloring-face-count 7
+  "Number of faces defined for highlighting delimiter levels.
+Determines depth at which to cycle through faces again.")
+
 
 ;;; Face functions
 
@@ -156,9 +156,13 @@ For example: \"context-coloring-depth-1-face\"."
 ;;; Customizable variables
 
 (defcustom context-coloring-delay 0.25
-  "Delay between a buffer update and colorization.
+  "Delay between a buffer updates and colorization.
+
+Increase this if your machine is high-performing. Decrease it it if ain't."
+  :group 'context-coloring)
 
-If your performance is poor, you might want to increase this."
+(defcustom context-coloring-benchmark-colorization nil
+  "If non-nil, display how long each colorization took."
   :group 'context-coloring)
 
 
@@ -182,6 +186,10 @@ is a reference to that one process.")
 imply that it should be colorized again.")
 (make-variable-buffer-local 'context-coloring-changed)
 
+(defvar context-coloring-start-time nil
+  "Used to benchmark colorization time.")
+(make-variable-buffer-local 'context-coloring-changed)
+
 
 ;;; Scopification
 
@@ -219,7 +227,7 @@ buffer."
     (setq context-coloring-scopifier-process nil)))
 
 (defun context-coloring-parse-array (input)
-  "Specialized alternative JSON parser."
+  "Specialized JSON parser for a flat array of numbers."
   (vconcat (mapcar 'string-to-number (split-string (substring input 1 -1) 
","))))
 
 (defun context-coloring-scopify ()
@@ -237,7 +245,8 @@ applying a parsed list of tokens to
         (start-process-shell-command "scopifier" nil 
context-coloring-scopifier-path))
 
   (let ((output "")
-        (buffer context-coloring-buffer))
+        (buffer context-coloring-buffer)
+        (start-time context-coloring-start-time))
 
     ;; The process may produce output in multiple chunks. This filter
     ;; accumulates the chunks into a message.
@@ -253,9 +262,11 @@ applying a parsed list of tokens to
                               (let ((tokens (context-coloring-parse-array 
output)))
                                 (with-current-buffer buffer
                                   (context-coloring-apply-tokens tokens))
-                                (setq context-coloring-scopifier-process 
nil))))))
+                                (setq context-coloring-scopifier-process nil)
+                                (when context-coloring-benchmark-colorization
+                                  (message "Colorized (after %f seconds)." (- 
(float-time) start-time))))))))
 
-  ;; Give the process its input.
+  ;; Give the process its input so it can begin.
   (process-send-region context-coloring-scopifier-process (point-min) 
(point-max))
   (process-send-eof context-coloring-scopifier-process))
 
@@ -265,6 +276,9 @@ applying a parsed list of tokens to
 (defun context-coloring-colorize ()
   "Colors the current buffer by function context."
   (interactive)
+  (when context-coloring-benchmark-colorization
+    (setq context-coloring-start-time (float-time))
+    (message "%s" "Colorizing..."))
   (context-coloring-scopify))
 
 (defun context-coloring-change-function (start end length)
@@ -300,12 +314,13 @@ colorizing would be redundant."
         (font-lock-mode)
         (jit-lock-mode t))
 
+    ;; Remember this buffer. This value should not be dynamically-bound.
     (setq context-coloring-buffer (current-buffer))
 
     ;; Colorize once initially.
     (context-coloring-colorize)
 
-    ;; Font lock is not compatible with this mode; the converse is also true.
+    ;; Font lock is incompatible with this mode; the converse is also true.
     (font-lock-mode 0)
     (jit-lock-mode nil)
 
@@ -316,18 +331,6 @@ colorizing would be redundant."
     (setq context-coloring-colorize-idle-timer
           (run-with-idle-timer context-coloring-delay t 
'context-coloring-maybe-colorize))))
 
-;;;###autoload
-(defun context-coloring-mode-enable ()
-  (context-coloring-mode 1))
-
-;;;###autoload
-(defun context-coloring-mode-disable ()
-  (context-coloring-mode 0))
-
-;;;###autoload
-(define-globalized-minor-mode global-context-coloring-mode
-  context-coloring-mode context-coloring-mode-enable)
-
 (provide 'context-coloring)
 
 ;;; context-coloring.el ends here