This project adds [CoffeeScript] support to vim. It covers syntax, indenting, compiling, and more. ![Screenshot](http://i.imgur.com/j1BhpZQ.png) [CoffeeScript]: http://coffeescript.org/ ## Table of Contents - Installation - [Requirements](#requirements) - [Install using Pathogen](#install-using-pathogen) - [Install using Vundle](#install-using-vundle) - [Install from a Zip File](#install-from-a-zip-file) - Coffee Commands - [Compile to JavaScript](#compile-to-javascript) - [Compile CoffeeScript Snippets](#coffeecompile-compile-coffeescript-snippets) - [Live Preview Compiling](#coffeewatch-live-preview-compiling) - [Run CoffeeScript Snippets](#coffeerun-run-coffeescript-snippets) - [Lint your CoffeeScript](#coffeelint-lint-your-coffeescript) - Extras - [Literate CoffeeScript](#literate-coffeescript) - [CoffeeScript in HTML](#coffeescript-in-html) - [CoffeeScript in Haml](#coffeescript-in-haml) - Configuration - [Custom Autocmds](#custom-autocmds) - [Configuration Variables](#configuration-variables) - [Configure Syntax Highlighting](#configure-syntax-highlighting) - [Tune Vim for CoffeeScript](#tune-vim-for-coffeescript) ## Requirements - vim 7.4 or later - coffee 1.2.0 or later ## Install using Pathogen This project uses rolling releases based on git commits, so pathogen is a natural fit for it. If you're already using pathogen, you can skip to step 4. 1. Install [pathogen.vim] into `~/.vim/autoload/` (see [pathogen's readme][install-pathogen] for more information.) [pathogen.vim]: http://www.vim.org/scripts/script.php?script_id=2332 [install-pathogen]: https://github.com/tpope/vim-pathogen#installation 2. Enable pathogen in your vimrc. Here's a bare-minimum vimrc that enables all the features of `vim-coffee-script`: ```vim call pathogen#infect() syntax enable filetype plugin indent on ``` If you already have a vimrc built up, just make sure it contains these calls, in this order. 3. Create the directory `~/.vim/bundle/`: mkdir ~/.vim/bundle 4. Clone the `vim-coffee-script` repo into `~/.vim/bundle/`: git clone https://github.com/kchmck/vim-coffee-script.git ~/.vim/bundle/vim-coffee-script/ Updating takes two steps: 1. Change into `~/.vim/bundle/vim-coffee-script/`: cd ~/.vim/bundle/vim-coffee-script 2. Pull in the latest changes: git pull ## Install using Vundle 1. [Install Vundle] into `~/.vim/bundle/`. [Install Vundle]: https://github.com/gmarik/vundle#quick-start 2. Configure your vimrc for Vundle. Here's a bare-minimum vimrc that enables all the features of `vim-coffee-script`: ```vim set nocompatible filetype off set rtp+=~/.vim/bundle/vundle/ call vundle#rc() Bundle 'kchmck/vim-coffee-script' syntax enable filetype plugin indent on ``` If you're adding Vundle to a built-up vimrc, just make sure all these calls are in there and that they occur in this order. 3. Open vim and run `:BundleInstall`. To update, open vim and run `:BundleInstall!` (notice the bang!) ## Install from a Zip File 1. Download the latest zip file from [vim.org][zip]. 2. Extract the archive into `~/.vim/`: unzip -od ~/.vim/ ARCHIVE.zip This should create the files `~/.vim/autoload/coffee.vim`, `~/.vim/compiler/coffee.vim`, etc. You can update the plugin using the same steps. [zip]: http://www.vim.org/scripts/script.php?script_id=3590 ## Compile to JavaScript A `coffee` wrapper for use with `:make` is enabled automatically for coffee files if no other compiler is loaded. To enable it manually, run :compiler coffee The `:make` command is then configured to use the `coffee` compiler and recognize its errors. I've included a quick reference here but be sure to check out [`:help :make`][make] for a full reference of the command. ![make](http://i.imgur.com/scUXmxR.png) ![make Result](http://i.imgur.com/eGIjEdn.png) [make]: http://vimdoc.sourceforge.net/htmldoc/quickfix.html#:make_makeprg Consider the full signature of a `:make` call as :[silent] make[!] [COFFEE-OPTIONS]... By default `:make` shows all compiler output and jumps to the first line reported as an error. Compiler output can be hidden with a leading `:silent`: :silent make Line-jumping can be turned off by adding a bang: :make! `COFFEE-OPTIONS` given to `:make` are passed along to `coffee` (see also [`coffee_make_options`](#coffee_make_options)): :make --bare --output /some/dir See the [full table of options](http://coffeescript.org/#usage) for a list of all the options that `coffee` recognizes. *Configuration*: [`coffee_compiler`](#coffee_compiler), [`coffee_make_options`](#coffee_make_options) #### The quickfix window Compiler errors are added to the [quickfix] list by `:make`, but the quickfix window isn't automatically shown. The [`:cwindow`][cwindow] command will pop up the quickfix window if there are any errors: :make :cwindow This is usually the desired behavior, so you may want to add an autocmd to your vimrc to do this automatically: autocmd QuickFixCmdPost * nested cwindow | redraw! The `redraw!` command is needed to fix a redrawing quirk in terminal vim, but can removed for gVim. [quickfix]: http://vimdoc.sourceforge.net/htmldoc/quickfix.html#quickfix [cwindow]: http://vimdoc.sourceforge.net/htmldoc/quickfix.html#:cwindow #### Recompile on write To recompile a file when it's written, add a `BufWritePost` autocmd to your vimrc: autocmd BufWritePost *.coffee silent make! #### Cake and Cakefiles A `cake` compiler is also available with the call :compiler cake You can then use `:make` as above to run your Cakefile and capture any `coffee` errors: :silent make build It runs within the current directory, so make sure you're in the directory of your Cakefile before calling it. *Configuration*: [`coffee_cake`](#coffee_cake), [`coffee_cake_options`](#coffee_cake_options) ## CoffeeCompile: Compile CoffeeScript Snippets CoffeeCompile shows how the current file or a snippet of CoffeeScript is compiled to JavaScript. :[RANGE] CoffeeCompile [vert[ical]] [WINDOW-SIZE] Calling `:CoffeeCompile` without a range compiles the whole file: ![CoffeeCompile](http://i.imgur.com/0zFG0l0.png) ![CoffeeCompile Result](http://i.imgur.com/bpiAxaa.png) Calling it with a range, like in visual mode, compiles only the selected snippet of CoffeeScript: ![CoffeeCompile Snippet](http://i.imgur.com/x3OT3Ay.png) ![Compiled Snippet](http://i.imgur.com/J02j4T8.png) Each file gets its own CoffeeCompile buffer, and the same buffer is used for all future calls of `:CoffeeCompile` on that file. It can be quickly closed by hitting `q` in normal mode. Using `vert` opens the CoffeeCompile buffer vertically instead of horizontally (see also [`coffee_compile_vert`](#coffee_compile_vert)): :CoffeeCompile vert By default the CoffeeCompile buffer splits the source buffer in half, but this can be overridden by passing in a `WINDOW-SIZE`: :CoffeeCompile 4 *Configuration*: [`coffee_compiler`](#coffee_compiler`), [`coffee_compile_vert`](#coffee_compile_vert) #### Quick syntax checking If compiling a snippet results in a compiler error, CoffeeCompile adds that error to the [quickfix] list. [quickfix]: http://vimdoc.sourceforge.net/htmldoc/quickfix.html#quickfix ![Syntax Checking](http://i.imgur.com/RC8accF.png) ![Syntax Checking Result](http://i.imgur.com/gi1ON75.png) You can use this to quickly check the syntax of a snippet. ## CoffeeWatch: Live Preview Compiling CoffeeWatch emulates using the Try CoffeeScript preview box on the [CoffeeScript homepage][CoffeeScript]. ![CoffeeWatch](http://i.imgur.com/TRHdIMG.png) ![CoffeeWatch Result](http://i.imgur.com/rJbOeeS.png) CoffeeWatch takes the same options as CoffeeCompile: :CoffeeWatch [vert[ical]] [WINDOW-SIZE] After a source buffer is watched, leaving insert mode or saving the file fires off a recompile of the CoffeeScript: ![Insert Mode](http://i.imgur.com/SBVcf4k.png) ![Recompile](http://i.imgur.com/pbPMog7.png) You can force recompilation by calling `:CoffeeWatch`. To get synchronized scrolling of the source buffer and CoffeeWatch buffer, set [`'scrollbind'`](http://vimdoc.sourceforge.net/htmldoc/options.html#'scrollbind') on each: :setl scrollbind *Configuration*: [`coffee_compiler`](#coffee_compiler), [`coffee_watch_vert`](#coffee_watch_vert) ## CoffeeRun: Run CoffeeScript Snippets CoffeeRun compiles the current file or selected snippet and runs the resulting JavaScript. ![CoffeeRun](http://i.imgur.com/YSkHUuQ.png) ![CoffeeRun Output](http://i.imgur.com/wZQbggN.png) The command has two forms: :CoffeeRun [PROGRAM-OPTIONS]... This form applies when no `RANGE` is given or when the given range is `1,$` (first line to last line). It allows passing `PROGRAM-OPTIONS` to your compiled program. The filename is passed directly to `coffee` so you must save the file for your changes to take effect. :RANGE CoffeeRun [COFFEE-OPTIONS]... This form applies with all other ranges. It compiles and runs the lines within the given `RANGE` and any extra `COFFEE-OPTIONS` are passed to `coffee`. *Configuration*: [`coffee_compiler`](#coffee_compiler), [`coffee_run_vert`](#coffee_run_vert) ## CoffeeLint: Lint your CoffeeScript CoffeeLint runs [coffeelint](http://www.coffeelint.org/) (version 0.5.7 or later required) on the current file and adds any issues to the [quickfix] list. ![CoffeeLint](http://i.imgur.com/UN8Nr5N.png) ![CoffeeLint Result](http://i.imgur.com/9hSIj3W.png) :[RANGE] CoffeeLint[!] [COFFEELINT-OPTIONS]... [ | cwindow] If a `RANGE` is given, only those lines are piped to `coffeelint`. Options given in `COFFEELINT-OPTIONS` are passed to `coffeelint` (see also [`coffee_lint_options`](#coffee_lint_options)): :CoffeeLint -f lint.json It behaves very similar to `:make`, described [above](#compile-to-javascript). :CoffeeLint! | cwindow *Configuration*: [`coffee_linter`](#coffee_linter), [`coffee_lint_options`](#coffee_lint_options) ## Literate CoffeeScript Literate CoffeeScript syntax and indent support is provided by [vim-literate-coffeescript]. The `Coffee` commands detect when they're running on a litcoffee file and pass the `--literate` flag to their respective tools, but at this time the commands are not automatically loaded when a litcoffee file is opened. [vim-literate-coffeescript]: https://github.com/mintplant/vim-literate-coffeescript To load them, run runtime ftplugin/coffee.vim while inside a litcoffee buffer. To do this automatically, add autocmd FileType litcoffee runtime ftplugin/coffee.vim to your vimrc. ## CoffeeScript in HTML CoffeeScript is highlighted and indented within ```html ``` blocks in html files. ## CoffeeScript in Haml CoffeeScript is highlighted within the `:coffeescript` filter in haml files: ```haml :coffeescript console.log "hullo" ``` At this time, coffee indenting doesn't work in these blocks. ## Custom Autocmds You can [define commands][autocmd-explain] to be ran automatically on these custom events. In all cases, the name of the command running the event (`CoffeeCompile`, `CoffeeWatch`, or `CoffeeRun`) is matched by the [`{pat}`][autocmd] argument. You can match all commands with a `*` or only specific commands by separating them with a comma: `CoffeeCompile,CoffeeWatch`. [autocmd-explain]: http://vimdoc.sourceforge.net/htmldoc/usr_40.html#40.3 [autocmd]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#:autocmd #### CoffeeBufNew CoffeeBufNew is ran when a new scratch buffer is created. It's called from the new buffer, so it can be used to do additional set up. ```vim augroup CoffeeBufNew autocmd User * set wrap augroup END ``` *Used By*: CoffeeCompile, CoffeeWatch, CoffeeRun #### CoffeeBufUpdate CoffeeBufUpdate is ran when a scratch buffer is updated with output from `coffee`. It's called from the scratch buffer, so it can be used to alter the compiled output. ```vim " Switch back to the source buffer after updating. augroup CoffeeBufUpdate autocmd User CoffeeCompile,CoffeeRun exec bufwinnr(b:coffee_src_buf) 'wincmd w' augroup END ``` For example, to strip off the "Generated by" comment on the first line, put this in your vimrc: ```vim function! s:RemoveGeneratedBy() " If there was an error compiling, there's no comment to remove. if v:shell_error return endif " Save cursor position. let pos = getpos('.') " Remove first line. set modifiable 1 delete _ set nomodifiable " Restore cursor position. call setpos('.', pos) endfunction augroup CoffeeBufUpdate autocmd User CoffeeCompile,CoffeeWatch call s:RemoveGeneratedBy() augroup END ``` *Used By*: CoffeeCompile, CoffeeWatch, CoffeeRun ## Configuration Variables This is the full list of configuration variables available, with example settings and default values. Use these in your vimrc to control the default behavior. #### coffee\_indent\_keep\_current By default, the indent function matches the indent of the previous line if it doesn't find a reason to indent or outdent. To change this behavior so it instead keeps the [current indent of the cursor][98], use let coffee_indent_keep_current = 1 [98]: https://github.com/kchmck/vim-coffee-script/pull/98 *Default*: `unlet coffee_indent_keep_current` Note that if you change this after a coffee file has been loaded, you'll have to reload the indent script for the change to take effect: unlet b:did_indent | runtime indent/coffee.vim #### coffee\_compiler Path to the `coffee` executable used by the `Coffee` commands: let coffee_compiler = '/usr/bin/coffee' *Default*: `'coffee'` (search `$PATH` for executable) #### coffee\_make\_options Options to pass to `coffee` with `:make`: let coffee_make_options = '--bare' *Default*: `''` (nothing) Note that `coffee_make_options` is embedded into `'makeprg'`, so `:compiler coffee` must be ran after changing `coffee_make_options` for the changes to take effect. #### coffee\_cake Path to the `cake` executable: let coffee_cake = '/opt/bin/cake' *Default*: `'cake'` (search `$PATH` for executable) #### coffee\_cake\_options Options to pass to `cake` with `:make`: let coffee_cake_options = 'build' *Default*: `''` (nothing) #### coffee\_linter Path to the `coffeelint` executable: let coffee_linter = '/opt/bin/coffeelint' *Default*: `'coffeelint'` (search `$PATH` for executable) #### coffee\_lint\_options Options to pass to `coffeelint`: let coffee_lint_options = '-f lint.json' *Default*: `''` (nothing) #### coffee\_compile\_vert Open the CoffeeCompile buffer with a vertical split instead of a horizontal one: let coffee_compile_vert = 1 *Default*: `unlet coffee_compile_vert` #### coffee\_watch\_vert Open the CoffeeWatch buffer with a vertical split instead of a horizontal one: let coffee_watch_vert = 1 *Default*: `unlet coffee_watch_vert` #### coffee\_run\_vert Open the CoffeeRun buffer with a vertical split instead of a horizontal one: let coffee_run_vert = 1 *Default*: `unlet coffee_run_vert` ## Configure Syntax Highlighting Add these lines to your vimrc to disable the relevant syntax group. #### Disable trailing whitespace error Trailing whitespace is highlighted as an error by default. This can be disabled with: hi link coffeeSpaceError NONE #### Disable trailing semicolon error Trailing semicolons are considered an error (for help transitioning from JavaScript.) This can be disabled with: hi link coffeeSemicolonError NONE #### Disable reserved words error Reserved words like `function` and `var` are highlighted as an error where they're not allowed in CoffeeScript. This can be disabled with: hi link coffeeReservedError NONE ## Tune Vim for CoffeeScript Changing these core settings can make vim more CoffeeScript friendly. #### Fold by indentation Folding by indentation works well for CoffeeScript functions and classes: ![Folding](http://i.imgur.com/gDgUBdO.png) To fold by indentation in CoffeeScript files, add this line to your vimrc: autocmd BufNewFile,BufReadPost *.coffee setl foldmethod=indent nofoldenable With this, folding is disabled by default but can be quickly toggled per-file by hitting `zi`. To enable folding by default, remove `nofoldenable`: autocmd BufNewFile,BufReadPost *.coffee setl foldmethod=indent #### Two-space indentation To get standard two-space indentation in CoffeeScript files, add this line to your vimrc: autocmd BufNewFile,BufReadPost *.coffee setl shiftwidth=2 expandtab