-# Context Coloring [](https://travis-ci.org/jacksonrayhamilton/context-coloring)
+# Context Coloring [](https://travis-ci.org/jacksonrayhamilton/context-coloring) [](https://coveralls.io/r/jacksonrayhamilton/context-coloring?branch=master)
<p align="center">
<img alt="Screenshot of JavaScript code highlighted by context." src="screenshot.png" title="Screenshot">
</p>
-Highlights code according to function context.
+Highlights code by scope. Top-level scopes are one color, second-level scopes
+are another color, and so on. Variables retain the color of the scope in which
+they are defined. A variable defined in an outer scope referenced by an inner
+scope is colored the same as the outer scope.
-- Code in the global scope is one color. Code in functions within the global
- scope is a different color, and code within such functions is another color,
- and so on.
-- Identifiers retain the color of the scope in which they were declared.
-- Comments are gray.
-
-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 name
-shadowing or unexpected assignment. A rainbow can indicate excessive
-complexity. A spot of contrast followed by an assignment expression could be a
-side-effect... or, the state of a closure could be undergoing change.
-
-This coloring strategy is probably more useful than conventional *syntax*
-highlighting. Highlighting keywords can help one to detect spelling errors, and
-highlighting the content between quotation marks can alert one to unclosed
-string literals. But a [linter][] could also spot those errors, and if
-[integrated via flycheck][integration], an extra spot opens up in your editing
-toolbelt.
-
-Give context coloring a try; you may find that it *changes the way you write
-code*.
+By default, comments and strings are still highlighted syntactically.
## Features
-- Supported languages: JavaScript
- Light and dark (customizable) color schemes.
-- Insanely fast for regular files, quick for big ones too.
- - jQuery (9191 lines): 0.20 seconds (js2-mode), 0.57 seconds (js-mode)
- - Lodash (6786 lines): 0.07 seconds (js2-mode), 0.35 seconds (js-mode)
- - Async (1124 lines): 0.03 seconds (js2-mode), 0.17 seconds (js-mode)
- - mkdirp (98 lines): 0.002 seconds (js2-mode), 0.09 seconds (js-mode)
+- JavaScript support:
+ - Script, function and block scopes (and even `catch` block scopes).
+ - Very fast for files under 1000 lines.
+- Emacs Lisp support:
+ - `defun`, `lambda`, `let`, `let*`, `cond`, `condition-case`, quotes,
+ backquotes (and splicing).
+ - 25,000 lines per second!
-\* js2-mode parses idly, irrespective of this plugin; its benchmarks represent
-coloring only. js-mode benchmarks represent parsing and coloring.
-
-## Usage
+## Installation
Requires Emacs 24+.
-JavaScript language support requires either [js2-mode][] or
-[Node.js 0.10+][node], respectively.
+JavaScript language support requires either [js2-mode][], or
+[Node.js 0.10+][node] and the [scopifier][] executable.
+
+### ELPA
+
+- `M-x package-install RET context-coloring RET`
+
+### Git
- Clone this repository.
make compile
```
-- Add the following to your `~/.emacs` file:
+- Add the following to your init file:
```lisp
(add-to-list 'load-path "~/.emacs.d/context-coloring")
(require 'context-coloring)
+```
+
+### Dependencies (js-mode)
+
+```bash
+npm install -g scopifier
+```
+
+## Usage
+
+Add the following to your init file:
+
+```lisp
+;; js-mode:
(add-hook 'js-mode-hook 'context-coloring-mode)
+
+;; js2-mode:
+(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
+(add-hook 'js2-mode-hook 'context-coloring-mode)
+
+;; emacs-lisp-mode:
+(add-hook 'emacs-lisp-mode-hook 'context-coloring-mode)
```
+## Customizing
+
+### Options
+
+- `context-coloring-syntactic-comments` (default: `t`): If non-nil, also color
+ comments using `font-lock`.
+- `context-coloring-syntactic-strings` (default: `t`): If non-nil, also color
+ strings using `font-lock`.
+- `context-coloring-default-delay` (default: `0.25`; supported modes: `js-mode`,
+ `js3-mode`): Default (sometimes overridden) delay between a buffer update and
+ colorization.
+- `context-coloring-js-block-scopes` (default: `nil`; supported modes:
+ `js2-mode`): If non-nil, also color block scopes in the scope hierarchy in
+ JavaScript.
+
+### Color Schemes
+
+Color schemes for custom themes are automatically applied when those themes are
+active. Built-in theme support is available for: `ample`, `anti-zenburn`,
+`grandshell`, `leuven`, `monokai`, `solarized`, `spacegray`, `tango` and
+`zenburn`.
+
+You can define your own theme colors too:
+
+```lisp
+(context-coloring-define-theme
+ 'zenburn
+ :colors '("#dcdccc"
+ "#93e0e3"
+ "#bfebbf"
+ "#f0dfaf"
+ "#dfaf8f"
+ "#cc9393"
+ "#dc8cc3"
+ "#94bff3"
+ "#9fc59f"
+ "#d0bf8f"
+ "#dca3a3"))
+```
+
+See `C-h f context-coloring-define-theme` for more info on theme parameters.
+
## Extending
-To add support for a new language, write a "scopifier" for it, and add an entry
-to `context-coloring-dispatch-plist`. Then the plugin should handle the rest.
+To add support for a new language, write a "scopifier" for it, and define a new
+coloring dispatch strategy with `context-coloring-define-dispatch`. Then the
+plugin should handle the rest. (See `C-h f context-coloring-define-dispatch`
+for more info on dispatch strategies.)
A "scopifier" is a CLI program that reads a buffer's contents from stdin and
-writes a JSON array of numbers to stdout. Every three numbers in the array
-represent a range of color. For instance, if I fed the following string of
-JavaScript code to a scopifier,
+writes a JSON array of numbers to stdout. Every three numbers in the array
+represent a range of color. For instance, if I fed the following string of
+JavaScript code to a scopifier
```js
var a = function () {};
```
-then the scopifier would produce the following array:
+then the scopifier would produce the following array
```js
[1,24,0,9,23,1]
```
-Where, for every three numbers, the first number is a 1-indexed start [point][],
+where, for every three numbers, the first number is a 1-indexed start [point][],
the second number is an exclusive end point, and the third number is a scope
-level. The result of applying level 0 coloring to the range [1, 24) and then
-applying level 1 coloring to the range [9, 23) would result in the following
-coloring:
+level. The result of applying level 0 coloring to the range [1, 24) and
+then applying level 1 coloring to the range [9, 23) would result in the
+following coloring:
<p align="center">
- <img alt="Screenshot of ranges [1, 24) and [9, 23)." src="scopifier-example.png" title="Screenshot">
+ <img alt="Screenshot of ranges [1, 24) and [9, 23)." src="scopifier.png" title="Screenshot">
</p>
If there is an abstract syntax tree generator for your language, you can walk
the syntax tree, find variables and scopes, and build their positions and levels
into an array like the one above.
-[linter]: https://github.com/jacksonrayhamilton/jslinted
-[integration]: https://github.com/jacksonrayhamilton/jslinted#emacs-integration
-[point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
+For example, a Ruby scopifier might be defined and implemented like this:
+
+```lisp
+(context-coloring-define-dispatch
+ 'ruby
+ :modes '(ruby-mode)
+ :executable "ruby"
+ :command "/home/username/scopifier")
+```
+
+```ruby
+#!/usr/bin/env ruby
+def scopifier(code)
+ # Parse code.
+ # Return an array.
+end
+print scopifier ARGF.read
+```
+
+When a `--version` argument is passed, a scopifier should print its version
+number and exit. This allows context-coloring to determine if an update is
+required.
+
+Alternatively, you could implement a "colorizer" in Emacs Lisp. A colorizer
+also handles the job of calling `context-coloring-colorize-region` to apply
+colors to a buffer. A colorizer may have better performance than a scopifier
+when parsing and coloring can be performed in the same pass.
+
[js2-mode]: https://github.com/mooz/js2-mode
[node]: http://nodejs.org/download/
-[load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html
+[scopifier]: https://github.com/jacksonrayhamilton/scopifier
+[point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html