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