Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

231 lines (188 sloc) 8.943 kB
*whitespaste.txt* Auto-adjust number of blank lines when pasting
==============================================================================
CONTENTS *whitespaste* *whitespaste-contents*
Installation...........................: |whitespaste-installation|
Usage..................................: |whitespaste-usage|
Settings...............................: |whitespaste-settings|
Internals..............................: |whitespaste-internals|
Issues.................................: |whitespaste-issues|
==============================================================================
INSTALLATION *whitespaste-installation*
There are several ways to install the plugin. The recommended one is by using
Tim Pope's pathogen (http://www.vim.org/scripts/script.php?script_id=2332). In
that case, you can clone the plugin's git repository like so:
>
git clone git://github.com/AndrewRadev/whitespaste.vim.git ~/.vim/bundle/whitespaste
<
If your vim configuration is under git version control, you could also set up
the repository as a submodule, which would allow you to update more easily.
The command is (provided you're in ~/.vim):
>
git submodule add git://github.com/AndrewRadev/whitespaste.vim.git bundle/whitespaste
<
Another way is to simply copy all the essential directories inside the ~/.vim
directory: plugin, autoload, doc.
==============================================================================
USAGE *whitespaste-usage*
This plugin remaps the standard |p| and |P| mappings to enhance their
functionality. When pasting, it compresses all blank lines that result from
the paste to a single one (or none, at the top and bottom of the file). That
way, even if you copy any leftover whitespace, it'll be neatly trimmed to just
one line. This takes effect only for linewise pasting, since it's not entirely
clear what the behaviour should be for characterwise and blockwise pasting.
If you don't want to clobber your default |p| and |P| mappings, you can make
whitespaste use different ones by setting two predefined variables:
>
let g:whitespaste_before_mapping = ',P'
let g:whitespaste_after_mapping = ',p'
<
If you need more fine-grained control, you can disable mappings altogether by
setting both of these variables to empty strings. You can then use the three
provided <Plug> mappings for your purposes. For example:
>
let g:whitespaste_before_mapping = ''
let g:whitespaste_after_mapping = ''
nmap ,P <Plug>WhitespasteBefore
nmap ,p <Plug>WhitespasteAfter
xmap ,P <Plug>WhitespasteVisual
xmap ,p <Plug>WhitespasteVisual
<
The plugin also takes care of special cases like pasting functions/methods,
if-clauses and so on. Currently, these special cases work only with ruby and
vimscript, but see below in |whitespaste-extending| to find out how you can
extend the plugin for a different language or change it to fit your own coding
style.
Whitespaste automatically integrates with the vim-pasta plugin
(https://github.com/sickill/vim-pasta). If you want to disable this, you can
do it like so:
>
let g:whitespaste_pasta_enabled = 0
<
==============================================================================
EXTENDING *whitespaste-extending*
The global variable |g:whitespaste_linewise_definitions| controls the
behaviour of the plugin. It's a hash with two keys: "top" and "bottom". Each
of these keys points to a list of definitions that are attempted to decide how
much space to leave at the top of the pasted text and at the bottom,
respectively. This looks a bit like this:
>
let g:whitespaste_linewise_definitions = {
\ 'top': [
\ { ... }, { ... }
\ ],
\ 'bottom': [
\ { ... }, { ... }
\ ]
\ }
<
Each of the definitions in the list is a dictionary that can hold several
different keys.
- target_line: If this key is set, the definition matches only for a specific
line number of the area that the text is pasted in (the "target"). The
special value -1 denotes the last line + 1.
- target_text: A pattern to match the target line's contents with.
- pasted_line: Only matches when the first/last nonblank line of the
pasted text is positioned on this line.
- pasted_text: Only matches when the first/last nonblank line of the
pasted text matches this pattern.
- blank_lines: the exact amount of blank lines to set at the top or bottom
of the pasted text.
- compress_blank_lines: same as "blank_lines", except only enforced if the
current amount of blank lines is larger than the given number.
The "target_line" and "pasted_line" keys would probably not be very useful,
but they help in defining the edge case definitions:
>
let g:whitespaste_linewise_definitions = {
\ 'top': [
\ { 'target_line': 0, 'blank_lines': 0 },
\ ],
\ 'bottom': [
\ { 'target_line': -1, 'blank_lines': 0 },
\ ]
\ }
<
This set of definitions ensures that, when pasting at the top and bottom of
the buffer, whitespace is reduced to 0. Usually, though, you'll want to use
"target_text" and "pasted_text".
The definitions are attempted in order, which means that you should put
stricter definitions at the top and fallbacks at the bottom.
For an example, illustrating the "target" and "pasted" lines, let's assume
that we've yanked the following text:
>
puts "one"
puts "two"
puts "three"
<
Now, we'd like to paste it into the following area:
>
something {
}
<
Pasting the text on any line between the curly braces sets the target lines to
"something {" and "}" respectively -- the target lines are always the first
non-blank lines upwards and downwards of the pasted position. Similarly,
regardless of the whitespace we've pasted along with the given text, the
"pasted" lines' texts will be 'puts "one"' (for the top) and 'puts "three"'
(for the bottom). For this example, if we wanted the paste to always result in
this, regardless of leftover blank lines:
>
something {
puts "one"
puts "two"
puts "three"
}
<
Then we could define a whitespaste definition like so:
>
let g:whitespaste_linewise_definitions = {
\ 'top': [
\ { 'target_text': '{$', 'blank_lines': 0 }
\ ],
\ 'bottom': [
\ { 'target_text': '^}$', 'blank_lines': 0 }
\ ]
\ }
<
Note that, for a catchall definition, you could simply make a definition
without any conditions -- only with a "blank_lines" key or
"compress_blank_lines" key. Such a definition exists by default, and is set to
>
{ 'compress_blank_lines': 1 }
<
That way, no more than 1 blank line is allowed on any paste, as long as some
other definition doesn't override it earlier on.
To add definitions for only a specific filetype, assign the buffer-local
|b:whitespaste_linewise_definitions| variable instead. Buffer-local
definitions are assumed to be of higher priority, so be careful when putting
catchall definitions in there.
The default definitions can be seen in "plugin/whitespaste.vim". At this time,
the global definitions handle curly braces, as demonstrated in the above
example, remove whitespace at the top and bottom of the buffer, and compress
all other pasting operations to only one blank line. There are also specific
definitions for ruby, vimscript, and a few HTML-like filetypes.
==============================================================================
SETTINGS *whitespaste-settings*
*g:whitespaste_before_mapping*
*g:whitespaste_after_mapping*
>
let g:whitespaste_before_mapping = ',P'
let g:whitespaste_after_mapping = ',p'
<
Default values: P, p
These variables contain the mappings you need to enter to paste with
whitespaste. By default, they're "P" and "p" respectively, so they override
the built-in mappings. Set them to empty strings to avoid setting any mappings
by the plugin.
*g:whitespaste_pasta_enabled*
>
let g:whitespaste_pasta_enabled = 0
<
Default value:
g:whitespaste_pasta_enabled == 1
This variable lets you disable the built-in vim-pasta integration if you want
to, for whatever reason.
==============================================================================
ISSUES *whitespaste-issues*
Any issues and suggestions are very welcome on the github bugtracker:
https://github.com/AndrewRadev/whitespaste.vim/issues
vim:tw=78:sw=4:ft=help:norl:
Jump to Line
Something went wrong with that request. Please try again.