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