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

   1 CoffeeScript Major Mode
   2 =======================
   3
   4 An Emacs major mode for [CoffeeScript][cs], unfancy JavaScript.
   5
   6 Provides syntax highlighting, indentation support, imenu support,
   7 a menu bar, and a few cute commands.
   8
   9 ![Screenshot](http://img.skitch.com/20100308-fcr622c95ibey4m474d5m1m1qt.png)
  10
  11 ## Installation
  12
  13 In your shell:
  14
  15     $ cd ~/.emacs.d/vendor
  16     $ git clone git://github.com/defunkt/coffee-mode.git
  17
  18 In your emacs config:
  19
  20     (add-to-list 'load-path "~/.emacs.d/vendor/coffee-mode")
  21     (require 'coffee-mode)
  22
  23 If `coffee-mode` is not enabled automatically for any files ending in
  24 ".coffee" or named "Cakefile", add this to your emacs config as well:
  25
  26     (add-to-list 'auto-mode-alist '("\\.coffee$" . coffee-mode))
  27     (add-to-list 'auto-mode-alist '("Cakefile" . coffee-mode))
  28
  29 [coffee-mode used to offer automatic deletion of trailing whitespace.
  30 This is now left to whitespace-mode. See its documentation for full
  31 details, but as a hint, configure:
  32
  33     (setq whitespace-action '(auto-cleanup)) ;; automatically clean up bad whitespace
  34     (setq whitespace-style '(trailing space-before-tab indentation empty space-after-tab)) ;; only show bad whitespace
  35
  36 Then turn on whitespace-mode, or global-whitespace-mode.]
  37
  38 ## Indentation
  39
  40 ### TAB Theory
  41
  42 It goes like this: when you press `TAB`, we indent the line unless
  43 doing so would make the current line more than two indentation levels
  44 deepers than the previous line. If that's the case, remove all
  45 indentation.
  46
  47 Consider this code, with point at the position indicated by the
  48 caret:
  49
  50     line1()
  51       line2()
  52       line3()
  53          ^
  54
  55 Pressing `TAB` will produce the following code:
  56
  57     line1()
  58       line2()
  59         line3()
  60            ^
  61
  62 Pressing `TAB` again will produce this code:
  63
  64     line1()
  65       line2()
  66     line3()
  67        ^
  68
  69 And so on. I think this is a pretty good way of getting decent
  70 indentation with a whitespace-sensitive language.
  71
  72 ### Newline and Indent
  73
  74 We all love hitting `RET` and having the next line indented
  75 properly. Given this code and cursor position:
  76
  77     line1()
  78       line2()
  79       line3()
  80             ^
  81
  82 Pressing `RET` would insert a newline and place our cursor at the
  83 following position:
  84
  85     line1()
  86       line2()
  87       line3()
  88
  89       ^
  90
  91 In other words, the level of indentation is maintained. This
  92 applies to comments as well. Combined with the `TAB` you should be
  93 able to get things where you want them pretty easily.
  94
  95 ### Indenters
  96
  97 `class`, `for`, `if`, and possibly other keywords cause the next line
  98 to be indented a level deeper automatically.
  99
 100 For example, given this code and cursor position::
 101
 102     class Animal
 103                 ^
 104
 105 Pressing enter would produce the following:
 106
 107     class Animal
 108
 109       ^
 110
 111 That is, indented a column deeper.
 112
 113 This also applies to lines ending in `->`, `=>`, `{`, `[`, and
 114 possibly more characters.
 115
 116 So this code and cursor position:
 117
 118     $('#demo').click ->
 119                        ^
 120
 121 On enter would produce this:
 122
 123     $('#demo').click ->
 124
 125       ^
 126
 127 Pretty slick.
 128
 129 ## imenu
 130
 131 If you're using imenu, `coffee-mode` should work just fine. This
 132 means users of [textmate.el][tm] will find that `⇧⌘T`
 133 (`textmate-go-to-symbol`) mostly works as expected.
 134
 135 If you're not using imenu check out [this page][im] or textmate.el for
 136 a really awesome way to jump quickly to a function's definition in a
 137 file.
 138
 139 ## Commands
 140
 141 If you have `easymenu` you can get to any of these commands from the
 142 menu bar:
 143
 144 ![coffee-mode menu bar](http://img.skitch.com/20100308-tt5yn51h2jww2pmjqaawed6eq8.png)
 145
 146 ### coffee-compile-file
 147
 148 Compiles the current file as a JavaScript file. Doesn't open it or
 149 anything special for you.
 150
 151 Operating on "basic.coffee" and running this command will save a
 152 "basic.js" in the same directory. Subsequent runs will overwrite the
 153 file.
 154
 155 If there are compilation errors and we the compiler have returned a
 156 line number to us for the first error, the point is moved to that
 157 line, so you can investigate.  If this annoys you, you can set
 158 `coffee-compile-jump-to-error` to `nil`.
 159
 160 ### coffee-compile-buffer
 161
 162 Compiles the current buffer to JavaScript using the command specified
 163 by the `coffee-command` variable and opens the contents in a new
 164 buffer using the mode configured for ".js" files.
 165
 166 Bind it:
 167
 168     (define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer)
 169
 170 ### coffee-compile-region
 171
 172 Compiles the selected region to JavaScript using the same
 173 configuration variables as `coffee-compile-buffer`.
 174
 175 Bind it:
 176
 177     (define-key coffee-mode-map [(meta R)] 'coffee-compile-region)
 178
 179 ### Compile-on-save
 180
 181 Hitting the key sequence `C-c C-o C-s` turns on (toggles) the
 182 compile-on-save minor mode in `coffee-mode`.  To enable it by default:
 183
 184     (add-hook 'coffee-mode-hook '(lambda () (coffee-cos-mode t)))
 185
 186 ### coffee-repl
 187
 188 Starts a repl in a new buffer using `coffee-command`.
 189
 190 ## Hooks
 191
 192 ### coffee-mode-hook
 193
 194 Naturally. Example:
 195
 196     (defun coffee-custom ()
 197       "coffee-mode-hook"
 198
 199       ;; CoffeeScript uses two spaces.
 200       (make-local-variable 'tab-width)
 201       (set 'tab-width 2)
 202
 203       ;; If you don't want your compiled files to be wrapped
 204       (setq coffee-args-compile '("-c" "--bare"))
 205
 206       ;; Emacs key binding
 207       (define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer)
 208
 209       ;; Riding edge.
 210       (setq coffee-command "~/dev/coffee")
 211
 212       ;; Compile '.coffee' files on every save
 213       (and (file-exists-p (buffer-file-name))
 214            (file-exists-p (coffee-compiled-file-name))
 215            (coffee-cos-mode t)))
 216
 217     (add-hook 'coffee-mode-hook 'coffee-custom)
 218
 219 ## Configuration
 220
 221 You can customize any of the following options using `M-x
 222 customize-group` with "coffee" as the group.
 223
 224 You can also customize then with `coffee-mode-hook`, as demonstrated
 225 above.
 226
 227 ### coffee-tab-width
 228
 229 The tab width to use when indenting.
 230
 231 Default: `tab-width`
 232
 233 ### coffee-command
 234
 235 The CoffeeScript command used for evaluating code. Must be in your
 236 path.
 237
 238 Default: `"coffee"`
 239
 240 ### coffee-args-repl
 241
 242 The command line arguments to pass to `coffee-command' to start a
 243 REPL.
 244
 245 Default: `'("-i")`
 246
 247 ### coffee-args-compile
 248
 249 The command line arguments to pass to `coffee-command' when compiling a file.
 250
 251 Default: `'("-c")`
 252
 253 ### coffee-compiled-buffer-name
 254
 255 The name of the scratch buffer used when compiling CoffeeScript.
 256
 257 Default: `"*coffee-compiled*"`
 258
 259 ### coffee-compile-jump-to-error
 260
 261 Whether to jump to the first error if compilation fails.  Please note
 262 that the coffee compiler doesn't always give a line number for the
 263 issue and in that case it is not possible to jump to the error, of
 264 course.
 265
 266 Default: `t`
 267
 268 ## Thanks
 269
 270 * Jeremy Ashkenas for CoffeeScript
 271 * <http://xahlee.org/emacs/elisp_syntax_coloring.html> for instructions.
 272 * Jason Blevins for the guidance his markdown-mode.el gave.
 273 * Steve Yegge for js2
 274
 275 ## Bugs
 276
 277 Prototype accessor assignments like `String::length: -> 10` don't look
 278 great.
 279
 280 Please file bugs at <http://github.com/defunkt/coffee-mode/issues>
 281
 282 [cs]: http://jashkenas.github.com/coffee-script/
 283 [tm]: http://github.com/defunkt/textmate.el
 284 [im]: http://chopmo.blogspot.com/2008/09/quickly-jumping-to-symbols.html