vis.txt The Visual Block Tool Sep 07, 2016
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2016 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.
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:
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
<roemer@informatik.tu-muenchen.de>; however, both the implementation
and methods used internally have completely changed since Roemer's
version.
g:vis_empty_character : this character should not appear in your
text. By default: users of euc-jp will get a 0x01, otherwise
it wil be a 0xff. Used to prevent an empty result in the
moving back the modified text operation, which otherwise results
in an unwanted extra blank space being inserted.
==============================================================================
3. Visual Block Search vis-search vis-srch vis-S
Visual block search provides two ways to search a visual-selection.
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):
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:
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:
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 <vis.vim> (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, <vis.vim> required <cecutil.vim>. It uses
the SaveWinPosn() and RestoreWinPosn() functions therein. You may get
<cecutil.vim> from
http://www.drchip.org/astronaut/vim/index.html#CECUTIL
==============================================================================
5. Sorting Examples vis-sort
Assume we start with the following three lines:
Example 1: Use visual-block mode to select the center three
words: ctrl-v select two/five/eight, then :'<,'>sort:
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:
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:
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
v22 : Dec 08, 2021 - while using mathify, I kept getting an unwanted
trailing space. I've tracked it down to Step#5
in vis#VisBlockCmd()'s exe 'keepj norm! 0'.vmode.'G$"ax'
For an unknown reason, that command sometimes, not
always, picks up the end-of-line as a space (even
with set ve=)
v21 : Apr 01, 2013 - visual block and ragged right detection; there was
a conflict between using ve= and ve=all
(internally); one was good for ragged right and
the other for smooth right visual block selections.
I found a way to detect ragged right vs smooth right
and so vis.vim now works properly in both
situations.
Apr 02, 2013 - The detection method above hung when on line 1.
Fixed.
Jan 15, 2015 - Small adjustment to prevent a leading space from
being inserted.
Feb 10, 2016 - (Stefan Siegal) provided a patch making
visPlugin.vim restore cpo
Sep 07, 2016 - addressed an empty-string bug : if the block
command causes an empty string to appear in the
modified text, vim would insert a blank rather than
do nothing. Fixed by prepending an
"empty-character" and then removing it
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 <Esc> 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 - <q-args> used instead of '<args>'
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, <vis.vim> now requires <cecutil.vim>
(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 begcol<endcol for "v" mode)
v6 : Jun 25, 2002 - bugfix (VirtcolM1 instead of virtcol()-1)
v5 : Jun 21, 2002 - now supports character-visual mode (v) and
linewise-visual mode (V)
v4 : Jun 20, 2002 - saves sol, sets nosol, restores sol
- bugfix: 0 inserted: 0\<c-v>G$\"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 <vis.vim>
v? June 19, 2002 Complete rewrite - <vis.vim> is now immune to
the presence of tabs and is considerably faster.
v1 Epoch - Stefan Roemer <roemer@informatik.tu-muenchen.de>
wrote the original <vis.vim>.
==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker