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 are declared.
  13
  14 Lexical scope information at-a-glance can assist a programmer in understanding
  15 the overall structure of a program. It can help to curb nasty bugs like name
  16 shadowing. A rainbow can indicate excessive complexity. State change within a
  17 closure is easily monitored.
  18
  19 By default, Context Coloring still highlights comments and strings
  20 syntactically. It is still easy to differentiate code from non-code, and strings
  21 cannot be confused for variables.
  22
  23 This coloring strategy is probably more useful than conventional syntax
  24 highlighting. Highlighting keywords can help one to detect spelling errors, but
  25 a [linter][] could also spot those errors, and if integrated with [flycheck][],
  26 an extra spot opens up in your editing 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 - Very fast for files under 1000 lines.
  36
  37 ## Usage
  38
  39 Requires Emacs 24+.
  40
  41 JavaScript language support requires either [js2-mode][] or
  42 [Node.js 0.10+][node], respectively.
  43
  44 - Clone this repository.
  45
  46 ```bash
  47 cd ~/.emacs.d/
  48 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  49 ```
  50
  51 - Byte-compile the package for improved speed.
  52
  53 ```bash
  54 cd context-coloring/
  55 make compile
  56 ```
  57
  58 - Add the following to your `~/.emacs` file:
  59
  60 ```lisp
  61 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  62 (require 'context-coloring)
  63 (add-hook 'js-mode-hook 'context-coloring-mode)
  64 ```
  65
  66 ## Customizing
  67
  68 You can adjust the colors to your liking using
  69 `context-coloring-set-colors`. The first argument is an alist of levels, and the
  70 optional second argument is the new total number of levels. This plugin does not
  71 figure out the total for you; you need to specify it if your number of colors is
  72 different from the default (`7`).
  73
  74 I like to take the colors from an existing theme and use those to create a
  75 rainbow that matches that theme. The end result is consistent, and usually looks
  76 as good as the theme does. Here's an example for `tango`:
  77
  78 ```lisp
  79 ;; ~/.emacs
  80 (load-theme 'tango)
  81 (require 'context-coloring)
  82 (defun jrh-context-coloring-tango ()
  83   (interactive)
  84   (context-coloring-set-colors
  85    '((comment . "#5f615c")
  86      (0       . "#2e3436") ; Globals.
  87      (1       . "#346604")
  88      (2       . "#204a87")
  89      (3       . "#5c3566")
  90      (4       . "#a40000")
  91      (5       . "#b35000")
  92      (6       . "#c4a000")
  93      (7       . "#8ae234") ; "You're screwed" colors.
  94      (8       . "#8cc4ff")
  95      (9       . "#ad7fa8")
  96      (10      . "#ef2929")
  97      (11      . "#fcaf3e")
  98      (12      . "#fce94f"))
  99    13))
 100 (jrh-context-coloring-tango)
 101 ```
 102
 103 ## Extending
 104
 105 To add support for a new language, write a "scopifier" for it, and add an entry
 106 to `context-coloring-dispatch-plist`. Then the plugin should handle the rest.
 107
 108 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
 109 writes a JSON array of numbers to stdout. Every three numbers in the array
 110 represent a range of color. For instance, if I fed the following string of
 111 JavaScript code to a scopifier,
 112
 113 ```js
 114 var a = function () {};
 115 ```
 116
 117 then the scopifier would produce the following array:
 118
 119 ```js
 120 [1,24,0,9,23,1]
 121 ```
 122
 123 Where, for every three numbers, the first number is a 1-indexed start [point][],
 124 the second number is an exclusive end point, and the third number is a scope
 125 level. The result of applying level 0 coloring to the range &#91;1, 24) and then
 126 applying level 1 coloring to the range &#91;9, 23) would result in the following
 127 coloring:
 128
 129 <p align="center">
 130   <img alt="Screenshot of ranges &#91;1, 24) and &#91;9, 23)." src="scopifier.png" title="Screenshot">
 131 </p>
 132
 133 If there is an abstract syntax tree generator for your language, you can walk
 134 the syntax tree, find variables and scopes, and build their positions and levels
 135 into an array like the one above.
 136
 137 [linter]: http://jshint.com/about/
 138 [flycheck]: http://www.flycheck.org/
 139 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
 140 [js2-mode]: https://github.com/mooz/js2-mode
 141 [node]: http://nodejs.org/download/
 142 [load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html