*ShowTrailingWhitespace.txt* Detect unwanted whitespace at the end of lines. SHOW TRAILING WHITESPACE by Ingo Karkat *ShowTrailingWhitespace.vim* description |ShowTrailingWhitespace-description| usage |ShowTrailingWhitespace-usage| installation |ShowTrailingWhitespace-installation| configuration |ShowTrailingWhitespace-configuration| integration |ShowTrailingWhitespace-integration| limitations |ShowTrailingWhitespace-limitations| known problems |ShowTrailingWhitespace-known-problems| todo |ShowTrailingWhitespace-todo| history |ShowTrailingWhitespace-history| ============================================================================== DESCRIPTION *ShowTrailingWhitespace-description* This plugin highlights whitespace at the end of each line (except when typing at the end of a line). It uses the matchadd()-function, therefore doesn't interfere with syntax highlighting and leaves the |:match| command for other uses. Highlighting can be switched on/off globally and for individual buffers. The plugin comes with exceptions for certain filetypes, where certain lines can / must include trailing whitespace; additional patterns can be configured. RELATED WORKS * There are already a number of plugins for this purpose, most based on this VimTip: http://vim.wikia.com/wiki/Highlight_unwanted_spaces However, most of them use the older :match command and are not as flexible. - smartmatcheol.vim (vimscript #2635) highlights based on file extension or name. - trailing-whitespace (vimscript #3201) uses :match. - bad-whitespace (vimscript #3735) uses :match, allows on/off/toggling via commands. - Trailer Trash (vimscript #3938) uses :match. - DynamicSigns (vimscript #3965) can show whitespace errors (also mixed indent) in the sign column. Many plugins also come with a command to strip off the trailing whitespace; this plugin separates this into the companion |DeleteTrailingWhitespace.vim| plugin (vimscript #0000), which can even remove the trailing whitespace automatically on each write. To quickly locate the occurrences of trailing whitespace, you can use the companion |JumpToTrailingWhitespace.vim| plugin (vimscript #0000). ============================================================================== USAGE *ShowTrailingWhitespace-usage* By default, trailing whitespace is highlighted in all Vim buffers. Some users may want to selectively enable / disable this for certain filetypes, or files in a particular directory hierarchy, or toggle this on demand. Since it's difficult to accommodate all these demands with short and easy mappings and commands, this plugin does not define any of them, and leaves it to you to tailor the plugin to your needs. See |ShowTrailingWhitespace-configuration| below. ============================================================================== INSTALLATION *ShowTrailingWhitespace-installation* This script is packaged as a |vimball|. If you have the "gunzip" decompressor in your PATH, simply edit the *.vba.gz package in Vim; otherwise, decompress the archive first, e.g. using WinZip. Inside Vim, install by sourcing the vimball or via the |:UseVimball| command. > vim ShowTrailingWhitespace.vba.gz :so % To uninstall, use the |:RmVimball| command. DEPENDENCIES *ShowTrailingWhitespace-dependencies* - Requires Vim 7.1 with "matchadd()", or Vim 7.2 or higher. ============================================================================== CONFIGURATION *ShowTrailingWhitespace-configuration* For a permanent configuration, put the following commands into your |vimrc|: *ShowTrailingWhitespace-colors* To change the highlighting colors: > highlight ShowTrailingWhitespace Error ctermbg=Red guibg=Red < *g:ShowTrailingWhitespace* By default, highlighting is enabled for all buffers, and you can (selectively) disable it. To work from the opposite premise, launch Vim with highlighting disabled: > let g:ShowTrailingWhitespace = 0 < *g:ShowTrailingWhitespace_FilterFunc* In addition to toggling the highlighting on/off via |g:ShowTrailingWhitespace|, the decision can also be influenced by buffer settings or the environment. By default, buffers that are not persisted to disk (unless they are scratch buffers) or not modifiable (like user interface windows from various plugins) are skipped. You can disable this filtering: > let g:ShowTrailingWhitespace_FilterFunc = '' or install your own custom filter function instead: > let g:ShowTrailingWhitespace_FilterFunc = function('MyFunc') < *ShowTrailingWhitespace-commands* Highlighting can be enabled / disabled globally and for individual buffers. Analog to the |:set| and |:setlocal| commands, you can define the following commands: > command! -bar ShowTrailingWhitespaceOn call ShowTrailingWhitespace#Set(1,1) command! -bar ShowTrailingWhitespaceOff call ShowTrailingWhitespace#Set(0,1) command! -bar ShowTrailingWhitespaceBufferOn call ShowTrailingWhitespace#Set(1,0) command! -bar ShowTrailingWhitespaceBufferOff call ShowTrailingWhitespace#Set(0,0) To set the local highlighting back to its global value (like :set {option}< does), the following command can be defined: > command! -bar ShowTrailingWhitespaceBufferClear call ShowTrailingWhitespace#Reset() < *ShowTrailingWhitespace-mappings* You can also define a quick mapping to toggle the highlighting (here, locally; for global toggling use ShowTrailingWhitespace#Toggle(1): > nnoremap t$ :call ShowTrailingWhitespace#Toggle(0)echo (ShowTrailingWhitespace#IsSet() ? 'Show trailing whitespace' : 'Not showing trailing whitespace') < *ShowTrailingWhitespace-exceptions* For some filetypes, in certain places, trailing whitespace is part of the syntax or even mandatory. If you don't want to be bothered by these showing up as false positives, you can augment the regular expression so that these places do not match. The ShowTrailingWhitespace#SetLocalExtraPattern() function takes a regular expression that is prepended to the pattern for the trailing whitespace. For a certain filetype, this is best set in a file ftplugin/{filetype}_ShowTrailingWhitespace.vim ============================================================================== INTEGRATION *ShowTrailingWhitespace-integration* *ShowTrailingWhitespace-functions* The ShowTrailingWhitespace#IsSet() function can be used to query the on/off status for the current buffer, e.g. for use in the |statusline|. To obtain the pattern for matching trailing whitespace, including any |ShowTrailingWhitespace-exceptions|, you can use the function ShowTrailingWhitespace#Pattern(0). ============================================================================== LIMITATIONS *ShowTrailingWhitespace-limitations* KNOWN PROBLEMS *ShowTrailingWhitespace-known-problems* TODO *ShowTrailingWhitespace-todo* IDEAS *ShowTrailingWhitespace-ideas* ============================================================================== HISTORY *ShowTrailingWhitespace-history* 1.00 16-Mar-2012 First published version. 0.01 25-Feb-2012 Started development. ============================================================================== Copyright: (C) 2012 Ingo Karkat The VIM LICENSE applies to this script; see |copyright|. Maintainer: Ingo Karkat ============================================================================== vim:tw=78:ts=8:ft=help:norl: