Navigation Menu

Skip to content

Commit

Permalink
update syntastic to 5e275c4
Browse files Browse the repository at this point in the history
  • Loading branch information
@esamattis
esamattis committed Mar 18, 2014
1 parent efa65dd commit 7e9aaa0
Show file tree
Hide file tree
Showing 168 changed files with 5,216 additions and 2,887 deletions.
2 changes: 1 addition & 1 deletion bundle/syntastic/CONTRIBUTING.md
View file
Expand Up @@ -29,7 +29,7 @@ Following the coding conventions/styles used in the syntastic core:
* Use 4 space indents.
* Don't use abbreviated keywords - e.g. use `endfunction`, not `endfun` (there's always room for more fun!).
* Don't use `l:` prefixes for variables unless actually required (i.e. almost never).
* Code for maintainability. We would rather a function be a couple of lines longer and have (for example) some [explaining variables](http://www.refactoring.com/catalog/introduceExplainingVariable.html) to aid readability.
* Code for maintainability. We would rather a function be a couple of lines longer and have (for example) some [explaining variables](http://www.refactoring.com/catalog/extractVariable.html) to aid readability.

# Syntax checker style notes

Expand Down
245 changes: 161 additions & 84 deletions bundle/syntastic/README.markdown
View file
Expand Up @@ -17,31 +17,39 @@
\_____________________________________________/




Syntastic is a syntax checking plugin that runs files through external syntax
checkers and displays any resulting errors to the user. This can be done on
demand, or automatically as files are saved. If syntax errors are detected, the
user is notified and is happy because they didn't have to compile their code or
execute their script to find them.

At the time of this writing, syntax checking plugins exist for Ada,
AppleScript, AsciiDoc, Bourne shell, C, C++, C#, Chef, CoffeeScript, Coco,
Coq, CSS, Cucumber, CUDA, D, Dart, DocBook, Dust, Elixir, Erlang, eRuby,
Fortran, Gentoo metadata, Go, Haml, Haskell, Haxe, Handlebars, HSS, HTML,
Java, JavaScript, JSON, LESS, LISP, LLVM intermediate language, Lua, MATLAB,
NASM, Objective-C, Objective-C++, OCaml, Perl, Perl POD, PHP, Puppet, Python,
reStructuredText, Ruby, Rust, SASS/SCSS, Scala, Slim, Tcl, TeX, Twig,
TypeScript, Vala, Verilog, VHDL, xHtml, XML, XSLT, YAML, z80, Zope page
templates, zsh.

## Screenshot
- - -
1\. [Introduction](#introduction)
2\. [Installation](#installation)
3\. [FAQ](#faq)
4\. [Other resources](#otherresources)
- - -

<a name="introduction"></a>

## 1\. Introduction

Syntastic is a syntax checking plugin for Vim that runs files through external
syntax checkers and displays any resulting errors to the user. This can be done
on demand, or automatically as files are saved. If syntax errors are detected,
the user is notified and is happy because they didn't have to compile their
code or execute their script to find them.

At the time of this writing, syntax checking plugins exist for ActionScript,
Ada, AppleScript, AsciiDoc, ASM, BEMHTML, Bourne shell, C, C++, C#, Chef,
CoffeeScript, Coco, Coq, CSS, Cucumber, CUDA, D, Dart, DocBook, Dust, Elixir,
Erlang, eRuby, Fortran, Gentoo metadata, GLSL, Go, Haml, Haskell, Haxe,
Handlebars, HSS, HTML, Java, JavaScript, JSON, JSX, LESS, Lex, Limbo, LISP,
LLVM intermediate language, Lua, MATLAB, NASM, Objective-C, Objective-C++,
OCaml, Perl, Perl POD, PHP, gettext Portable Object, Puppet, Python, Racket,
reStructuredText, Ruby, Rust, SASS/SCSS, Scala, Slim, Tcl, TeX, Texinfo, Twig,
TypeScript, Vala, Verilog, VHDL, VimL, xHtml, XML, XSLT, YACC, YAML, z80, Zope
page templates, and zsh.

Below is a screenshot showing the methods that Syntastic uses to display syntax
errors. Note that, in practise, you will only have a subset of these methods
enabled.

![Screenshot 1](https://github.com/scrooloose/syntastic/raw/master/_assets/screenshot_1.png)
![Screenshot 1][0]

1. Errors are loaded into the location list for the corresponding window.
2. When the cursor is on a line containing an error, the error message is echoed in the command window.
Expand All @@ -50,126 +58,195 @@ enabled.
5. Hover the mouse over a line containing an error and the error message is displayed as a balloon.
6. (not shown) Highlighting errors with syntax highlighting. Erroneous parts of lines can be highlighted.

## Installation

Installing syntastic is easy but first you need to have the pathogen plugin installed. If you already
have pathogen working then skip Step 1 and go to Step 2.
<a name="installation"></a>

### Step 1: Install pathogen.vim
## 2\. Installation

First I'll show you how to install tpope's [pathogen.vim](https://github.com/tpope/vim-pathogen) so that
it's easy to install syntastic. Do this in your Terminal so that you get the pathogen.vim file
and the directories it needs:
Installing syntastic is easy but first you need to have the [pathogen][1]
plugin installed. If you already have [pathogen][1] working then skip
[Step 1](#step1) and go to [Step 2](#step2).

mkdir -p ~/.vim/autoload ~/.vim/bundle; \
curl -so ~/.vim/autoload/pathogen.vim \
https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim

Next you *need to add this* to your ~/.vimrc:
<a name="step1"></a>

execute pathogen#infect()
### 2.1\. Step 1: Install pathogen.vim

### Step 2: Install syntastic as a pathogen bundle
First I'll show you how to install Tim Pope's [pathogen][1] so that it's easy to
install syntastic. Do this in your terminal so that you get the `pathogen.vim`
file and the directories it needs:
```sh
mkdir -p ~/.vim/autoload ~/.vim/bundle; \
curl -so ~/.vim/autoload/pathogen.vim \
https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim
```
Next you *need* to add this to your `~/.vimrc`:
```vim
execute pathogen#infect()
```

You now have pathogen installed and can put syntastic into ~/.vim/bundle like this:

<a name="step2"></a>

cd ~/.vim/bundle
git clone https://github.com/scrooloose/syntastic.git
### 2.2\. Step 2: Install syntastic as a pathogen bundle

You now have pathogen installed and can put syntastic into `~/.vim/bundle` like
this:
```sh
cd ~/.vim/bundle
git clone https://github.com/scrooloose/syntastic.git
```
Quit vim and start it back up to reload it, then type:
```vim
:Helptags
```
If you get an error when you do this, then you probably didn't install
[pathogen][1] right. Go back to [Step 1](#step1) and make sure you did the following:

:Helptags

If you get an error when you do this, then you probably didn't install pathogen right. Go back to
step 1 and make sure you did the following:

1. Created both the ~/.vim/autoload and ~/.vim/bundle directories.
2. Added the "call pathogen#infect()" line to your ~/.vimrc file
3. Did the git clone of syntastic inside ~/.vim/bundle
1. Created both the `~/.vim/autoload` and `~/.vim/bundle` directories.
2. Added the `call pathogen#infect()` line to your `~/.vimrc` file
3. Did the `git clone` of syntastic inside `~/.vim/bundle`
4. Have permissions to access all of these directories.


## Google group
<a name="faq"></a>

To get information or make suggestions check out the [google group](https://groups.google.com/group/vim-syntastic).


## FAQ
## 3\. FAQ

__Q. I installed syntastic but it isn't reporting any errors...__

A. The most likely reason is that none of the syntax checkers that it requires is installed. For example: python requires either `flake8`, `pyflakes` or `pylint` to be installed and in `$PATH`. To see which executables are supported, just look in `syntax_checkers/<filetype>/*.vim`. Note that aliases do not work; the actual executable must be available in your `$PATH`. Symbolic links are okay. You can see syntastic's idea of available checkers by running `:SyntasticInfo`.

Another reason it could fail is that either the command line options or the error output for a syntax checker may have changed. In this case, make sure you have the latest version of the syntax checker installed. If it still fails then create an issue - or better yet, create a pull request.

__Q. Recently some of my syntax checker options have stopped working...__

A. The options are still there, they have just been renamed. Recently, almost all syntax checkers were refactored to use the new `syntastic#makeprg#build()` function. This made a lot of the old explicit options redundant - as they are now implied. The new implied options usually have slightly different names to the old options.

e.g. Previously there was `g:syntastic_phpcs_conf`, now you must use `g:syntastic_php_phpcs_args`. This completely overrides the arguments of the checker, including any defaults, so you may need to look up the default arguments of the checker and add these in.

See `:help syntastic-checker-options` for more information.
A. The most likely reason is that none of the syntax checkers that it requires
is installed. For example: by default, python requires either `flake8` or
`pylint` to be installed and in your `$PATH`. To see which executables are
supported, look at the [wiki][3]. Note that aliases do not work; the actual
executables must be available in your `$PATH`. Symbolic links are okay though.
You can see syntastic's idea of available checkers by running `:SyntasticInfo`.

Another reason it could fail is that either the command line options or the
error output for a syntax checker may have changed. In this case, make sure you
have the latest version of the syntax checker installed. If it still fails then
create an issue - or better yet, create a pull request.

__Q. The `perl` checker has stopped working...__

A. The `perl` checker runs `perl -c` against your file, which in turn
__executes__ any `BEGIN`, `UNITCHECK`, and `CHECK` blocks, and any `use`
statements in your file (cf. [perlrun][10]). This is probably fine if you
wrote the file yourself, but it's a security problem if you're checking third
party files. Since there is currently no way to disable this behaviour while
still producing useful results, the checker is now disabled by default. To
(re-)enable it, set `g:syntastic_enable_perl_checker` to 1 in your vimrc:
```vim
let g:syntastic_enable_perl_checker = 1
```

__Q. I run a checker and the location list is not updated...__

A. By default, the location list is changed only when you run the `:Errors` command, in order to minimise conflicts with other plugins. If you want the location list to always be updated when you run the checkers, add this line to your vimrc:
A. By default the location list is changed only when you run the `:Errors`
command, in order to minimise conflicts with other plugins. If you want the
location list to always be updated when you run the checkers, add this line to
your vimrc:
```vim
let g:syntastic_always_populate_loc_list=1
let g:syntastic_always_populate_loc_list = 1
```

__Q. How can I pass additional arguments to a checker?__

A. Almost all syntax checkers use the `syntastic#makeprg#build()` function. Those checkers that do can be configured using global variables. The general form of the global args variables are:
```vim
syntastic_<filetype>_<subchecker>_args
```
A. Almost all syntax checkers use the `makeprgBuild()` function. Those checkers
that do can be configured using global variables. The general form of the
global `args` variables is `syntastic_<filetype>_<checker>_args`.

So, If you wanted to pass "--my --args --here" to the ruby mri checker you would add this line to your vimrc:
So, If you wanted to pass "--my --args --here" to the ruby mri checker you
would add this line to your vimrc:
```vim
let g:syntastic_ruby_mri_args="--my --args --here"
let g:syntastic_ruby_mri_args = "--my --args --here"
```

See `:help syntastic-checker-options` for more information.

__Q. Syntastic supports several checkers for my filetype - how do I tell it which one(s) to use?__
__Q. Syntastic supports several checkers for my filetype - how do I tell it
which one(s) to use?__

A. Stick a line like this in your vimrc:
```vim
let g:syntastic_<filetype>_checkers=['<checker-name>']
let g:syntastic_<filetype>_checkers = ['<checker-name>']
```

To see the list of checkers for your filetype, look in `syntax_checkers/<filetype>/`.
To see the list of supported checkers for your filetype look at the
[wiki][3].

e.g. Python has the following checkers: `flake8`, `pyflakes`, `pylint` and a native `python` checker.
e.g. Python has the following checkers, among others: `flake8`, `pyflakes`,
`pylint` and a native `python` checker.

To tell syntastic to use `pylint`, you would use this setting:
```vim
let g:syntastic_python_checkers=['pylint']
let g:syntastic_python_checkers = ['pylint']
```

Some filetypes, like PHP, have style checkers as well as syntax checkers. These can be chained together like this:
Some filetypes, like PHP, have style checkers as well as syntax checkers. These
can be chained together like this:
```vim
let g:syntastic_php_checkers=['php', 'phpcs', 'phpmd']
let g:syntastic_php_checkers = ['php', 'phpcs', 'phpmd']
```

This is telling syntastic to run the `php` checker first, and if no errors are found, run `phpcs`, and then `phpmd`.
This is telling syntastic to run the `php` checker first, and if no errors are
found, run `phpcs`, and then `phpmd`.

__Q. How can I jump between the different errors without using the location list at the bottom of the window?__
__Q. How can I jump between the different errors without using the location
list at the bottom of the window?__

A. Vim provides several built in commands for this. See `:help :lnext` and `:help :lprev`.
A. Vim provides several built in commands for this. See `:help :lnext` and
`:help :lprev`.

If you use these commands a lot then you may want to add shortcut mappings to your vimrc, or install something like [unimpaired](https://github.com/tpope/vim-unimpaired), which provides such mappings (among other things).
If you use these commands a lot then you may want to add shortcut mappings to
your vimrc, or install something like [unimpaired][2], which provides such
mappings (among other things).

__Q. A syntax checker is giving me unwanted/strange style tips?__

A. Some filetypes (e.g. php) have style checkers as well as syntax checkers. You can usually configure the options that are passed to the style checkers, or just disable them. Take a look at the [wiki](https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers) to see what options are available.
A. Some filetypes (e.g. php) have style checkers as well as syntax
checkers. You can usually configure the options that are passed to the style
checkers, or just disable them. Take a look at the [wiki][3] to see what
options are available.

__Q. The error window is closed automatically when I :quit the current buffer but not when I :bdelete it?__
Alternatively, you can use `g:syntastic_quiet_messages` to filter out the
messages you don't want to see. e.g. To turn off all style messages:
```vim
let g:syntastic_quiet_messages = { "type": "style" }
```
See `:help syntastic_quiet_messages` for details.

__Q. The error window is closed automatically when I :quit the current buffer
but not when I :bdelete it?__

A. There is no safe way to handle that situation automatically, but you can work around it:
A. There is no safe way to handle that situation automatically, but you can
work around it:

```vim
nnoremap <silent> <C-d> :lclose<CR>:bdelete<CR>
cabbrev <silent> bd lclose\|bdelete
```


<a name="otherresources"></a>

## 4\. Other resources

The preferred place for posting suggestions, reporting bugs, and general
discussions related to syntastic is the [issue tracker at GitHub][4]. There
are also a [google group][5], and a [syntastic tag at StackOverflow][6].

Syntastic aims to provide a common interface to syntax checkers for as many
languages as possible. For particular languages, there are, of course, other
plugins that provide more functionality than syntastic. You might want to take
a look at [jedi-vim][7], [python-mode][8], or [YouCompleteMe][9].

[0]: https://github.com/scrooloose/syntastic/raw/master/_assets/screenshot_1.png
[1]: https://github.com/tpope/vim-pathogen
[2]: https://github.com/tpope/vim-unimpaired
[3]: https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers
[4]: https://github.com/scrooloose/syntastic/issues
[5]: https://groups.google.com/group/vim-syntastic
[6]: http://stackoverflow.com/questions/tagged/syntastic
[7]: https://github.com/davidhalter/jedi-vim
[8]: https://github.com/klen/python-mode
[9]: https://github.com/Valloric/YouCompleteMe
[10]: http://perldoc.perl.org/perlrun.html#*-c*

0 comments on commit 7e9aaa0

Please sign in to comment.