ultimate-vim/sources_non_forked/vim-coffee-script/Readme.md

This project adds CoffeeScript support to vim. It covers syntax, indenting, compiling, and more.

Table of Contents

• Installation
  • Requirements
  • Install using Pathogen
  • Install using Vundle
  • Install from a Zip File
• Coffee Commands
  • Compile to JavaScript
  • Compile CoffeeScript Snippets
  • Live Preview Compiling
  • Run CoffeeScript Snippets
  • Lint your CoffeeScript
• Extras
  • Literate CoffeeScript
  • CoffeeScript in HTML
  • CoffeeScript in Haml
• Configuration
  • Custom Autocmds
  • Configuration Variables
  • Configure Syntax Highlighting
  • 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 for more information.)

2. 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.

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/.

2. 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.

3. Open vim and run :PluginInstall.

To update, open vim and run :PluginInstall! (notice the bang!)

Install from a Zip File

1. Download the latest zip file from vim.org.

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.

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 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 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