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