doc
:group 'context-coloring)))
-;; Provide some default colors based off Emacs' defaults.
+;; Provide some default colors based off Emacs's defaults.
(context-coloring-defface 0 "#000000" "#ffffff" nil)
(context-coloring-defface 1 "#008b8b" "#00ffff" "yellow")
(context-coloring-defface 2 "#0000ff" "#87cefa" "green")
(context-coloring-defface 6 "#228b22" "#7fffd4" "red")
(context-coloring-defface 7 "#3f3f3f" "#cdcdcd" nil)
-(defconst context-coloring-default-maximum-face 7)
+(defconst context-coloring-default-maximum-face 7
+ "Maximum face when there are no custom faces.")
;; Create placeholder faces for users and theme authors.
(dotimes (level 18)
"Dynamic index of the highest face available for coloring.")
(defsubst context-coloring-level-face (level)
- "Return the symbol for a face with LEVEL."
+ "Return symbol for face with LEVEL."
;; `concat' is faster than `format' here.
(intern-soft
(concat "context-coloring-level-" (number-to-string level) "-face")))
(defsubst context-coloring-bounded-level-face (level)
- "Return the symbol for a face with LEVEL, bounded by
-`context-coloring-maximum-face'."
+ "Return symbol for face with LEVEL, bounded by the maximum."
(context-coloring-level-face (min level context-coloring-maximum-face)))
(defconst context-coloring-level-face-regexp
;;; Colorization utilities
(defsubst context-coloring-colorize-region (start end level)
- "Color characters from the 1-indexed START point (inclusive) to
-the END point (exclusive) with the face corresponding to LEVEL."
+ "Color from START (inclusive) to END (exclusive) with LEVEL."
(add-text-properties
start
end
:group 'context-coloring)
(defun context-coloring-font-lock-syntactic-comment-function (state)
- "Tell `font-lock' to color a comment but not a string according
-to STATE."
+ "Color a comment according to STATE."
(if (nth 3 state) nil font-lock-comment-face))
(defun context-coloring-font-lock-syntactic-string-function (state)
- "Tell `font-lock' to color a string but not a comment according
-to STATE."
+ "Color a string according to STATE."
(if (nth 3 state) font-lock-string-face nil))
(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. MIN defaults
-to the beginning of the buffer and MAX defaults to the end."
+ "Maybe color comments and strings in buffer from MIN to MAX.
+MIN defaults to beginning of buffer. MAX defaults to end."
(when (or context-coloring-syntactic-comments
context-coloring-syntactic-strings)
(let ((min (or min (point-min)))
(puthash scope level context-coloring-js2-scope-level-hash-table)))))
(defsubst context-coloring-js2-local-name-node-p (node)
- "Determine if NODE is a `js2-name-node' representing a local
-variable."
+ "Determine if NODE represents a local variable."
(and (js2-name-node-p node)
(let ((parent (js2-node-parent node)))
(not (or (and (js2-object-prop-node-p parent)
level)))
(defun context-coloring-js2-colorize ()
- "Color the current buffer using the abstract syntax tree
-generated by `js2-mode'."
+ "Color the buffer using the `js2-mode' abstract syntax tree."
;; Reset the hash table; the old one could be obsolete.
(setq context-coloring-js2-scope-level-hash-table (make-hash-table :test #'eq))
(setq context-coloring-point-max (point-max))
(while (forward-comment 1)))
(defsubst context-coloring-elisp-forward-sws ()
- "Move forward through whitespace and comments, colorizing
-comments along the way."
+ "Move through whitespace and comments, coloring comments."
(let ((start (point)))
(context-coloring-forward-sws)
(context-coloring-colorize-comments-and-strings start (point))))
(defsubst context-coloring-elisp-forward-sexp ()
- "Like `forward-sexp', but colorize comments and strings along
-the way."
+ "Like `forward-sexp', coloring skipped comments and strings."
(let ((start (point)))
(forward-sexp)
(context-coloring-elisp-colorize-comments-and-strings-in-region
(context-coloring-exact-or-regexp
'("t" "nil" "." "?")))
"\\|")
- "Match words that might be considered symbols but can't be
-bound as variables.")
+ "Match symbols that can't be bound as variables.")
(defconst context-coloring-WORD-CODE 2)
(defconst context-coloring-SYMBOL-CODE 3)
"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."
+ "Maybe check if the user interrupted the current parse."
(setq context-coloring-elisp-sexp-count
(1+ context-coloring-elisp-sexp-count))
(when (and (zerop (% context-coloring-elisp-sexp-count
(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."
+ "Return the level of VARIABLE, or 0 if it isn't found."
(let* ((scope-stack context-coloring-elisp-scope-stack)
scope
level)
variable))
(defsubst context-coloring-elisp-parse-bindable (callback)
- "Parse the symbol at point, and if the symbol can be bound,
-invoke CALLBACK with it."
+ "Parse the symbol at point.
+If the symbol can be bound, invoke CALLBACK with it."
(let* ((arg-string (buffer-substring-no-properties
(point)
(progn (context-coloring-elisp-forward-sexp)
(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."
+ "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.
(context-coloring-elisp-forward-sws))
(defun context-coloring-elisp-colorize-scope (callback)
- "Color the whole scope at point with its one color. Handle a
-header in CALLBACK."
+ "Color the whole scope at point with its one color.
+Handle a header in CALLBACK."
(let ((start (point))
(end (progn (forward-sexp)
(point))))
(funcall callback)))
(defun context-coloring-elisp-colorize-defun-like (callback)
- "Color the defun-like function at point, parsing the header
-with CALLBACK."
+ "Color the defun-like function at point.
+Parse the header with CALLBACK."
(context-coloring-elisp-colorize-scope
(lambda ()
(when (context-coloring-elisp-identifier-p (context-coloring-get-syntax-code))
(context-coloring-elisp-forward-sws))))))
(defun context-coloring-elisp-colorize-lambda-like (callback)
- "Color the lambda-like function at point, parsing the header
-with CALLBACK."
+ "Color the lambda-like function at point.
+Parsing the header with CALLBACK."
(context-coloring-elisp-colorize-scope
(lambda ()
(context-coloring-elisp-parse-header callback))))
(forward-char))
(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."
+ "Color the expression prefix and expression at point.
+It could be a quoted or backquoted expression."
(context-coloring-elisp-increment-sexp-count)
(cond
((/= (char-after) context-coloring-BACKTICK-CHAR)
(scan-error (progn))))))
(defun context-coloring-elisp-colorize ()
- "Color the current buffer, parsing elisp to determine its
-scopes and variables."
+ "Color the current Emacs Lisp buffer."
(interactive)
(context-coloring-elisp-colorize-guard
(lambda ()
;;; Dispatch
(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.")
+ "Map dispatch strategy names to their property lists.")
(defvar context-coloring-mode-hash-table (make-hash-table :test #'eq)
"Map major mode names to dispatch property lists.")
properties)) context-coloring-dispatch-predicates))))
(defun context-coloring-dispatch ()
- "Determine the optimal track for scopification / coloring of
-the current buffer, then execute it."
+ "Determine how to color the current buffer, and color it."
(let* ((dispatch (context-coloring-get-current-dispatch))
(colorizer (plist-get dispatch :colorizer)))
(catch 'interrupted