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

   1 # Context Coloring [![Build Status](https://travis-ci.org/jacksonrayhamilton/context-coloring.png?branch=master)](https://travis-ci.org/jacksonrayhamilton/context-coloring) [![Coverage Status](https://coveralls.io/repos/jacksonrayhamilton/context-coloring/badge.svg?branch=master)](https://coveralls.io/r/jacksonrayhamilton/context-coloring?branch=master)
   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 by scope.  Top-level scopes are one color, second-level scopes
   8 are another color, and so on.  Variables retain the color of the scope in which
   9 they are defined.  A variable defined in an outer scope referenced by an inner
  10 scope is colored the same as the outer scope.
  11
  12 By default, comments and strings are still highlighted syntactically.
  13
  14 ## Features
  15
  16 - Light and dark (customizable) color schemes.
  17 - JavaScript support:
  18   - Script, function and block scopes (and even `catch` block scopes).
  19   - Very fast for files under 1000 lines.
  20 - Emacs Lisp support:
  21   - `defun`, `lambda`, `let`, `let*`, `cond`, `condition-case`, quotes,
  22     backquotes (and splicing).
  23   - 25,000 lines per second!
  24
  25 ## Installation
  26
  27 Requires Emacs 24+.
  28
  29 JavaScript language support requires either [js2-mode][], or
  30 [Node.js 0.10+][node] and the [scopifier][] executable.
  31
  32 ### ELPA
  33
  34 - `M-x package-install RET context-coloring RET`
  35
  36 ### Git
  37
  38 - Clone this repository.
  39
  40 ```bash
  41 cd ~/.emacs.d/
  42 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  43 ```
  44
  45 - Byte-compile the package for improved speed.
  46
  47 ```bash
  48 cd context-coloring/
  49 make compile
  50 ```
  51
  52 - Add the following to your init file:
  53
  54 ```lisp
  55 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  56 (require 'context-coloring)
  57 ```
  58
  59 ### Dependencies (js-mode)
  60
  61 ```bash
  62 npm install -g scopifier
  63 ```
  64
  65 ## Usage
  66
  67 Add the following to your init file:
  68
  69 ```lisp
  70 ;; js-mode:
  71 (add-hook 'js-mode-hook 'context-coloring-mode)
  72
  73 ;; js2-mode:
  74 (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
  75 (add-hook 'js2-mode-hook 'context-coloring-mode)
  76
  77 ;; emacs-lisp-mode:
  78 (add-hook 'emacs-lisp-mode-hook 'context-coloring-mode)
  79 ```
  80
  81 ## Customizing
  82
  83 ### Options
  84
  85 - `context-coloring-syntactic-comments` (default: `t`): If non-nil, also color
  86   comments using `font-lock`.
  87 - `context-coloring-syntactic-strings` (default: `t`): If non-nil, also color
  88   strings using `font-lock`.
  89 - `context-coloring-default-delay` (default: `0.25`; supported modes: `js-mode`,
  90   `js3-mode`): Default (sometimes overridden) delay between a buffer update and
  91   colorization.
  92 - `context-coloring-js-block-scopes` (default: `nil`; supported modes:
  93   `js2-mode`): If non-nil, also color block scopes in the scope hierarchy in
  94   JavaScript.
  95
  96 ### Color Schemes
  97
  98 Color schemes for custom themes are automatically applied when those themes are
  99 active.  Built-in theme support is available for: `ample`, `anti-zenburn`,
 100 `grandshell`, `leuven`, `monokai`, `solarized`, `spacegray`, `tango` and
 101 `zenburn`.
 102
 103 You can define your own theme colors too:
 104
 105 ```lisp
 106 (context-coloring-define-theme
 107  'zenburn
 108  :colors '("#dcdccc"
 109            "#93e0e3"
 110            "#bfebbf"
 111            "#f0dfaf"
 112            "#dfaf8f"
 113            "#cc9393"
 114            "#dc8cc3"
 115            "#94bff3"
 116            "#9fc59f"
 117            "#d0bf8f"
 118            "#dca3a3"))
 119 ```
 120
 121 See `C-h f context-coloring-define-theme` for more info on theme parameters.
 122
 123 ## Extending
 124
 125 To add support for a new language, write a "scopifier" for it, and define a new
 126 coloring dispatch strategy with `context-coloring-define-dispatch`.  Then the
 127 plugin should handle the rest.  (See `C-h f context-coloring-define-dispatch`
 128 for more info on dispatch strategies.)
 129
 130 A "scopifier" is a CLI program that reads a buffer's contents from stdin and
 131 writes a JSON array of numbers to stdout.  Every three numbers in the array
 132 represent a range of color.  For instance, if I fed the following string of
 133 JavaScript code to a scopifier
 134
 135 ```js
 136 var a = function () {};
 137 ```
 138
 139 then the scopifier would produce the following array
 140
 141 ```js
 142 [1,24,0,9,23,1]
 143 ```
 144
 145 where, for every three numbers, the first number is a 1-indexed start [point][],
 146 the second number is an exclusive end point, and the third number is a scope
 147 level.  The result of applying level 0 coloring to the range &#91;1, 24) and
 148 then applying level 1 coloring to the range &#91;9, 23) would result in the
 149 following coloring:
 150
 151 <p align="center">
 152   <img alt="Screenshot of ranges &#91;1, 24) and &#91;9, 23)." src="scopifier.png" title="Screenshot">
 153 </p>
 154
 155 If there is an abstract syntax tree generator for your language, you can walk
 156 the syntax tree, find variables and scopes, and build their positions and levels
 157 into an array like the one above.
 158
 159 For example, a Ruby scopifier might be defined and implemented like this:
 160
 161 ```lisp
 162 (context-coloring-define-dispatch
 163  'ruby
 164  :modes '(ruby-mode)
 165  :executable "ruby"
 166  :command "/home/username/scopifier")
 167 ```
 168
 169 ```ruby
 170 #!/usr/bin/env ruby
 171 def scopifier(code)
 172     # Parse code.
 173     # Return an array.
 174 end
 175 print scopifier ARGF.read
 176 ```
 177
 178 When a `--version` argument is passed, a scopifier should print its version
 179 number and exit.  This allows context-coloring to determine if an update is
 180 required.
 181
 182 Alternatively, you could implement a "colorizer" in Emacs Lisp.  A colorizer
 183 also handles the job of calling `context-coloring-colorize-region` to apply
 184 colors to a buffer.  A colorizer may have better performance than a scopifier
 185 when parsing and coloring can be performed in the same pass.
 186
 187 [js2-mode]: https://github.com/mooz/js2-mode
 188 [node]: http://nodejs.org/download/
 189 [scopifier]: https://github.com/jacksonrayhamilton/scopifier
 190 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html