Skip to content
Browse files

README.md, CONTRIBUTING.md, LICENSE

  • Loading branch information...
1 parent 15d4dae commit 0104c060a6d28d2886ba337bcad35134325fae23 @AndrewRadev committed Oct 30, 2012
Showing with 151 additions and 2 deletions.
  1. +29 −0 CONTRIBUTING.md
  2. +17 −0 LICENSE
  3. +105 −2 README.md
View
29 CONTRIBUTING.md
@@ -0,0 +1,29 @@
+# Contributing
+
+If you'd like to contribute to the project, you can use the usual github pull-request flow:
+
+1. Fork the project
+2. Make your change/addition, preferably in a separate branch.
+3. Test the new behaviour and make sure all existing tests pass (optional, see below for more information).
+4. Issue a pull request with a description of your feature/bugfix.
+
+## Testing
+
+This project uses [rspec](http://rspec.info/) and [vimrunner](https://github.com/AndrewRadev/vimrunner) to test its behaviour. Testing vimscript this way is still fairly experimental, but does a great job of catching regressions. Tests are written in the ruby programming language, so if you're familiar with it, you should (I hope) find the tests fairly understandable and easy to get into.
+
+If you're not familiar with ruby, please don't worry about it :). I'd definitely appreciate it if you could take a look at the tests and attempt to write something that describes your change. Even if you don't, Travis-bot should run the tests upon issuing a pull request, so we'll know right away if there's a regression. In that case, I'll work on the tests myself and see what I can do.
+
+To run the test suite, provided you have ruby installed, first you need bundler:
+
+```
+$ gem install bundler
+```
+
+If you already have the `bundle` command (check it out with `which bundle`), you don't need this step. Afterwards, it should be as simple as:
+
+```
+$ bundle install
+$ bundle exec rspec spec
+```
+
+Depending on what kind of Vim you have installed, this may spawn a GUI Vim instance, or even several. You can read up on [vimrunner's README](https://github.com/AndrewRadev/vimrunner/blob/master/README.md) to understand how that works.
View
17 LICENSE
@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
View
107 README.md
@@ -1,4 +1,4 @@
-*Note: lots more documentation soon to come*
+## Usage
This plugin provides two `<Plug>` mappings, `<Plug>WhitespasteBefore` and `<Plug>WhitespasteAfter` that are meant to be used as replacements to the `P` and `p` mappings respectively. To override the built-ins directly:
@@ -14,4 +14,107 @@ nmap <leader>P <Plug>WhitespasteBefore
nmap <leader>p <Plug>WhitespasteAfter
```
-These mappings differ from standard pasting by compressing all whitespace that results in a linewise paste to a single line and removing all whitespace at the top or bottom of the file. It 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 the "Extending" section (TODO) to find out how you can extend the plugin for a different language or change it to fit your own coding style.
+The plugin differs from standard pasting by compressing all whitespace that results in a linewise paste to a single line. It 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 to find out how you can extend the plugin for a different language or change it to fit your own coding style.
+
+## 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:
+
+``` vim
+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:
+
+``` vim
+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 more strict 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:
+
+``` vim
+ puts "one"
+ puts "two"
+ puts "three"
+```
+
+Now, we'd like to paste it into the following area:
+
+``` vim
+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:
+
+``` vim
+something {
+ puts "one"
+ puts "two"
+ puts "three"
+}
+```
+
+Then we could define a whitespaste definition like so:
+
+``` vim
+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
+
+``` vim
+{ '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 and vimscript.
+
+## Contributing
+
+Pull requests are welcome, but take a look at [CONTRIBUTING.md](https://github.com/AndrewRadev/whitespaste.vim/blob/master/CONTRIBUTING.md) first for some guidelines.

0 comments on commit 0104c06

Please sign in to comment.
Something went wrong with that request. Please try again.