1 CoffeeScript Major Mode
2 =======================
4 An Emacs major mode for [CoffeeScript][cs], unfancy JavaScript.
6 Provides syntax highlighting, indentation support, imenu support,
7 a menu bar, and a few cute commands.
9 ![Screenshot](http://img.skitch.com/20100308-fcr622c95ibey4m474d5m1m1qt.png)
15 $ cd ~/.emacs.d/vendor
16 $ git clone git://github.com/defunkt/coffee-mode.git
20 (add-to-list 'load-path "~/.emacs.d/vendor/coffee-mode")
21 (require 'coffee-mode)
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:
26 (add-to-list 'auto-mode-alist '("\\.coffee$" . coffee-mode))
27 (add-to-list 'auto-mode-alist '("Cakefile" . coffee-mode))
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:
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
36 Then turn on whitespace-mode, or global-whitespace-mode.]
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
47 Consider this code, with point at the position indicated by the
55 Pressing `TAB` will produce the following code:
62 Pressing `TAB` again will produce this code:
69 And so on. I think this is a pretty good way of getting decent
70 indentation with a whitespace-sensitive language.
72 ### Newline and Indent
74 We all love hitting `RET` and having the next line indented
75 properly. Given this code and cursor position:
82 Pressing `RET` would insert a newline and place our cursor at the
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.
97 `class`, `for`, `if`, and possibly other keywords cause the next line
98 to be indented a level deeper automatically.
100 For example, given this code and cursor position::
105 Pressing enter would produce the following:
111 That is, indented a column deeper.
113 This also applies to lines ending in `->`, `=>`, `{`, `[`, and
114 possibly more characters.
116 So this code and cursor position:
121 On enter would produce this:
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.
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
141 If you have `easymenu` you can get to any of these commands from the
144 ![coffee-mode menu bar](http://img.skitch.com/20100308-tt5yn51h2jww2pmjqaawed6eq8.png)
146 ### coffee-compile-file
148 Compiles the current file as a JavaScript file. Doesn't open it or
149 anything special for you.
151 Operating on "basic.coffee" and running this command will save a
152 "basic.js" in the same directory. Subsequent runs will overwrite the
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`.
160 ### coffee-compile-buffer
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.
168 (define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer)
170 ### coffee-compile-region
172 Compiles the selected region to JavaScript using the same
173 configuration variables as `coffee-compile-buffer`.
177 (define-key coffee-mode-map [(meta R)] 'coffee-compile-region)
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:
184 (add-hook 'coffee-mode-hook '(lambda () (coffee-cos-mode t)))
188 Starts a repl in a new buffer using `coffee-command`.
196 (defun coffee-custom ()
199 ;; CoffeeScript uses two spaces.
200 (make-local-variable 'tab-width)
203 ;; If you don't want your compiled files to be wrapped
204 (setq coffee-args-compile '("-c" "--bare"))
207 (define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer)
210 (setq coffee-command "~/dev/coffee")
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)))
217 (add-hook 'coffee-mode-hook 'coffee-custom)
221 You can customize any of the following options using `M-x
222 customize-group` with "coffee" as the group.
224 You can also customize then with `coffee-mode-hook`, as demonstrated
229 The tab width to use when indenting.
235 The CoffeeScript command used for evaluating code. Must be in your
242 The command line arguments to pass to `coffee-command' to start a
247 ### coffee-args-compile
249 The command line arguments to pass to `coffee-command' when compiling a file.
253 ### coffee-compiled-buffer-name
255 The name of the scratch buffer used when compiling CoffeeScript.
257 Default: `"*coffee-compiled*"`
259 ### coffee-compile-jump-to-error
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
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
277 Prototype accessor assignments like `String::length: -> 10` don't look
280 Please file bugs at <http://github.com/defunkt/coffee-mode/issues>
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