-# 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 JavaScript 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 in 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.
-- Identifiers are bold when first declared.
-- Comments are gray and italic.
+By default, comments and strings are still highlighted syntactically.
-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 followed by an assignment expression could be a
-side-effect... or, a specially-constructed object's private state could be
-undergoing change.
+## Features
-This coloring scheme is probably more useful than conventional JavaScript
-*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][].
+- Supported languages: JavaScript
+- Light and dark (customizable) color schemes.
+- Very fast for files under 1000 lines.
-## Features
+## Installation
-- Light and dark color schemes.
-- Fast async AST parsing. Some total parse + recolor times:
- - jQuery (9191 lines): 0.72 seconds
- - Lodash (6786 lines): 0.40 seconds
- - Async (1124 lines): 0.20 seconds
- - mkdirp (98 lines): 0.09 seconds
+Requires Emacs 24+.
-## Usage
+JavaScript language support requires either [js2-mode][], or
+[Node.js 0.10+][node] and the [scopifier][] executable.
+
+### ELPA
-Requires Emacs 24+ and [Node.js 0.10+][node].
+- `M-x package-install RET context-coloring RET`
+
+### Git
- Clone this repository.
-- Run `make` in it.
-- Add it to your [load path][].
-- Add the following to your `~/.emacs`:
+
+```bash
+cd ~/.emacs.d/
+git clone https://github.com/jacksonrayhamilton/context-coloring.git
+```
+
+- Byte-compile the package for improved speed.
+
+```bash
+cd context-coloring/
+make compile
+```
+
+- Add the following to your init file:
```lisp
+(add-to-list 'load-path "~/.emacs.d/context-coloring")
(require 'context-coloring)
+```
+
+### scopifier (for non-js2-mode users)
+
+```bash
+npm install -g scopifier
+```
+
+## Usage
+
+Add the following to your init file:
+
+```lisp
+;; non-js2-mode users:
(add-hook 'js-mode-hook 'context-coloring-mode)
+
+;; js2-mode users:
+(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
+(add-hook 'js2-mode-hook 'context-coloring-mode)
```
-[linter]: https://github.com/jacksonrayhamilton/jslinted
-[flycheck]: https://github.com/flycheck/flycheck
+## 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-delay` (default: `0.25`; supported modes: `js-mode`,
+ `js3-mode`): 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 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
+
+```js
+var a = function () {};
+```
+
+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][],
+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:
+
+<p align="center">
+ <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.
+
+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.
+
+[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