Join README file

	       __      _          __
	      / /___  (_)___     / /
	 __  / / __ \/ / __ \   / / 
	/ /_/ / /_/ / / / / /  /_/  
	\____/\____/_/_/ /_/  (_)  
	
        -Do better Join in vim

Join

(http://www.vim.org/scripts/script.php?script_id=4516)

Join provides more powerful line join features than the build-in :join.

Features

Except for all features provided by the build-in :join command, Join can:

• Join lines with separator (string)
• Join lines with or without trimming the leading/trailing whitespaces
• Join lines with negative count (backwards join)
• Join lines in reverse
• Join lines and keep joined lines (without removing joined lines)
• Join lines with any combinations of above options

Usage

If you are impatient, move your eyes down to the Examples and Screenshots section. :)

Join plugin defines only one command: :Join. If there is no other customer command (by other plugins maybe) starts with J, :J is also available for :Join.

The command format is:

:[range]Join[!] [separator] [count] [flags]

Short explanation: (detailed command description please check :h Join)

• all arguments are optional. If one argument was not given, the default value will be used:

    arg      | Default value
    ========================
    range    | current line 
    count    | 1            
    bang     | ""           
    separator| " "          
    flags    | ""           
    ------------------------
  

• all given arguments must be separated by space

• range follows Vim's range definition

• separator must be the 1st argument, and could be any string. It must be quoted by " or ', depends on if an escaped special character is required.

• the order of last two argument: count and flags are free. e.g :Join 5 rk and :Join rk 5, both are valid.

• count could be negative number. In this case Join will do backwards join.

• flags :

    r : (reverse) join lines in reverse
    k : (keep) don't remove joined line after join
  

• If you don't give [separator] and [flags] also give only positive [count], the :Join works as same as build-in :join

Examples & Screenshots

For detailed explainations, please check :h Join

Before	command & description	After
	:J ', ' 3 Join with: sep count
	:J '-' 3 r Join with: sep count reverse
	:J '-' 3 k Join with: sep count keep
	:J '-' 3 kr Join with: sep count keep reverse
	:J -3 Join with: negative count
	:J -3 r Join with: negative count reverse
	:J -3 kr Join with: negative count reverse keep
	:2,5J "'\"\t" k Join with: range special sep keep
	:2,5J "# " rk Join with: range sep keep reverse
	:5,7J 3 Join with: range count
	:5,7J -3 Join with: range negative count

vim: ft=markdown sw=2 ts=2 fdm=marker expandtab