X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/6706bc2b0a1a58f5b8564d58f8501e27b8b4c234..3007b2917d71a7d66eb94876536dfd80b0661d40:/README.md
diff --git a/README.md b/README.md
index b687f453c..21f1eb5cf 100644
--- a/README.md
+++ b/README.md
@@ -1,149 +1,66 @@
-# 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)
-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)
-
-\* js2-mode parses idly, irrespective of this plugin; its benchmarks represent
-coloring only. js-mode benchmarks represent parsing and coloring.
-
-## Usage
-
-Requires Emacs 24+.
+- Light and dark customizable color schemes.
+- JavaScript support:
+ - Script, function and block scopes (and even `catch` block scopes).
+ - Node.js "file-level" scope detection.
+- Emacs Lisp support:
+ - `defun`, `lambda`, `let`, `let*`, `cond`, `condition-case`, `defadvice`,
+ `dolist`, `quote`, `backquote` and backquote splicing.
+ - Works in `eval-expression` too.
-JavaScript language support requires either [js2-mode][] or
-[Node.js 0.10+][node], respectively.
+## Installation
-- Clone this repository.
+Requires Emacs 24.3+. JavaScript language support requires
+[js2-mode](https://github.com/mooz/js2-mode).
-```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 `~/.emacs` file:
+To install, run the command `M-x package-install RET context-coloring RET`, and
+then add the following to your init file:
```lisp
-(add-to-list 'load-path "~/.emacs.d/context-coloring")
-(require 'context-coloring)
-(add-hook 'js-mode-hook 'context-coloring-mode)
-```
+;; JavaScript:
+(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
+(add-hook 'js2-mode-hook #'context-coloring-mode)
-## Customizing
+;; Emacs Lisp:
+(add-hook 'emacs-lisp-mode-hook #'context-coloring-mode)
-You can adjust the colors to your liking using
-`context-coloring-set-colors`. The first argument is an alist of levels, and the
-optional second argument is the new total number of levels. This plugin does not
-figure out the total for you; you need to specify it if your number of colors is
-different from the default (`7`).
-
-I like to take the colors from an existing theme and use those to create a
-rainbow that matches that theme. The end result is consistent, and usually looks
-as good as the theme does. Here's an example for `tango`:
-
-```lisp
-;; ~/.emacs
-(load-theme 'tango)
-(require 'context-coloring)
-(defun jrh-context-coloring-tango ()
- (interactive)
- (context-coloring-set-colors
- '((comment . "#5f615c")
- (0 . "#2e3436") ; Globals.
- (1 . "#346604")
- (2 . "#204a87")
- (3 . "#5c3566")
- (4 . "#a40000")
- (5 . "#b35000")
- (6 . "#c4a000")
- (7 . "#8ae234") ; "You're screwed" colors.
- (8 . "#8cc4ff")
- (9 . "#ad7fa8")
- (10 . "#ef2929")
- (11 . "#fcaf3e")
- (12 . "#fce94f"))
- 13))
-(jrh-context-coloring-tango)
+;; eval-expression:
+(add-hook 'eval-expression-minibuffer-setup-hook #'context-coloring-mode) ; 24.4+
+(add-hook 'minibuffer-setup-hook #'context-coloring-mode) ; 24.3
```
-## Extending
+## Color Schemes
-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.
-
-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 () {};
-```
+The [Zenburn](https://github.com/bbatsov/zenburn-emacs) theme, featured in the
+screenshot above, now supports context coloring.
-then the scopifier would produce the following array:
+You can define your own colors by customizing faces like
+`context-coloring-level-N-face`, where N is a number starting from 0.
-```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:
-
-
- 
-
+[See here](https://gist.github.com/jacksonrayhamilton/6b89ca3b85182c490816) for
+some color schemes for popular custom themes.
-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.
+## Options
-[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
-[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
+- `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-javascript-block-scopes` (default: `nil`): If non-nil, also
+ color block scopes in the scope hierarchy in JavaScript.
+- `context-coloring-javascript-detect-top-level-scope` (default: `t`): If
+ non-nil, detect when to use file-level scope.