#

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

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

1. Create the directory `~/.vim/bundle/`:

       mkdir ~/.vim/bundle

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

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

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