*vis.txt* The Visual Block Tool Mar 29, 2013 Author: Charles E. Campbell (remove NOSPAM from Campbell's email first) Copyright: (c) 2004-2013 by Charles E. Campbell *vis-copyright* The VIM LICENSE applies to vis.vim and vis.txt (see |copyright|) except use "vis" instead of "Vim" No warranty, express or implied. Use At-Your-Own-Risk. ============================================================================== 1. Contents *vis* *vis-contents* *vis.vim* 1. Contents......................: |vis-contents| 2. Visual Block Manual...........: |vis-manual| 3. Visual Block Search...........: |vis-srch| 4. Required......................: |vis-required| 5. Sorting Examples..............: |vis-sort| 6. History.......................: |vis-history| ============================================================================== 2. Visual Block Manual *visman* *vismanual* *vis-manual* *v_:B* Performs an arbitrary Ex command on a visual highlighted block. Mark visual block (CTRL-V) or visual character (v), press ':B ' and enter an Ex command [cmd]. ex. Use ctrl-v to visually mark the block then use :B cmd (will appear as :'<,'>B cmd ) ex. Use v to visually mark the block then use :B cmd (will appear as :'<,'>B cmd ) Command-line completion is supported for Ex commands. There must be a space before the '!' when invoking external shell commands, eg. ':B !sort'. Otherwise an error is reported. Doesn't work as one might expect with Vim's ve option. That's because ve=all ended up leaving unwanted blank columns, so the solution chosen was to have the vis function turn ve off temporarily. The script works by deleting the selected region into register "a. The register "a itself is first saved and later restored. The text is then put at the end-of-file, modified by the user command, and then deleted back into register "a. Any excess lines are removed, and the modified text is then put back into the text at its original location. Popular uses for this command include: > :B s/pattern/output/ :B left :B right < 1: apply a substitute command to just the selected visual block, 2: left justify the selected block, and 3: right justify the selected block, respectively. The concept for this plugin is originally Stefan Roemer's ; however, both the implementation and methods used internally have completely changed since Roemer's version. ============================================================================== 3. Visual Block Search *vis-search* *vis-srch* *vis-S* Visual block search provides two ways to get visual-selection based searches. Both these methods work well with :set hls and searching may be repeated with the n or N commands. Using // and ?? after a visual selection (the // is only available if you have g:vis_WantSlashSlash=1 in your <.vimrc> file): > ex. select region via V, v, or ctrl-v //pattern < You'll actually get a long leader string of commands to restrict searches to the requested visual block first. You may then enter the pattern afterwards. For example, using "v" to select this paragraph, you'll see something like: > /\%(\%(\%80l\%>12v\)\|\%(\%83l\%<53v\)\|\%(\%>80l\%<83l\)\)\& < You may enter whatever pattern you want after the \&, and the pattern search will be restricted to the requested region. The "S" command in visual mode: > ex. select region via V, v, or ctrl-v :S pattern < The ":S pattern" will appear as ":'<,'>S pattern". This command will move the cursor to the next instance of the pattern, restricted to the visually selected block. An "R" command was contemplated, but I currently see no way to get it to continue to search backwards with n and N commands. ============================================================================== 4. Required *vis-required* The latest (v20f or later) now requires vim 7.0 (or later), as it has been split into plugin/ and an autoload/ sections for on-demand loading. Starting with version 11, required . It uses the SaveWinPosn() and RestoreWinPosn() functions therein. You may get from http://www.drchip.org/astronaut/vim/index.html#CECUTIL ============================================================================== 5. Sorting Examples *vis-sort* Assume we start with the following three lines: > one two three four five six seven eight nine < Example 1: Use visual-block mode to select the center three words: ctrl-v select two/five/eight, then :'<,'>sort: > four five six one two three seven eight nine < Note that the visual-block is ignored, other than as a way to select the three lines. The resulting sorting is done on the three words "one/four/seven". (this example presumed that you're using vim 7.0; if you're using an earlier version vim, try :'<,\> !sort instead) Example 2: Using vis.vim's B command: Again, use visual-block mode to select the center three words: ctrl-v select two/five/eight, then :'<,'>B sort: > one eight three four five six seven two nine < This operation sorts the selected three words (two/five/eight), leaving all characters outside the visual block alone. (this example presumed that you're using vim 7.0; if you're using an earlier version vim, try :'<,\> !sort instead) Example 3: Using vissort.vim's Vissort() function Use visual block mode to select the center three words; ctrl-v select two/five/eight, then :'<,'>Vissort: > seven eight nine four five six one two three < This time, the entire lines are sorted, but the sorting is done based on the visual-block selected region (ie. two/five/eight). ============================================================================== 6. History *vis-history* {{{1 v20 : May 20, 2009 - cecutil bugfix May 19, 2010 - split into plugin/ and autoload/ for faster loading and on-demand loading. Mar 18, 2013 - (Gary Johnson) pointed out that changing cedit to caused problems with visincr; the cedit setting is now bypassed in vis, too. Mar 29, 2013 - Fixed a problem with vis#VisBlockCmd() where it missed substitutes due to a short last line. s:SaveUserSettings() now makes ve=all instead of ve= (see |'ve'|) v19 : Jan 06, 2006 - small modification included to allow AlignMaps maps to work (visual select, :B norm \somemap) - cecutil updated to use keepjumps Jan 24, 2006 - works around formatoption setting Jan 25, 2006 - uses SaveWinPosn(0) to avoid SWP stack use v18 : Jul 11, 2005 - vis.vim now works around a virtcol() behavior difference between ve=all vs ve=block v17 : Apr 25, 2005 - vis.vim now uses cecutil (SaveWinPosn, etc) so the tarball now includes a copy of cecutil.vim v16 : Feb 02, 2005 - fixed a bug with visual-block + S ; the first line was being omitted in the search Mar 01, 2005 - used instead of '' Apr 13, 2005 - :'<,'>S plus v had a bug with one or two line selections (tnx to Vigil for pointing this out) Apr 14, 2005 - set ignorecase caused visual-block searching to confuse visual modes "v" and "V" v15 : Feb 01, 2005 - includes some additions to the help v14 : Sep 28, 2004 - visual-block based searching now supported. One do this either with :'<,'>S pattern or with a / or ? Jan 31, 2005 - fixed help file v13 : Jul 16, 2004 - folding commands added to source - GetLatestVimScript hook added for automatic updating v12 : Jun 14, 2004 - bugfix (folding interfered) v11 : May 18, 2004 - Included calls to SaveWinPosn() and RestoreWinPosn() to prevent unwanted movement of the cursor and window. As a result, now requires (see |vis-required|). v10 : Feb 11, 2003 - bugfix (ignorecase option interfered with v) v9 : Sep 10, 2002 - bugfix (left Decho on, now commented out) v8 : Sep 09, 2002 - bugfix (first column problem) v7 : Sep 05, 2002 - bugfix (was forcing begcolG$\"ad - Fixed double-loading (was commented out for debugging purposes) v3 : Jun 20, 2002 - saves ve, unsets ve, restores ve v2 : June 19, 2002 - Charles Campbell's v? June 19, 2002 Complete rewrite - is now immune to the presence of tabs and is considerably faster. v1 Epoch - Stefan Roemer wrote the original . ============================================================================== Modelines: {{{1 vim:tw=78:ts=8:ft=help:fdm=marker