branch: master
commit c81eecb37b3d19b60d13d86c84de0b33cbbbb2c1
Author: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
Commit: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
Update function names and docstrings.
---
benchmark/context-coloring-benchmark.el | 1 +
context-coloring.el | 131 +++++++++++++++++++++----------
test/context-coloring-coverage.el | 2 +-
test/context-coloring-test.el | 11 ++-
4 files changed, 96 insertions(+), 49 deletions(-)
diff --git a/benchmark/context-coloring-benchmark.el
b/benchmark/context-coloring-benchmark.el
index 9ce2f6d..c2dd653 100644
--- a/benchmark/context-coloring-benchmark.el
+++ b/benchmark/context-coloring-benchmark.el
@@ -38,6 +38,7 @@
(expand-file-name path context-coloring-benchmark-path))
(defun context-coloring-benchmark-next-tick (callback)
+ "Run CALLBACK in the next turn of the event loop."
(run-with-timer nil nil callback))
(defun context-coloring-benchmark-series (sequence callback)
diff --git a/context-coloring.el b/context-coloring.el
index 35e8c43..ffed467 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -93,7 +93,7 @@ backgrounds."
(defvar context-coloring-original-maximum-face nil
"Fallback value for `context-coloring-maximum-face' when all
- themes have been disabled.")
+themes have been disabled.")
(setq context-coloring-maximum-face 7)
@@ -138,7 +138,9 @@ used.")
"Length of last text that changed.")
(defun context-coloring-change-function (start end length)
- "Register a change so that a buffer can be colorized soon."
+ "Register a change so that a buffer can be colorized soon.
+
+START, END and LENGTH are recorded for later use."
;; Tokenization is obsolete if there was a change.
(context-coloring-cancel-scopification)
(setq context-coloring-changed-start start)
@@ -147,7 +149,7 @@ used.")
(setq context-coloring-changed-p t))
(defun context-coloring-maybe-colorize (buffer)
- "Colorize the current buffer if it has changed."
+ "Colorize the current buffer if it is BUFFER and has changed."
(when (and (eq buffer (current-buffer))
context-coloring-changed-p)
(context-coloring-colorize)
@@ -231,10 +233,11 @@ the END point (exclusive) with the face corresponding to
LEVEL."
"Tell `font-lock' to color a string but not a comment."
(if (nth 3 state) font-lock-string-face nil))
-(defsubst context-coloring-maybe-colorize-comments-and-strings (&optional min
max)
+(defsubst context-coloring-colorize-comments-and-strings (&optional min max)
"Color the current buffer's comments or strings if
`context-coloring-syntactic-comments' or
-`context-coloring-syntactic-strings' are non-nil."
+`context-coloring-syntactic-strings' are non-nil. MIN defaults
+to the beginning of the buffer and MAX defaults to the end."
(when (or context-coloring-syntactic-comments
context-coloring-syntactic-strings)
(let ((min (or min (point-min)))
@@ -350,7 +353,7 @@ generated by `js2-mode'."
(context-coloring-js2-scope-level defining-scope))))))
;; The `t' indicates to search children.
t)))
- (context-coloring-maybe-colorize-comments-and-strings)))
+ (context-coloring-colorize-comments-and-strings)))
;;; Emacs Lisp colorization
@@ -361,10 +364,10 @@ generated by `js2-mode'."
(defsubst context-coloring-elisp-forward-sws ()
"Move forward through whitespace and comments, colorizing
-them along the way."
+comments along the way."
(let ((start (point)))
(context-coloring-forward-sws)
- (context-coloring-maybe-colorize-comments-and-strings start (point))))
+ (context-coloring-colorize-comments-and-strings start (point))))
(defsubst context-coloring-elisp-forward-sexp ()
"Like `forward-sexp', but colorize comments and strings along
@@ -375,16 +378,17 @@ the way."
start (point))))
(defsubst context-coloring-get-syntax-code ()
+ "Get the syntax code at point."
(syntax-class
;; Faster version of `syntax-after':
(aref (syntax-table) (char-after (point)))))
(defsubst context-coloring-exact-regexp (word)
- "Create a regexp that matches exactly WORD."
+ "Create a regexp matching exactly WORD."
(concat "\\`" (regexp-quote word) "\\'"))
(defsubst context-coloring-exact-or-regexp (words)
- "Create a regexp that matches any exact word in WORDS."
+ "Create a regexp matching any exact word in WORDS."
(context-coloring-join
(mapcar #'context-coloring-exact-regexp words) "\\|"))
@@ -398,12 +402,14 @@ the way."
'("condition-case"
"condition-case-unless-debug")))
-(defconst context-coloring-ignored-word-regexp
+(defconst context-coloring-elisp-ignored-word-regexp
(context-coloring-join (list "\\`[-+]?[0-9]"
"\\`[&:].+"
(context-coloring-exact-or-regexp
'("t" "nil" "." "?")))
- "\\|"))
+ "\\|")
+ "Match words that might be considered symbols but can't be
+bound as variables.")
(defconst context-coloring-WORD-CODE 2)
(defconst context-coloring-SYMBOL-CODE 3)
@@ -430,9 +436,12 @@ the way."
If user input is pending, stop the parse. This makes for a
smoother user experience for large files.")
-(defvar context-coloring-elisp-sexp-count 0)
+(defvar context-coloring-elisp-sexp-count 0
+ "Current number of sexps leading up to the next pause.")
(defsubst context-coloring-elisp-increment-sexp-count ()
+ "Maybe check if the current parse should be interrupted as a
+result of pending user input."
(setq context-coloring-elisp-sexp-count
(1+ context-coloring-elisp-sexp-count))
(when (and (zerop (% context-coloring-elisp-sexp-count
@@ -441,23 +450,30 @@ smoother user experience for large files.")
(input-pending-p))
(throw 'interrupted t)))
-(defvar context-coloring-elisp-scope-stack '())
+(defvar context-coloring-elisp-scope-stack '()
+ "List of scopes in the current parse.")
(defsubst context-coloring-elisp-make-scope (level)
+ "Make a scope object for LEVEL."
(list
:level level
:variables '()))
(defsubst context-coloring-elisp-scope-get-level (scope)
+ "Get the level of SCOPE object."
(plist-get scope :level))
(defsubst context-coloring-elisp-scope-add-variable (scope variable)
+ "Add to SCOPE a VARIABLE."
(plist-put scope :variables (cons variable (plist-get scope :variables))))
(defsubst context-coloring-elisp-scope-has-variable (scope variable)
+ "Check if SCOPE has VARIABLE."
(member variable (plist-get scope :variables)))
(defsubst context-coloring-elisp-get-variable-level (variable)
+ "Search up the scope chain for the first instance of VARIABLE
+and return its level, or 0 (global) if it isn't found."
(let* ((scope-stack context-coloring-elisp-scope-stack)
scope
level)
@@ -471,7 +487,8 @@ smoother user experience for large files.")
;; Assume a global variable.
(or level 0)))
-(defsubst context-coloring-elisp-current-scope-level ()
+(defsubst context-coloring-elisp-get-current-scope-level ()
+ "Get the nesting level of the current scope."
(cond
((car context-coloring-elisp-scope-stack)
(context-coloring-elisp-scope-get-level (car
context-coloring-elisp-scope-stack)))
@@ -479,29 +496,38 @@ smoother user experience for large files.")
0)))
(defsubst context-coloring-elisp-push-scope ()
+ "Add a new scope to the bottom of the scope chain."
(push (context-coloring-elisp-make-scope
- (1+ (context-coloring-elisp-current-scope-level)))
+ (1+ (context-coloring-elisp-get-current-scope-level)))
context-coloring-elisp-scope-stack))
(defsubst context-coloring-elisp-pop-scope ()
+ "Remove the scope on the bottom of the scope chain."
(pop context-coloring-elisp-scope-stack))
(defsubst context-coloring-elisp-add-variable (variable)
+ "Add VARIABLE to the current scope."
(context-coloring-elisp-scope-add-variable
(car context-coloring-elisp-scope-stack)
variable))
-(defsubst context-coloring-elisp-parse-arg (callback)
+(defsubst context-coloring-elisp-parse-bindable (callback)
+ "Parse the symbol at point, and if the symbol can be bound,
+invoke CALLBACK with it."
(let* ((arg-string (buffer-substring-no-properties
(point)
(progn (context-coloring-elisp-forward-sexp)
(point)))))
(when (not (string-match-p
- context-coloring-ignored-word-regexp
+ context-coloring-elisp-ignored-word-regexp
arg-string))
(funcall callback arg-string))))
(defun context-coloring-elisp-parse-let-varlist (type)
+ "Parse the list of variable initializers at point. If TYPE is
+`let', all the variables are bound after all their initializers
+are parsed; if TYPE is `let*', each variable is bound immediately
+after its own initializer is parsed."
(let ((varlist '())
syntax-code)
;; Enter.
@@ -515,7 +541,7 @@ smoother user experience for large files.")
(setq syntax-code (context-coloring-get-syntax-code))
(when (or (= syntax-code context-coloring-WORD-CODE)
(= syntax-code context-coloring-SYMBOL-CODE))
- (context-coloring-elisp-parse-arg
+ (context-coloring-elisp-parse-bindable
(lambda (var)
(push var varlist)))
(context-coloring-elisp-forward-sws)
@@ -527,7 +553,7 @@ smoother user experience for large files.")
(forward-char))
((or (= syntax-code context-coloring-WORD-CODE)
(= syntax-code context-coloring-SYMBOL-CODE))
- (context-coloring-elisp-parse-arg
+ (context-coloring-elisp-parse-bindable
(lambda (var)
(push var varlist)))))
(when (eq type 'let*)
@@ -540,6 +566,7 @@ smoother user experience for large files.")
(forward-char)))
(defun context-coloring-elisp-parse-arglist ()
+ "Parse the list of function arguments at point."
(let (syntax-code)
;; Enter.
(forward-char)
@@ -548,10 +575,11 @@ smoother user experience for large files.")
(cond
((or (= syntax-code context-coloring-WORD-CODE)
(= syntax-code context-coloring-SYMBOL-CODE))
- (context-coloring-elisp-parse-arg
+ (context-coloring-elisp-parse-bindable
(lambda (arg)
(context-coloring-elisp-add-variable arg))))
(t
+ ;; Ignore artifacts.
(context-coloring-elisp-forward-sexp)))
(context-coloring-elisp-forward-sws))
;; Exit.
@@ -559,6 +587,9 @@ smoother user experience for large files.")
(defun context-coloring-elisp-colorize-defun-like (&optional anonymous-p
let-type)
+ "Color the defun-like function at point. ANONYMOUS-P indicates
+the function doesn't name itself (e.g. `lambda', `let').
+LET-TYPE can be one of `let' or `let*'."
(let ((start (point))
end
stop
@@ -572,7 +603,7 @@ smoother user experience for large files.")
(context-coloring-colorize-region
start
end
- (context-coloring-elisp-current-scope-level))
+ (context-coloring-elisp-get-current-scope-level))
(goto-char start)
;; Enter.
(forward-char)
@@ -620,18 +651,23 @@ smoother user experience for large files.")
(context-coloring-elisp-pop-scope)))
(defun context-coloring-elisp-colorize-defun ()
+ "Color the `defun' (or defun-like function) at point."
(context-coloring-elisp-colorize-defun-like))
(defun context-coloring-elisp-colorize-lambda ()
+ "Color the `lambda' at point."
(context-coloring-elisp-colorize-defun-like t))
(defun context-coloring-elisp-colorize-let ()
+ "Color the `let' at point."
(context-coloring-elisp-colorize-defun-like t 'let))
(defun context-coloring-elisp-colorize-let* ()
+ "Color the `let*' at point."
(context-coloring-elisp-colorize-defun-like t 'let*))
(defun context-coloring-elisp-colorize-cond ()
+ "Color the `cond' at point."
(let (syntax-code)
;; Enter.
(forward-char)
@@ -651,12 +687,14 @@ smoother user experience for large files.")
;; Exit.
(forward-char)))
(t
+ ;; Ignore artifacts.
(context-coloring-elisp-forward-sexp)))
(context-coloring-elisp-forward-sws))
;; Exit.
(forward-char)))
(defun context-coloring-elisp-colorize-condition-case ()
+ "Color the `condition-case' at point."
(let ((start (point))
end
syntax-code
@@ -670,7 +708,7 @@ smoother user experience for large files.")
(context-coloring-colorize-region
start
end
- (context-coloring-elisp-current-scope-level))
+ (context-coloring-elisp-get-current-scope-level))
(goto-char start)
;; Enter.
(forward-char)
@@ -682,7 +720,7 @@ smoother user experience for large files.")
;; Gracefully ignore missing variables.
(when (or (= syntax-code context-coloring-WORD-CODE)
(= syntax-code context-coloring-SYMBOL-CODE))
- (context-coloring-elisp-parse-arg
+ (context-coloring-elisp-parse-bindable
(lambda (parsed-variable)
(setq variable parsed-variable)))
(context-coloring-elisp-forward-sws))
@@ -721,6 +759,7 @@ smoother user experience for large files.")
(context-coloring-elisp-pop-scope)))
(defun context-coloring-elisp-colorize-parenthesized-sexp ()
+ "Color the sexp enclosed by parenthesis at point."
(context-coloring-elisp-increment-sexp-count)
(let* ((start (point))
(end (progn (forward-sexp)
@@ -771,11 +810,12 @@ smoother user experience for large files.")
(context-coloring-colorize-region
start
end
- (context-coloring-elisp-current-scope-level))
+ (context-coloring-elisp-get-current-scope-level))
(context-coloring-elisp-colorize-region (point) (1- end))
(forward-char)))))
(defun context-coloring-elisp-colorize-symbol ()
+ "Color the symbol at point."
(context-coloring-elisp-increment-sexp-count)
(let* ((symbol-pos (point))
(symbol-end (progn (forward-sexp)
@@ -784,7 +824,7 @@ smoother user experience for large files.")
symbol-pos
symbol-end)))
(cond
- ((string-match-p context-coloring-ignored-word-regexp symbol-string))
+ ((string-match-p context-coloring-elisp-ignored-word-regexp
symbol-string))
(t
(context-coloring-colorize-region
symbol-pos
@@ -793,6 +833,8 @@ smoother user experience for large files.")
symbol-string))))))
(defun context-coloring-elisp-colorize-expression-prefix ()
+ "Color the expression prefix and the following expression at
+point. It could be a quoted or backquoted expression."
(context-coloring-elisp-increment-sexp-count)
(let ((char (char-after))
start
@@ -822,18 +864,19 @@ smoother user experience for large files.")
start end)))))
(defun context-coloring-elisp-colorize-comment ()
+ "Color the comment at point."
(context-coloring-elisp-increment-sexp-count)
(context-coloring-elisp-forward-sws))
(defun context-coloring-elisp-colorize-string ()
+ "Color the string at point."
(context-coloring-elisp-increment-sexp-count)
(let ((start (point)))
(forward-sexp)
- (context-coloring-maybe-colorize-comments-and-strings
- start
- (point))))
+ (context-coloring-colorize-comments-and-strings start (point))))
(defun context-coloring-elisp-colorize-sexp ()
+ "Color the sexp at point."
(let ((syntax-code (context-coloring-get-syntax-code)))
(cond
((= syntax-code context-coloring-OPEN-PARENTHESIS-CODE)
@@ -851,6 +894,7 @@ smoother user experience for large files.")
(forward-char)))))
(defun context-coloring-elisp-colorize-comments-and-strings-in-region (start
end)
+ "Color comments and strings between START and END."
(let (syntax-code)
(goto-char start)
(while (> end (progn (skip-syntax-forward "^<\"\\" end)
@@ -867,6 +911,7 @@ smoother user experience for large files.")
(forward-char))))))
(defun context-coloring-elisp-colorize-region (start end)
+ "Color everything between START and END."
(let (syntax-code)
(goto-char start)
(while (> end (progn (skip-syntax-forward "^()w_'<\"\\" end)
@@ -890,6 +935,7 @@ smoother user experience for large files.")
(forward-char))))))
(defun context-coloring-elisp-colorize-region-initially (start end)
+ "Begin coloring everything between START and END."
(setq context-coloring-elisp-sexp-count 0)
(setq context-coloring-elisp-scope-stack '())
(let ((inhibit-point-motion-hooks t)
@@ -932,7 +978,7 @@ separated by commas."
(pop tokens)
(pop tokens)
(pop tokens))))
- (context-coloring-maybe-colorize-comments-and-strings))
+ (context-coloring-colorize-comments-and-strings))
(defun context-coloring-parse-array (array)
"Parse ARRAY as a flat JSON array of numbers and use the tokens
@@ -997,6 +1043,9 @@ scopifying."
context-coloring-scopifier-process))
(defun context-coloring-start-scopifier-server (command host port callback)
+ "Connect to or start a scopifier server with COMMAND, HOST and PORT.
+Invoke CALLBACK with a network stream when the server is ready
+for connections."
(let* ((connect
(lambda ()
(let ((stream (open-network-stream "context-coloring-stream" nil
host port)))
@@ -1024,6 +1073,9 @@ scopifying."
(funcall connect)))))))))
(defun context-coloring-send-buffer-to-scopifier-server (command host port
callback)
+ "Send the current buffer to the scopifier server running with
+COMMAND, HOST and PORT. Invoke CALLBACK with the server's
+response (a stringified JSON array)."
(context-coloring-start-scopifier-server
command host port
(lambda (process)
@@ -1056,12 +1108,8 @@ scopifying."
(setq active nil)))))))
(defun context-coloring-scopify-and-colorize-server (command host port
&optional callback)
- "Contact or start a scopifier server via COMMAND at HOST and
-PORT with the current buffer's contents, read the scopifier's
-response asynchronously and apply a parsed list of tokens to
-`context-coloring-apply-tokens'.
-
-Invoke CALLBACK when complete."
+ "Color the current buffer via the server started with COMMAND,
+HOST and PORT. Invoke CALLBACK when complete."
(let ((buffer (current-buffer)))
(context-coloring-send-buffer-to-scopifier-server
command host port
@@ -1071,11 +1119,8 @@ Invoke CALLBACK when complete."
(when callback (funcall callback))))))
(defun context-coloring-scopify-and-colorize (command &optional callback)
- "Invoke a scopifier via COMMAND with the current buffer's contents,
-read the scopifier's response asynchronously and apply a parsed
-list of tokens to `context-coloring-apply-tokens'.
-
-Invoke CALLBACK when complete."
+ "Color the current buffer via COMMAND. Invoke CALLBACK when
+complete."
(let ((buffer (current-buffer)))
(context-coloring-scopify-shell-command
command
@@ -1091,7 +1136,7 @@ Invoke CALLBACK when complete."
(defvar context-coloring-dispatch-hash-table (make-hash-table :test #'eq)
"Map dispatch strategy names to their corresponding property
- lists, which contain details about the strategies.")
+lists, which contain details about the strategies.")
(defvar context-coloring-mode-hash-table (make-hash-table :test #'eq)
"Map major mode names to dispatch property lists.")
@@ -1246,7 +1291,7 @@ version number required for the current major mode."
(defvar context-coloring-originally-set-theme-hash-table
(make-hash-table :test #'eq)
"Cache custom themes who originally set their own
- `context-coloring-level-N-face' faces.")
+`context-coloring-level-N-face' faces.")
(defun context-coloring-theme-originally-set-p (theme)
"Return t if there is a `context-coloring-level-N-face'
diff --git a/test/context-coloring-coverage.el
b/test/context-coloring-coverage.el
index cbd1e47..107908c 100644
--- a/test/context-coloring-coverage.el
+++ b/test/context-coloring-coverage.el
@@ -152,4 +152,4 @@
(provide 'context-coloring-coverage)
-;; context-coloring-coverage.el ends here
+;;; context-coloring-coverage.el ends here
diff --git a/test/context-coloring-test.el b/test/context-coloring-test.el
index 8e95219..bd37b3b 100644
--- a/test/context-coloring-test.el
+++ b/test/context-coloring-test.el
@@ -221,7 +221,8 @@ override it."
(setq js2-mode-show-strict-warnings nil)))
(defmacro context-coloring-test-deftest-js-js2 (&rest args)
- "Simultaneously define the same test for js and js2."
+ "Simultaneously define the same test for js and js2 (with
+ARGS)."
(declare (indent defun))
`(progn
(context-coloring-test-deftest-js ,@args)
@@ -347,7 +348,7 @@ override it."
(setq context-coloring-colorize-hook nil)))
(defmacro context-coloring-test-define-derived-mode (name)
- "Define a derived mode exclusively for tests."
+ "Define a derived mode exclusively for any test with NAME."
(let ((name (intern (format "context-coloring-test-%s-mode" name))))
`(define-derived-mode ,name fundamental-mode "Testing")))
@@ -519,8 +520,8 @@ FOREGROUND. Apply ARGUMENTS to
(defun context-coloring-test-assert-theme-originally-set-p
(settings &optional negate)
- "Assert that `context-coloring-theme-originally-set-p' returns
-t for a theme with SETTINGS, or the inverse if NEGATE is
+ "Assert that `context-coloring-theme-originally-set-p' will
+return t for a theme with SETTINGS, or the inverse if NEGATE is
non-nil."
(let ((theme (context-coloring-test-get-next-theme)))
(put theme 'theme-settings settings)
@@ -894,7 +895,7 @@ see that function."
(context-coloring-test-assert-position-face position nil))
(defun context-coloring-test-assert-coloring (map)
- "Assert that the current buffer's coloring matches MAP.
+ "Assert that the current buffer's coloring will match MAP.
MAP's newlines should correspond to the current fixture.
