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

   1 # Context Coloring [![Build Status](https://travis-ci.org/jacksonrayhamilton/context-coloring.png?branch=develop)](https://travis-ci.org/jacksonrayhamilton/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 - Insanely fast for regular files, quick for big ones too.
  36   - jQuery (9191 lines): 0.20 seconds (js2-mode), 0.57 seconds (js-mode)
  37   - Lodash (6786 lines): 0.07 seconds (js2-mode), 0.35 seconds (js-mode)
  38   - Async (1124 lines): 0.03 seconds (js2-mode), 0.17 seconds (js-mode)
  39   - mkdirp (98 lines): 0.002 seconds (js2-mode), 0.09 seconds (js-mode)
  40
  41 \* js2-mode parses idly, irrespective of this plugin; its benchmarks represent
  42 coloring only. js-mode benchmarks represent parsing and coloring.
  43
  44 ## Usage
  45
  46 Requires Emacs 24+.
  47
  48 JavaScript language support requires either [js2-mode][] or
  49 [Node.js 0.10+][node], respectively.
  50
  51 - Clone this repository.
  52
  53 ```bash
  54 cd ~/.emacs.d/
  55 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  56 ```
  57
  58 - Byte-compile the package for improved speed.
  59
  60 ```bash
  61 cd context-coloring/
  62 make compile
  63 ```
  64
  65 - Add the following to your `~/.emacs` file:
  66
  67 ```lisp
  68 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  69 (require 'context-coloring)
  70 (add-hook 'js-mode-hook 'context-coloring-mode)
  71 ```
  72
  73 ## Customizing
  74
  75 You can adjust the colors to your liking using
  76 `context-coloring-set-colors`. The first argument is an alist of levels, and the
  77 optional second argument is the new total number of levels. This plugin does not
  78 figure out the total for you; you need to specify it if your number of colors is
  79 different from the default (`7`).
  80
  81 I like to take the colors from an existing theme and use those to create a
  82 rainbow that matches that theme. The end result is consistent, and usually looks
  83 as good as the theme does. Here's an example for `tango`:
  84
  85 ```lisp
  86 ;; ~/.emacs
  87 (load-theme 'tango)
  88 (require 'context-coloring)
  89 (defun jrh-context-coloring-tango ()
  90   (interactive)
  91   (context-coloring-set-colors
  92    '((comment . "#5f615c")
  93      (0       . "#2e3436") ; Globals.
  94      (1       . "#346604")
  95      (2       . "#204a87")
  96      (3       . "#5c3566")
  97      (4       . "#a40000")
  98      (5       . "#b35000")
  99      (6       . "#c4a000")
 100      (7       . "#8ae234") ; "You're screwed" colors.
 101      (8       . "#8cc4ff")
 102      (9       . "#ad7fa8")
 103      (10      . "#ef2929")
 104      (11      . "#fcaf3e")
 105      (12      . "#fce94f"))
 106    13))
 107 (jrh-context-coloring-tango)
 108 ```
 109
 110 ## Extending
 111
 112 To add support for a new language, write a "scopifier" for it, and add an entry
 113 to `context-coloring-dispatch-plist`. Then the plugin should handle the rest.
 114
 115 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
 116 writes a JSON array of numbers to stdout. Every three numbers in the array
 117 represent a range of color. For instance, if I fed the following string of
 118 JavaScript code to a scopifier,
 119
 120 ```js
 121 var a = function () {};
 122 ```
 123
 124 then the scopifier would produce the following array:
 125
 126 ```js
 127 [1,24,0,9,23,1]
 128 ```
 129
 130 Where, for every three numbers, the first number is a 1-indexed start [point][],
 131 the second number is an exclusive end point, and the third number is a scope
 132 level. The result of applying level 0 coloring to the range &#91;1, 24) and then
 133 applying level 1 coloring to the range &#91;9, 23) would result in the following
 134 coloring:
 135
 136 <p align="center">
 137   <img alt="Screenshot of ranges &#91;1, 24) and &#91;9, 23)." src="scopifier-example.png" title="Screenshot">
 138 </p>
 139
 140 If there is an abstract syntax tree generator for your language, you can walk
 141 the syntax tree, find variables and scopes, and build their positions and levels
 142 into an array like the one above.
 143
 144 [linter]: https://github.com/jacksonrayhamilton/jslinted
 145 [integration]: https://github.com/jacksonrayhamilton/jslinted#emacs-integration
 146 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
 147 [js2-mode]: https://github.com/mooz/js2-mode
 148 [node]: http://nodejs.org/download/
 149 [load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html