16 KiB
This project adds CoffeeScript support to vim. It covers syntax, indenting, compiling, and more.
Table of Contents
- Installation
- Coffee Commands
- Extras
- Configuration
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.
- 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-script
repo 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 using Vundle
- 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() Plugin '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
:PluginInstall
.
To update, open vim and run :PluginInstall!
(notice the bang!)
Install from a Zip File
-
Download the latest zip file from vim.org.
-
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.
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
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
The quickfix window
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.
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_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:
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
Quick syntax checking
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: Live Preview Compiling
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: Run CoffeeScript Snippets
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: Lint your CoffeeScript
CoffeeLint runs coffeelint (version 1.4.0 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
Literate CoffeeScript syntax and indent support is now built in! The Coffee
commands detect when they're running on a litcoffee file and pass the
--literate
flag to their respective tools.
Literate CoffeeScript syntax and indent support was written by @mintplant
(Michael Smith). A standalone repo
exists, but you'll
need to copy the ftplugin/litcoffee.vim
file or set up an autocmd to get the
Coffee
commands to be automatically loaded for litcoffee files.
CoffeeScript in HTML
CoffeeScript is highlighted and indented within
<script type="text/coffeescript">
</script>
blocks in html files.
CoffeeScript in Haml
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.
Custom Autocmds
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
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 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.
" 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:
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, 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
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:
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