42adced250
Update README.md |
||
---|---|---|
plugin | ||
samples | ||
.gitattributes | ||
.gitignore | ||
LICENSE | ||
README.md |
vim-autoformat
Format code with one button press.
This plugin makes use of external formatting programs to achieve the best results. Check the list of formatprograms below to see which languages are supported by default. You can easily customize these or add your own formatprogram. When no formatprogram exists (or no formatprogram is installed) for a certain filetype, vim-autoformat falls back by default to indenting, (using vim's auto indent functionality), retabbing and removing trailing whitespace.
How to install
This plugin is supported by Vim 7.4+.
It is required that your vim has builtin python support. You can check whether this is the case
by running vim --version
and check that +python
or +python3
is listed among features.
Vundle
Put this in your .vimrc
Plugin 'Chiel92/vim-autoformat'
Then restart vim and run :PluginInstall
.
To update the plugin to the latest version, you can run :PluginUpdate
.
Pathogen
Download the source and extract in your bundle directory. Updating has to be done manually, as far as I'm aware.
Other
It is highly recommended to use a plugin manager such as Vundle, since this makes it easy to update plugins or uninstall them. It also keeps your .vim directory clean. Still you can decide to download this repository as a zip file or whatever and extract it to your .vim folder.
How to use
First you should install an external program that can format code of the programming language you are using. This can either be one of the programs that are listed below as defaultprograms, or a custom program. For defaultprograms, vim-autoformat knows for which filetypes it can be used. For using a custom formatprogram, read the text below How can I change the behaviour of formatters, or add one myself? If the formatprogram you want to use is installed in one of the following ways, vim automatically detects it:
- It suffices to make the formatprogram globally available, which is the case if you install it via your package manager.
- Alternatively you can point vim-autoformat to folders containing formatters, by putting the absolute paths to these folders in
g:formatterpath
in your .vimrc, like:
let g:formatterpath = ['/some/path/to/a/folder', '/home/superman/formatters']
Remember that when no formatprograms exists for a certain filetype, vim-autoformat falls back by default to indenting, retabbing and removing trailing whitespace. This will fix at least the most basic things, according to vim's indentfile for that filetype.
When you have installed the formatter you need, you can format the entire buffer with the command :Autoformat
.
You can provide the command with a file type such as :Autoformat json
, otherwise the buffer's filetype will be used.
Some formatters allow you to format only a part of the file, for instance clang-format
and
autopep8
.
To use this, provide a range to the :Autoformat
command, for instance by visually selecting a
part of your file, and then executing :Autoformat
.
For convenience it is recommended that you assign a key for this, like so:
noremap <F3> :Autoformat<CR>
Or to have your code be formatted upon saving your file, you could use something like this:
au BufWrite * :Autoformat
To disable the fallback to vim's indent file, retabbing and removing trailing whitespace, set the following variables to 0.
let g:autoformat_autoindent = 0
let g:autoformat_retab = 0
let g:autoformat_remove_trailing_spaces = 0
To disable or re-enable these option for specific buffers, use the buffer local variants:
b:autoformat_autoindent
, b:autoformat_retab
and b:autoformat_remove_trailing_spaces
.
So to disable autoindent for filetypes that have incompetent indent files, use
autocmd FileType vim,tex let b:autoformat_autoindent=0
You can manually autoindent, retab or remove trailing whitespace with the following respective commands.
gg=G
:retab
:RemoveTrailingSpaces
For each filetype, vim-autoformat has a list of applicable formatters.
If you have multiple formatters installed that are supported for some filetype, vim-autoformat
tries all formatters in this list of applicable formatters, until one succeeds.
You can set this list manually in your vimrc (see section How can I change the behaviour of formatters, or add one myself?,
or change the formatter with the highest priority by the commands :NextFormatter
and :PreviousFormatter
.
To print the currently selected formatter use :CurrentFormatter
.
These latter commands are mostly useful for debugging purposes.
If you have a composite filetype with dots (like django.python
or php.wordpress
),
vim-autoformat first tries to detect and use formatters for the exact original filetype, and
then tries the same for all supertypes occurring from left to right in the original filetype
separated by dots (.
).
Default formatprograms
Here is a list of formatprograms that are supported by default, and thus will be detected and used by vim when they are installed properly.
-
clang-format
for C, C++, Objective-C (supports formatting ranges). Clang-format is a product of LLVM source builds. If youbrew install llvm
, clang-format can be found in /usr/local/Cellar/llvm/bin/. Vim-autoformat checks whether there exists a.clang-format
or a_clang-format
file up in the current directory's ancestry. Based on that it either uses that file or tries to match vim options as much as possible. Details: http://clang.llvm.org/docs/ClangFormat.html. -
astyle
for C#, C++, C and Java. Download it here: http://astyle.sourceforge.net/. Important: version2.0.5
or higher is required, since only those versions correctly support piping and are stable enough. -
autopep8
for Python (supports formatting ranges). It's probably in your distro's repository, so you can download it as a regular package. For Ubuntu typesudo apt-get install python-autopep8
in a terminal. Here is the link to the repository: https://github.com/hhatto/autopep8. And here the link to its page on the python website: http://pypi.python.org/pypi/autopep8/0.5.2. -
yapf
for Python (supports formatting ranges). It is readily available through PIP. Most users can install with the terminal commandsudo pip install yapf
orpip install --user yapf
. YAPF has one optional configuration variable to control the formatter style. For example:let g:formatter_yapf_style = 'pep8'
pep8
is the default value, or you can choose:google
,facebook
,chromium
.Here is the link to the repository: https://github.com/google/yapf
-
js-beautify
for Javascript and JSON. It can be installed by runningnpm install -g js-beautify
. Note thatnodejs
is needed for this to work. The python version version is also supported by default, which does not neednodejs
to run. Here is the link to the repository: https://github.com/einars/js-beautify. -
JSCS
for Javascript. http://jscs.info/ -
standard
for Javascript. It can be installed by runningnpm install -g standard
(nodejs
is required). No more configuration needed. More information about the style guide can be found here: http://standardjs.com/. -
xo
for Javascript. It can be installed by runningnpm install -g xo
(nodejs
is required). Here is the link to the repository: https://github.com/sindresorhus/xo. -
html-beautify
for HTML. It is shipped withjs-beautify
, which can be installed by runningnpm install -g js-beautify
. Note thatnodejs
is needed for this to work. Here is the link to the repository: https://github.com/einars/js-beautify. -
css-beautify
for CSS. It is shipped withjs-beautify
, which can be installed by runningnpm install -g js-beautify
. Note thatnodejs
is needed for this to work. Here is the link to the repository: https://github.com/einars/js-beautify. -
typescript-formatter
for Typescript.typescript-formatter
is a thin wrapper around the TypeScript compiler services. It can be installed by runningnpm install -g typescript-formatter
. Note thatnodejs
is needed for this to work. Here is the link to the repository: https://github.com/vvakame/typescript-formatter. -
sass-convert
for SCSS. It is shipped withsass
, a CSS preprocessor written in Ruby, which can be installed by runninggem install sass
. Here is the link to the SASS homepage: http://sass-lang.com/. -
tidy
for HTML, XHTML and XML. It's probably in your distro's repository, so you can download it as a regular package. For Ubuntu typesudo apt-get install tidy
in a terminal. -
rbeautify
for Ruby. It is shipped withruby-beautify
, which can be installed by runninggem install ruby-beautify
. Note that compatibleruby-beautify-0.94.0
or higher version. Here is the link to the repository: https://github.com/erniebrodeur/ruby-beautify. This beautifier developed and tested with ruby2.0+
, so you can have weird results with earlier ruby versions. -
rubocop
for Ruby. It can be installed by runninggem install rubocop
. Here is the link to the repository: https://github.com/bbatsov/rubocop -
gofmt
for Golang. The default golang formatting program is shipped with the golang distribution. Make suregofmt
is in your PATH (if golang is installed properly, it should be). Here is the link to the installation: https://golang.org/doc/install -
rustfmt
for Rust. It can be installed usingcargo
, the Rust package manager. Up-to-date installation instructions are on the project page: https://github.com/nrc/rustfmt/#installation. -
dartfmt
for Dart. Part of the Dart SDK (make sure it is on your PATH). See https://www.dartlang.org/tools/dartfmt/ for more info. -
perltidy
for Perl. It can be installed from CPANcpanm Perl::Tidy
. See https://metacpan.org/pod/Perl::Tidy and http://perltidy.sourceforge.net/ for more info. -
stylish-haskell
for Haskell It can be installed usingcabal
build tool. Installation instructions are available at https://github.com/jaspervdj/stylish-haskell#installation -
remark
for Markdown. A Javascript based markdown processor that can be installed withnpm install -g remark-cli
. More info is available at https://github.com/wooorm/remark. -
fprettify
for modern Fortran. Download from official repository. Install with./setup.py install
or./setup.py install --user
.
It doesn't work!
If you're struggling with getting a formatter to work, it may help to set vim-autoformat in verbose-mode. Vim-autoformat will then output errors on formatters that failed.
let g:autoformat_verbosemode=1
" OR:
let verbose=1
To read all messages in a vim session type :messages
. Since one cannot always easily copy
the contents of messages (e.g. for posting it in an issue), vim-autoformats command :PutMessages
may
help. It puts the messages in the current buffer, allowing you to do whatever you want.
How can I change the behaviour of formatters, or add one myself?
If you need a formatter that is not among the defaults, or if you are not satisfied with the default formatting behaviour that is provided by vim-autoformat, you can define it yourself. The formatprogram must read the unformatted code from the standard input, and write the formatted code to the standard output.
Basic definitions
The formatprograms that available for a certain <filetype>
are defined in g:formatters_<filetype>
.
This is a list containing string identifiers, which point to corresponding formatter definitions.
The formatter definitions themselves are defined in g:formatdef_<identifier>
as a string
expression.
Defining any of these variable manually in your .vimrc, will override the default value, if existing.
For example, a complete definition in your .vimrc for C# files could look like this:
let g:formatdef_my_custom_cs = '"astyle --mode=cs --style=ansi -pcHs4"'
let g:formatters_cs = ['my_custom_cs']
In this example, my_custom_cs
is the identifier for our formatter definition.
The first line defines how to call the external formatter, while the second line tells
vim-autoformat that this is the only formatter that we want to use for C# files.
Please note the double quotes in g:formatdef_my_custom_cs
.
This allows you to define the arguments dynamically:
let g:formatdef_my_custom_cs = '"--mode=cs --style=ansi -pcHs".&shiftwidth'
let g:formatters_cs = ['my_custom_cs']
Please notice that g:formatdef_my_custom_cs
contains an expression that can be evaluated, as required.
As you see, this allows us to dynamically define some parameters.
In this example, the indent width that astyle will use, depends on the buffer local value of &shiftwidth
, instead of being fixed at 4.
So if you're editing a csharp file and change the shiftwidth
(even at runtime), the g:formatdef_my_custom_cs
will change correspondingly.
For the default formatprogram definitions, the options expandtab
, shiftwidth
and textwidth
are taken into account whenever possible.
This means that the formatting style will match your current vim settings as much as possible.
You can have look look at the exact default definitions for more examples.
They are defined in vim-autoformat/plugin/defaults.vim
.
As a small side note, in the actual defaults the function shiftwidth()
is used instead of the
property. This is because it falls back to the value of tabstop
if shiftwidth
is 0.
If you have a composite filetype with dots (like django.python
or php.wordpress
),
vim-autoformat internally replaces the dots with underscores so you can specify formatters
through g:formatters_django_python
and so on.
To override these options for a local buffer, use the buffer local variants:
b:formatters_<filetype>
and b:formatdef_<identifier>
. This can be useful, for example, when
working with different projects with conflicting formatting rules, with each project having settings
in its own vimrc or exrc file:
let b:formatdef_custom_c='"astyle --mode=c --suffix=none --options=/home/user/special_project/astylerc"'
let b:formatters_c = ['custom_c']
Ranged definitions
If your format program supports formatting specific ranges, you can provide a format
definition which allows to make use of this.
The first and last line of the current range can be retrieved by the variables a:firstline
and
a:lastline
. They default to the first and last line of your file, if no range was explicitly
specified.
So, a ranged definition could look like this.
let g:formatdef_autopep8 = "'autopep8 - --range '.a:firstline.' '.a:lastline"
let g:formatters_python = ['autopep8']
This would allow the user to select a part of the file and execute :Autoformat
, which
would then only format the selected part.
Contributing
Pull requests are welcome. Any feedback is welcome. If you have any suggestions on this plugin or on this readme, if you have some nice default formatter definition that can be added to the defaults, or if you experience problems, please contact me by creating an issue in this repository.
Change log
January 2017
- Add
xo
formatter for JavaScript.
March 2016
- Don't use the option formatprg internally anymore, to always have the possible of using the default
gq
command. - Add more fallback options.
June 2015
- Backward incompatible patch!
- Multiple formatters per filetype are now supported.
- Configuration variable names changed.
- Using
gq
as alias for:Autoformat
is no longer supported. :Autoformat
now suppports ranges.- Composite filetypes are fully supported.
December 20 2013
html-beautify
is now the default for HTML since it seems to be better maintained, and seems to handle inline javascript neatly.- The
formatters/
folder is no longer supported anymore, because it is unnecessary. js-beautify
can no longer be installed as a bundle, since it only makes this plugin unnecessarily complex.
March 27 2013
- The default behaviour of gq is enabled again by removing the fallback on auto-indenting.
Instead, the fallback is only used when running the command
:Autoformat
. - For HTML,XML and XHTML, the option
textwidth
is taken into account when formatting. This extends the way the formatting style will match your current vim settings.
March 16 2013
The dynamic_indent_width
branch has been merged into the master branch.
- The options
expandtab
,shiftwidth
,tabstop
andsofttabstop
are not overwritten anymore. - This obsoletes
g:autoformat_no_default_shiftwidth
g:formatprg_args_expr_<filetype>
is introduced.
March 13 2013
- It is now possible to prevent vim-autoformat from overwriting your settings for
tabstop
,softtabstop
,shiftwidth
andexpandtab
in your .vimrc.
March 10 2013
- When no formatter is installed or defined, vim will now auto-indent the file instead. This uses the indentfile for that specific filetype.
March 9 2013
The custom_config
branch has been merged into the master branch.
- Customization of formatprograms can be done easily now, as explained in the readme.
- I set the default tabwidth to 4 for all formatprograms as well as for vim itself.
- The default parameters for astyle have been slightly modified: it will wrap spaces around operators.
- phpCB has been removed from the defaults, due to code-breaking behaviour.
- XHTML default definition added