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   - Very fast for files under 1000 lines.
  19   - Script, function and block scopes (and even `catch` block scopes).
  20 - Emacs Lisp support:
  21   - `defun`, `lambda`, `let`, `let*`, quotes, backticks, commas.
  22
  23 ## Installation
  24
  25 Requires Emacs 24+.
  26
  27 JavaScript language support requires either [js2-mode][], or
  28 [Node.js 0.10+][node] and the [scopifier][] executable.
  29
  30 ### ELPA
  31
  32 - `M-x package-install RET context-coloring RET`
  33
  34 ### Git
  35
  36 - Clone this repository.
  37
  38 ```bash
  39 cd ~/.emacs.d/
  40 git clone https://github.com/jacksonrayhamilton/context-coloring.git
  41 ```
  42
  43 - Byte-compile the package for improved speed.
  44
  45 ```bash
  46 cd context-coloring/
  47 make compile
  48 ```
  49
  50 - Add the following to your init file:
  51
  52 ```lisp
  53 (add-to-list 'load-path "~/.emacs.d/context-coloring")
  54 (require 'context-coloring)
  55 ```
  56
  57 ### Dependencies (js-mode)
  58
  59 ```bash
  60 npm install -g scopifier
  61 ```
  62
  63 ## Usage
  64
  65 Add the following to your init file:
  66
  67 ```lisp
  68 ;; js-mode:
  69 (add-hook 'js-mode-hook 'context-coloring-mode)
  70
  71 ;; js2-mode:
  72 (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
  73 (add-hook 'js2-mode-hook 'context-coloring-mode)
  74
  75 ;; emacs-lisp-mode:
  76 (add-hook 'emacs-lisp-mode-hook 'context-coloring-mode)
  77 ```
  78
  79 ## Customizing
  80
  81 ### Options
  82
  83 - `context-coloring-syntactic-comments` (default: `t`): If non-nil, also color
  84   comments using `font-lock`.
  85 - `context-coloring-syntactic-strings` (default: `t`): If non-nil, also color
  86   strings using `font-lock`.
  87 - `context-coloring-delay` (default: `0.25`; supported modes: `js-mode`,
  88   `js3-mode`, `emacs-lisp-mode`): Delay between a buffer update and
  89   colorization.
  90 - `context-coloring-js-block-scopes` (default: `nil`; supported modes:
  91   `js2-mode`): If non-nil, also color block scopes in the scope hierarchy in
  92   JavaScript.
  93
  94 ### Color Schemes
  95
  96 Color schemes for custom themes are automatically applied when those themes are
  97 active.  Built-in theme support is available for: `ample`, `anti-zenburn`,
  98 `grandshell`, `leuven`, `monokai`, `solarized`, `spacegray`, `tango` and
  99 `zenburn`.
 100
 101 You can define your own theme colors too:
 102
 103 ```lisp
 104 (context-coloring-define-theme
 105  'zenburn
 106  :colors '("#dcdccc"
 107            "#93e0e3"
 108            "#bfebbf"
 109            "#f0dfaf"
 110            "#dfaf8f"
 111            "#cc9393"
 112            "#dc8cc3"
 113            "#94bff3"
 114            "#9fc59f"
 115            "#d0bf8f"
 116            "#dca3a3"))
 117 ```
 118
 119 See `C-h f context-coloring-define-theme` for more info on theme parameters.
 120
 121 ## Extending
 122
 123 To add support for a new language, write a "scopifier" for it, and define a new
 124 coloring dispatch strategy with `context-coloring-define-dispatch`.  Then the
 125 plugin should handle the rest.  (See `C-h f context-coloring-define-dispatch`
 126 for more info on dispatch strategies.)
 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
 146 then applying level 1 coloring to the range &#91;9, 23) would result in the
 147 following 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.  This allows context-coloring to determine if an update is
 178 required.
 179
 180 Alternatively, you could implement a "colorizer" in Emacs Lisp.  A colorizer
 181 also handles the job of calling `context-coloring-colorize-region` to apply
 182 colors to a buffer.  A colorizer may have better performance than a scopifier
 183 when parsing and coloring can be performed in the same pass.
 184
 185 [js2-mode]: https://github.com/mooz/js2-mode
 186 [node]: http://nodejs.org/download/
 187 [scopifier]: https://github.com/jacksonrayhamilton/scopifier
 188 [point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html