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 ## Installation
  38
  39 Requires Emacs 24+.
  40
  41 JavaScript language support requires either [js2-mode][], or
  42 [Node.js 0.10+][node] and the [scopifier][] executable.
  43
  44 ### ELPA
  45
  46 - `M-x package-refresh-contents RET`
  47 - `M-x package-install RET context-coloring RET`
  48
  49 ### Git
  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 ```
  71
  72 ### scopifier (for non-js2-mode users)
  73
  74 ```bash
  75 npm install -g scopifier
  76 ```
  77
  78 ## Usage
  79
  80 Add the following to your `~/.emacs` file:
  81
  82 ```lisp
  83 ;; non-js2-mode users:
  84 (add-hook 'js-mode-hook 'context-coloring-mode)
  85
  86 ;; js2-mode users:
  87 (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
  88 (add-hook 'js2-mode-hook 'context-coloring-mode)
  89 ```
  90
  91 ## Customizing
  92
  93 You can enable different color schemes via `context-coloring-load-theme`. (The
  94 screenshot above pairs the [zenburn][] color theme with the similarly-named
  95 context-coloring theme.)
  96
  97 Built-in available themes are: `leuven`, `monokai`, `solarized`, `tango` and
  98 `zenburn`. Contributions are welcome.
  99
 100 ```lisp
 101 (context-coloring-load-theme 'zenburn)
 102 ```
 103
 104 You can define your own themes, too:
 105
 106 ```lisp
 107 (context-coloring-define-theme
 108  'zenburn
 109  :colors '("#DCDCCC"
 110            "#93E0E3"
 111            "#BFEBBF"
 112            "#F0DFAF"
 113            "#DFAF8F"
 114            "#CC9393"
 115            "#DC8CC3"
 116            "#94BFF3"
 117            "#9FC59F"
 118            "#D0BF8F"
 119            "#DCA3A3"))
 120 ```
 121
 122 ## Extending
 123
 124 To add support for a new language, write a "scopifier" for it, and define a new
 125 coloring dispatch strategy with `context-coloring-define-dispatch`. Then the
 126 plugin should handle the rest.
 127
 128 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
 129 writes a JSON array of numbers to stdout. Every three numbers in the array
 130 represent a range of color. For instance, if I fed the following string of
 131 JavaScript code to a scopifier,
 132
 133 ```js
 134 var a = function () {};
 135 ```
 136
 137 then the scopifier would produce the following array:
 138
 139 ```js
 140 [1,24,0,9,23,1]
 141 ```
 142
 143 Where, for every three numbers, the first number is a 1-indexed start [point][],
 144 the second number is an exclusive end point, and the third number is a scope
 145 level. The result of applying level 0 coloring to the range &#91;1, 24) and then
 146 applying level 1 coloring to the range &#91;9, 23) would result in the following
 147 coloring:
 148
 149 <p align="center">
 150   <img alt="Screenshot of ranges &#91;1, 24) and &#91;9, 23)." src="scopifier.png" title="Screenshot">
 151 </p>
 152
 153 If there is an abstract syntax tree generator for your language, you can walk
 154 the syntax tree, find variables and scopes, and build their positions and levels
 155 into an array like the one above.
 156
 157 For example, a Ruby scopifier might be defined and implemented like this:
 158
 159 ```lisp
 160 (context-coloring-define-dispatch
 161  'ruby
 162  :modes '(ruby-mode)
 163  :executable "ruby"
 164  :command "/home/username/scopifier")
 165 ```
 166
 167 ```ruby
 168 #!/usr/bin/env ruby
 169 def scopifier(code)
 170     # Parse code.
 171     # Return an array.
 172 end
 173 print scopifier ARGF.read
 174 ```
 175
 176 When a `--version` argument is passed, a scopifier should print its version
 177 number and exit. For installable scopifiers, this allows context-coloring to
 178 check for updates as needed.
 179
 180 [linter]: http://jshint.com/about/
 181 [flycheck]: http://www.flycheck.org/
 182 [zenburn]: http://github.com/bbatsov/zenburn-emacs
 183 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
 184 [js2-mode]: https://github.com/mooz/js2-mode
 185 [node]: http://nodejs.org/download/
 186 [scopifier]: https://github.com/jacksonrayhamilton/scopifier
 187 [load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html