X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/fadacd1baa32e42dbba61d792db1119cda11a8ee..3007b2917d71a7d66eb94876536dfd80b0661d40:/README.md diff --git a/README.md b/README.md index 7e96bb78f..21f1eb5cf 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,66 @@ -# Context Coloring [![Build Status](https://travis-ci.org/jacksonrayhamilton/context-coloring.png?branch=develop)](https://travis-ci.org/jacksonrayhamilton/context-coloring) +# Context Coloring [![Build Status](https://travis-ci.org/jacksonrayhamilton/context-coloring.png?branch=master)](https://travis-ci.org/jacksonrayhamilton/context-coloring) [![Coverage Status](https://coveralls.io/repos/jacksonrayhamilton/context-coloring/badge.svg?branch=master)](https://coveralls.io/r/jacksonrayhamilton/context-coloring?branch=master)

Screenshot of JavaScript code highlighted by context.

-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. -- Fast async AST parsing. Some total parse + recolor times: - - jQuery (9191 lines): 0.63 seconds - - Lodash (6786 lines): 0.37 seconds - - Async (1124 lines): 0.17 seconds - - mkdirp (98 lines): 0.09 seconds - -## Usage +- 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. -Requires Emacs 24+. +## Installation -JavaScript language support requires either [js2-mode][] or -[Node.js 0.10+][node], respectively. - -- Clone this repository. - -```bash -cd ~/.emacs.d/ -git clone https://github.com/jacksonrayhamilton/context-coloring.git -``` +Requires Emacs 24.3+. JavaScript language support requires +[js2-mode](https://github.com/mooz/js2-mode). -- 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) -``` - -## 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. +;; JavaScript: +(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode)) +(add-hook 'js2-mode-hook #'context-coloring-mode) -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, +;; Emacs Lisp: +(add-hook 'emacs-lisp-mode-hook #'context-coloring-mode) -```js -var a = function () {}; +;; eval-expression: +(add-hook 'eval-expression-minibuffer-setup-hook #'context-coloring-mode) ; 24.4+ +(add-hook 'minibuffer-setup-hook #'context-coloring-mode) ; 24.3 ``` -then the scopifier would produce the following array: +## Color Schemes -```js -[1,24,0,9,23,1] -``` +The [Zenburn](https://github.com/bbatsov/zenburn-emacs) theme, featured in the +screenshot above, now supports context coloring. -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: +You can define your own colors by customizing faces like +`context-coloring-level-N-face`, where N is a number starting from 0. -

- Screenshot of ranges [1, 24) and [9, 23). -

+[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 lengths 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.