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