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