X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/fb538848d7328bcd946e1fecd1cd00096b574e5c..ec9f04d4fa1088ff14adb2b35e4a8ecb7a9ca65e:/README.md diff --git a/README.md b/README.md index 1e84ff28d..03bf677a3 100644 --- a/README.md +++ b/README.md @@ -4,35 +4,23 @@ 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 are declared. - -Lexical scope information at-a-glance can assist a programmer in understanding -the overall structure of a program. It can help to curb nasty bugs like name -shadowing. A rainbow can indicate excessive complexity. State change within a -closure is easily monitored. - -By default, context-coloring still highlights comments and strings -syntactically. It is still easy to differentiate code from non-code, and strings -cannot be confused for variables. - -This coloring strategy is probably more useful than conventional syntax -highlighting. Highlighting keywords can help one to detect spelling errors, but -a [linter][] could also spot those errors, and if integrated with [flycheck][], -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. -- Very fast for files under 1000 lines. +- 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! ## Installation @@ -61,14 +49,14 @@ cd context-coloring/ 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) ``` -### scopifier (for non-js2-mode users) +### Dependencies (js-mode) ```bash npm install -g scopifier @@ -76,15 +64,18 @@ npm install -g scopifier ## Usage -Add the following to your `~/.emacs` file: +Add the following to your init file: ```lisp -;; non-js2-mode users: +;; js-mode: (add-hook 'js-mode-hook 'context-coloring-mode) -;; js2-mode users: +;; 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 @@ -95,8 +86,9 @@ Add the following to your `~/.emacs` file: 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-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. @@ -104,7 +96,7 @@ Add the following to your `~/.emacs` file: ### 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`, +active. Built-in theme support is available for: `ample`, `anti-zenburn`, `grandshell`, `leuven`, `monokai`, `solarized`, `spacegray`, `tango` and `zenburn`. @@ -113,17 +105,17 @@ 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")) + :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. @@ -131,13 +123,13 @@ 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.) +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 +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 @@ -152,9 +144,9 @@ then the scopifier would produce the following array 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:

Screenshot of ranges [1, 24) and [9, 23). @@ -184,11 +176,14 @@ 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 +number and exit. This allows context-coloring to determine if an update is required. -[linter]: http://jshint.com/about/ -[flycheck]: http://www.flycheck.org/ +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/ [scopifier]: https://github.com/jacksonrayhamilton/scopifier