code.delx.au - gnu-emacs-elpa/blob - README.md

   1 # Context Coloring
   2
   3 <p align="center">
   4   <img alt="Screenshot of JavaScript code highlighted by context." src="screenshot.png" title="Screenshot">
   5 </p>
   6
   7 Highlights code according to function context.
   8
   9 - Code in the global scope is one color. Code in functions within the global
  10   scope is a different color, and code within such functions is another color,
  11   and so on.
  12 - Identifiers retain the color of the scope in which they were declared.
  13 - Comments are gray.
  14
  15 Lexical scope information at-a-glance can assist a programmer in understanding
  16 the overall structure of a program. It can also help curb nasty bugs like name
  17 shadowing or unexpected assignment. A rainbow can indicate excessive
  18 complexity. A spot of contrast followed by an assignment expression could be a
  19 side-effect... or, the state of a closure could be undergoing change.
  20
  21 This coloring strategy is probably more useful than conventional *syntax*
  22 highlighting. Highlighting keywords can help one to detect spelling errors, and
  23 highlighting the content between quotation marks can alert one to unclosed
  24 string literals. But a [linter][] could also spot those errors, and if
  25 [integrated via flycheck][integration], an extra spot opens up in your editing
  26 toolbelt.
  27
  28 Give context coloring a try; you may find that it *changes the way you write
  29 code*.
  30
  31 ## Features
  32
  33 - Supported languages: JavaScript
  34 - Light and dark (customizable) color schemes.
  35 - Fast async AST parsing. Some total parse + recolor times:
  36   - jQuery (9191 lines): 0.63 seconds
  37   - Lodash (6786 lines): 0.37 seconds
  38   - Async (1124 lines): 0.17 seconds
  39   - mkdirp (98 lines): 0.09 seconds
  40
  41 ## Extending
  42
  43 It would be great if this package supported more languages. I welcome any pull
  44 request that adds new language support.
  45
  46 Extension is relatively straightforward. Write a "scopifier" for the language of
  47 your choice, add an entry to `context-coloring-dispatch-plist`, and the plugin
  48 should handle the rest.
  49
  50 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
  51 writes a JSON array of numbers to stdout. Every three numbers in the array
  52 represent a range of color. For instance, if I fed the following string of
  53 JavaScript code to a scopifier,
  54
  55 ```js
  56 var a = function () {};
  57 ```
  58
  59 then the scopifier would produce the following array:
  60
  61 ```js
  62 [1,24,0,9,23,1]
  63 ```
  64
  65 Where, for every three numbers, the first number is a 1-indexed start [point][],
  66 the second number is an exclusive end point, and the third number is a scope
  67 level. The result of applying level 0 coloring to the range
  68 \[1, 24) and then applying level 1 coloring to the range \[9, 23) would result in the following coloring:
  69
  70 <p align="center">
  71   <img alt="Screenshot of ranges [1, 24) and [9, 23)." src="scopifier-example.png" title="Screenshot">
  72 </p>
  73
  74 ## Usage
  75
  76 Requires Emacs 24+.
  77
  78 JavaScript language support requires [Node.js 0.10+][node].
  79
  80 - Clone this repository.
  81
  82 ```bash
  83 cd ~/.emacs.d/
  84 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  85 ```
  86
  87 - Add the following to your `~/.emacs` file:
  88
  89 ```lisp
  90 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  91 (require 'context-coloring)
  92 (add-hook 'js-mode-hook 'context-coloring-mode)
  93 ```
  94
  95 [linter]: https://github.com/jacksonrayhamilton/jslinted
  96 [integration]: https://github.com/jacksonrayhamilton/jslinted#emacs-integration
  97 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
  98 [node]: http://nodejs.org/download/
  99 [load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html