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, and a few cute
   7 commands.
   8
   9 ![Screenshot](http://img.skitch.com/20100307-qmcr7kij6fx7qmsx6w12dgfs2x.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 `coffee-mode` will be enabled automatically for any files ending in
  24 ".coffee" or named "Cakefile".
  25
  26 ## Indentation
  27
  28 ### Configuring
  29
  30 Lines are indented according to the `tab-width` variable. If you're
  31 like me, you probably have this set in your Emacs config globally:
  32
  33     (setq-default tab-width 4)
  34
  35 Well, idiomatic CoffeeScript uses two spaces. We can set our
  36 `tab-width` to two for `coffee-mode` using the `coffee-mode-hook`:
  37
  38     (defun coffee-custom ()
  39       "coffee-mode-hook"
  40      (set (make-local-variable 'tab-width) 2))
  41
  42     (add-hook coffee-mode-hook
  43       '(lambda() (coffee-custom)))
  44
  45 Another example of this hook is given further down.
  46
  47 ### TAB Theory
  48
  49 When you press `TAB`, indent the line unless doing so would make the
  50 current line more than two indentation levels deepers than the
  51 previous line. If that's the case, remove all indentation.
  52
  53 Consider this code, with point at the position indicated by the
  54 caret:
  55
  56     line1()
  57       line2()
  58       line3()
  59          ^
  60
  61 Pressing `TAB` will produce the following code:
  62
  63     line1()
  64       line2()
  65         line3()
  66            ^
  67
  68 Pressing `TAB` again will produce this code:
  69
  70     line1()
  71       line2()
  72     line3()
  73        ^
  74
  75 And so on. I think this is a pretty good way of getting decent
  76 indentation with a whitespace-sensitive
  77
  78 ### Newline and Indent
  79
  80 As for indentation after newlines, given this code and cursor
  81 position:
  82
  83     line1()
  84       line2()
  85       line3()
  86             ^
  87
  88 Pressing `RET` would insert a newline and place our cursor at the
  89 following position:
  90
  91     line1()
  92       line2()
  93       line3()
  94
  95       ^
  96
  97 In other words, the level of indentation is maintained. This
  98 applies to comments as well. Combined with the `TAB` you should be
  99 able to get things where you want them pretty easily.
 100
 101 ### Indenters
 102
 103 `class`, `for`, `if`, and possibly other keywords cause the next line
 104 to be indented automatically, however.
 105
 106 For example, given this code and cursor position::
 107
 108     class Animal
 109                 ^
 110
 111 Pressing enter would produce the following:
 112
 113     class Animal
 114
 115       ^
 116
 117 That is, indented a column deeper.
 118
 119 This also applies to lines ending in `->`, `=>`, `{`, `[`, and
 120 possibly more characters.
 121
 122 So this code and cursor position:
 123
 124     $('#demo').click ->
 125                        ^
 126
 127 On enter would produce this:
 128
 129     $('#demo').click ->
 130
 131       ^
 132
 133 Pretty slick.
 134
 135 ## Commands
 136
 137 ### coffee-compile-buffer
 138
 139 Compiles the current buffer to JavaScript using the command specified
 140 by the `coffee-command` variable and opens the contents in a new
 141 buffer using your JavaScript mode of choice. The JavaScript mode is
 142 determined by the `coffee-js-mode` variable and defaults to `js2-mode`.
 143
 144 Bind it:
 145
 146     (define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer)
 147
 148 ### coffee-compiler-region
 149
 150 Compiles the selected region to JavaScript using the same
 151 configuration variables as `coffee-compile-buffer`.
 152
 153 Bind it:
 154
 155     (define-key coffee-mode-map [(meta R)] 'coffee-compile-region)
 156
 157 ### coffee-repl
 158
 159 Starts a repl in a new buffer using `coffee-command`.
 160
 161 ## Hooks
 162
 163 ### coffee-mode-hook
 164
 165 Naturally. Example:
 166
 167     (defun coffee-custom ()
 168       "coffee-mode-hook"
 169
 170       ;; CoffeeScript uses two spaces.
 171       (set (make-local-variable 'tab-width) 2)
 172
 173       ;; If you don't have js2-mode
 174       (setq coffee-js-mode 'javascript-mode)
 175
 176       ;; *Messages* spam
 177       (setq coffee-debug-mode t)
 178
 179       ;; Riding edge.
 180       (setq coffee-command "~/dev/coffee"))
 181
 182     (add-hook 'coffee-mode-hook '(lambda () (coffee-custom)))
 183
 184 ## Thanks
 185
 186 * <http://xahlee.org/emacs/elisp_syntax_coloring.html> for instructions.
 187 * Jason Blevins for the guidance his markdown-mode.el gave.
 188
 189 ## Bugs
 190
 191 It's tested on Aquamacs 1.9 (Emacs 22) for OS X Snow Leopard so it may
 192 not work on your environment. Please file a bug at
 193 <http://github.com/defunkt/coffee-mode/issues> and maybe we can fix
 194 the problem.
 195
 196 This is the author's first major mode. Any sort of style feedback is
 197 appreciated.
 198
 199 [cs]: http://jashkenas.github.com/coffee-script/