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) [![Coverage Status](https://coveralls.io/repos/jacksonrayhamilton/context-coloring/badge.svg)](https://coveralls.io/r/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-install RET context-coloring RET`
  47
  48 ### Git
  49
  50 - Clone this repository.
  51
  52 ```bash
  53 cd ~/.emacs.d/
  54 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  55 ```
  56
  57 - Byte-compile the package for improved speed.
  58
  59 ```bash
  60 cd context-coloring/
  61 make compile
  62 ```
  63
  64 - Add the following to your `~/.emacs` file:
  65
  66 ```lisp
  67 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  68 (require 'context-coloring)
  69 ```
  70
  71 ### scopifier (for non-js2-mode users)
  72
  73 ```bash
  74 npm install -g scopifier
  75 ```
  76
  77 ## Usage
  78
  79 Add the following to your `~/.emacs` file:
  80
  81 ```lisp
  82 ;; non-js2-mode users:
  83 (add-hook 'js-mode-hook 'context-coloring-mode)
  84
  85 ;; js2-mode users:
  86 (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
  87 (add-hook 'js2-mode-hook 'context-coloring-mode)
  88 ```
  89
  90 ## Customizing
  91
  92 ### Options
  93
  94 - `context-coloring-syntactic-comments` (default: `t`): If non-nil, also color
  95   comments using `font-lock`.
  96 - `context-coloring-syntactic-strings` (default: `t`): If non-nil, also color
  97   strings using `font-lock`.
  98 - `context-coloring-delay` (default: `0.25`; supported modes: `js-mode`,
  99   `js3-mode`): Delay between a buffer update and colorization.
 100 - `context-coloring-js-block-scopes` (default: `nil`; supported modes:
 101   `js2-mode`): If non-nil, also color block scopes in the scope hierarchy in
 102   JavaScript.
 103
 104 ### Color Schemes
 105
 106 Color schemes for custom themes are automatically applied when those themes are
 107 active. Built-in theme support is available for: `ample`, `anti-zenburn`,
 108 `grandshell`, `leuven`, `monokai`, `solarized`, `spacegray`, `tango` and
 109 `zenburn`.
 110
 111 You can define your own theme colors too:
 112
 113 ```lisp
 114 (context-coloring-define-theme
 115  'zenburn
 116  :colors '("#DCDCCC"
 117            "#93E0E3"
 118            "#BFEBBF"
 119            "#F0DFAF"
 120            "#DFAF8F"
 121            "#CC9393"
 122            "#DC8CC3"
 123            "#94BFF3"
 124            "#9FC59F"
 125            "#D0BF8F"
 126            "#DCA3A3"))
 127 ```
 128
 129 See `C-h f context-coloring-define-theme` for more info on theme parameters.
 130
 131 ## Extending
 132
 133 To add support for a new language, write a "scopifier" for it, and define a new
 134 coloring dispatch strategy with `context-coloring-define-dispatch`. Then the
 135 plugin should handle the rest. (See `C-h f context-coloring-define-dispatch` for
 136 more info on dispatch strategies.)
 137
 138 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
 139 writes a JSON array of numbers to stdout. Every three numbers in the array
 140 represent a range of color. For instance, if I fed the following string of
 141 JavaScript code to a scopifier:
 142
 143 ```js
 144 var a = function () {};
 145 ```
 146
 147 Then the scopifier would produce the following array:
 148
 149 ```js
 150 [1,24,0,9,23,1]
 151 ```
 152
 153 Where, for every three numbers, the first number is a 1-indexed start [point][],
 154 the second number is an exclusive end point, and the third number is a scope
 155 level. The result of applying level 0 coloring to the range &#91;1, 24) and then
 156 applying level 1 coloring to the range &#91;9, 23) would result in the following
 157 coloring:
 158
 159 <p align="center">
 160   <img alt="Screenshot of ranges &#91;1, 24) and &#91;9, 23)." src="scopifier.png" title="Screenshot">
 161 </p>
 162
 163 If there is an abstract syntax tree generator for your language, you can walk
 164 the syntax tree, find variables and scopes, and build their positions and levels
 165 into an array like the one above.
 166
 167 For example, a Ruby scopifier might be defined and implemented like this:
 168
 169 ```lisp
 170 (context-coloring-define-dispatch
 171  'ruby
 172  :modes '(ruby-mode)
 173  :executable "ruby"
 174  :command "/home/username/scopifier")
 175 ```
 176
 177 ```ruby
 178 #!/usr/bin/env ruby
 179 def scopifier(code)
 180     # Parse code.
 181     # Return an array.
 182 end
 183 print scopifier ARGF.read
 184 ```
 185
 186 When a `--version` argument is passed, a scopifier should print its version
 187 number and exit. This allows context-coloring to determine if an update is
 188 required.
 189
 190 [linter]: http://jshint.com/about/
 191 [flycheck]: http://www.flycheck.org/
 192 [js2-mode]: https://github.com/mooz/js2-mode
 193 [node]: http://nodejs.org/download/
 194 [scopifier]: https://github.com/jacksonrayhamilton/scopifier
 195 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html