This project adds CoffeeScript support to vim. It covers syntax, indenting, compiling, and more.
- Installation
- Coffee Commands
- Extras
- Configuration
- vim 7.4 or later
- coffee 1.2.0 or later
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.
- Install pathogen.vim into
~/.vim/autoload/(see pathogen's readme for more information.)
-
Enable pathogen in your vimrc. Here's a bare-minimum vimrc that enables all the features of
vim-coffee-script: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.
-
Create the directory
~/.vim/bundle/:mkdir ~/.vim/bundle -
Clone the
vim-coffee-scriptrepo into~/.vim/bundle/:git clone https://github.com/kchmck/vim-coffee-script.git ~/.vim/bundle/vim-coffee-script/
Updating takes two steps:
-
Change into
~/.vim/bundle/vim-coffee-script/:cd ~/.vim/bundle/vim-coffee-script -
Pull in the latest changes:
git pull
- Install Vundle into
~/.vim/bundle/.
-
Configure your vimrc for Vundle. Here's a bare-minimum vimrc that enables all the features of
vim-coffee-script: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.
-
Open vim and run
:BundleInstall.
To update, open vim and run :BundleInstall! (notice the bang!)
-
Download the latest zip file from vim.org.
-
Extract the archive into
~/.vim/:unzip -od ~/.vim/ ARCHIVE.zipThis should create the files
~/.vim/autoload/coffee.vim,~/.vim/compiler/coffee.vim, etc.
You can update the plugin using the same steps.
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 for a full reference of the command.
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):
:make --bare --output /some/dir
See the full table of options for a
list of all the options that coffee recognizes.
Configuration: coffee_compiler,
coffee_make_options
Compiler errors are added to the quickfix list by :make, but the quickfix
window isn't automatically shown. The :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.
To recompile a file when it's written, add a BufWritePost autocmd to your
vimrc:
autocmd BufWritePost *.coffee silent make!
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_options
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:
Calling it with a range, like in visual mode, compiles only the selected snippet of CoffeeScript:
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):
: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_compile_vert
If compiling a snippet results in a compiler error, CoffeeCompile adds that error to the quickfix list.
You can use this to quickly check the syntax of a snippet.
CoffeeWatch emulates using the Try CoffeeScript preview box on the CoffeeScript homepage.
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:
You can force recompilation by calling :CoffeeWatch.
To get synchronized scrolling of the source buffer and CoffeeWatch buffer, set
'scrollbind'
on each:
:setl scrollbind
Configuration: coffee_compiler,
coffee_watch_vert
CoffeeRun compiles the current file or selected snippet and runs the resulting JavaScript.
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_run_vert
CoffeeLint runs coffeelint (version 0.5.7 or later required) on the current file and adds any issues to the quickfix list.
:[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):
:CoffeeLint -f lint.json
It behaves very similar to :make, described above.
:CoffeeLint! | cwindow
Configuration: coffee_linter,
coffee_lint_options
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.
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 is highlighted and indented within
<script type="text/coffeescript">
</script>blocks in html files.
CoffeeScript is highlighted within the :coffeescript filter in haml files:
:coffeescript
console.log "hullo"At this time, coffee indenting doesn't work in these blocks.
You can define commands 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} argument.
You can match all commands with a * or only specific commands by separating
them with a comma: CoffeeCompile,CoffeeWatch.
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.
augroup CoffeeBufNew
autocmd User * set wrap
augroup ENDUsed By: CoffeeCompile, CoffeeWatch, CoffeeRun
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.
" Switch back to the source buffer after updating.
augroup CoffeeBufUpdate
autocmd User CoffeeCompile,CoffeeRun exec bufwinnr(b:coffee_src_buf) 'wincmd w'
augroup ENDFor example, to strip off the "Generated by" comment on the first line, put this in your vimrc:
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 ENDUsed By: CoffeeCompile, CoffeeWatch, CoffeeRun
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.
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, use
let coffee_indent_keep_current = 1
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
Path to the coffee executable used by the Coffee commands:
let coffee_compiler = '/usr/bin/coffee'
Default: 'coffee' (search $PATH for executable)
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.
Path to the cake executable:
let coffee_cake = '/opt/bin/cake'
Default: 'cake' (search $PATH for executable)
Options to pass to cake with :make:
let coffee_cake_options = 'build'
Default: '' (nothing)
Path to the coffeelint executable:
let coffee_linter = '/opt/bin/coffeelint'
Default: 'coffeelint' (search $PATH for executable)
Options to pass to coffeelint:
let coffee_lint_options = '-f lint.json'
Default: '' (nothing)
Open the CoffeeCompile buffer with a vertical split instead of a horizontal one:
let coffee_compile_vert = 1
Default: unlet coffee_compile_vert
Open the CoffeeWatch buffer with a vertical split instead of a horizontal one:
let coffee_watch_vert = 1
Default: unlet coffee_watch_vert
Open the CoffeeRun buffer with a vertical split instead of a horizontal one:
let coffee_run_vert = 1
Default: unlet coffee_run_vert
Add these lines to your vimrc to disable the relevant syntax group.
Trailing whitespace is highlighted as an error by default. This can be disabled with:
hi link coffeeSpaceError NONE
Trailing semicolons are considered an error (for help transitioning from JavaScript.) This can be disabled with:
hi link coffeeSemicolonError NONE
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
Changing these core settings can make vim more CoffeeScript friendly.
Folding by indentation works well for CoffeeScript functions and classes:
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
To get standard two-space indentation in CoffeeScript files, add this line to your vimrc:
autocmd BufNewFile,BufReadPost *.coffee setl shiftwidth=2 expandtab