vselmanager: vim visual selection manager — save & restore visual selections
The easiest way to access the documentation for this plugin is to type :h vselmanager.txt in Vim after installing it. Also, have a look at the changelog.
This plugin is a fork of the original visualMarks repository. There's also an unrelated visualMarks.vim.
| INTRODUCTION | vselmanager-introduction |
| USAGE | vselmanager-usage |
| MAPPINGS | vselmanager-mappings |
| VMARK NAMES | vselmanager-vmark-names |
| COMMANDS | vselmanager-commands |
| SETTINGS | vselmanager-settings |
| INSTALLING | vselmanager-install |
| LICENSE | vselmanager-license |
| CREDITS | vselmanager-credits |
INTRODUCTION vselmanager-introduction
This plugin lets you save visual selections to named "visual marks" ("vmarks") and later restore them, just as Vim's native marks do for cursor positions (but they are entirely separate entities). Vmark names are per-file (not global) and persistent.
USAGE vselmanager-usage
Assuming a standard setup (vselmanager-install): in visual mode, to save the selection to vmark "a", type
\vma
To later re-select the same area, type (in normal mode):
\v`a
and you'll be back in visual mode with the saved selection. Use lowercase
letters or <Space> as vmark names (vselmanager-vmark-names). Some names are
automatically assigned: ` is the most recently loaded vmark, and 0..1 are
the most recently saved vmarks (so regardless of the vmark name saved above,
and independently of Vim's gv selection, \v`0 will restore it).
Pressing <Tab> enters full name-editing mode with completion
(vselmanager-input-name). Alternatively, the mappings can be prefixed with a
register (e.g. "a\vm instead of \vma -- vselmanager-register-mappings).
See vselmanager-mappings and vselmanager-commands for more actions.
- no clobbering of Vim's regular marks and registers
- per-file vmarks
- vmarks persist after closing Vim
- vmarks save / restore the visual mode (v, V, Ctrl-V) of selections
- past-end-of-line ragged visual block selections are properly handled
MAPPINGS vselmanager-mappings
Most mappings require names (vselmanager-vmark-names) to operate on; see vselmanager-input-name and vselmanager-register-mappings for details on how the plugin requests these names from the user.
DEFAULT KEYS VselmanagerSetDefaultMaps() vselmanager-keys
These are set internally by calling the function
:call g:VselmanagerSetDefaultMaps( g:vselmanager_mapPrefix )
when the global prefix is set, which, assuming a "<Leader>v" prefix, results
in the following mappings (the "mapping" column lists the suffix after
<Plug>Vselmanager)
modes keys mapping-suffix Action
v \vm SaveVMark :VselmanagerSave
nv \v` LoadVMark :VselmanagerLoad
n \vd DelVMark :VselmanagerDel
nv \vp PutAVMark :VselmanagerPutA
nv \vP PutBVMark :VselmanagerPutB
nv \vy YankVMark <Plug>VselmanagerYankVMark
nv \vgv HistMR :VselmanagerHistNext 0
nv \v<Tab> HistNext :VselmanagerHistNext
nv \v<C-O> HistPrev :VselmanagerHistPrev
Set the preferred g:vselmanager_mapPrefix before the plugin loads (e.g. from
vimrc). The function does not re-bind <Plug> mappings already bound to
something else, so you can pre-bind some actions to other keys.
If g:vselmanager_mapPrefix is undefined, the plugin installs no bindings upon loading. You can thus selectively map any or all actions manually. You can also call VselmanagerSetDefaultMaps() at some later point in the startup sequence (e.g. from the after-directory).
MAP ACTIONS vselmanager-map-actions
- vselmanager-keys lists the associated command for most
<Plug>mappings - <Plug>VselmanagerYankVMark is described below
- all other
<Plug>mappings ending in "VMark" operate on a single vmark name - the "HistNext" and "HistPrev" mappings take an optional
[count]prefix (1 if omitted)
Yank the contents of the vmark into a register. Unlike other single-vmark
mappings, if prefixed by a register (e.g. "a), that register will act as
the destionation. The name of the vmark is always obtained as outlined in
vselmanager-input-name. If this mapping is invoked without a register
prefix, the contents will be yanked into the unnamed register (").
VMARK NAMES vselmanager-vmark-names
Names can be arbitrary strings, except that:
- names may not contain control chars (ASCII 0-31)
- names longer than a single char are harder to input (see below)
PLUGIN-MANAGED VMARKS vselmanager-auto-vmarks
Additionally, some names are automatically assigned / overwritten by the plugin:
- the name
`(backtick) is the most recently loaded vmark - numbers record the history of recently saved vmarks (currently only 0..1)
- names starting with an Uppercase letter are reserved for global vmarks (not currently implemented)
INPUT A VMARK NAME vselmanager-input-name
When requesting a vmark name, the plugin first reads a single char, which is
used immediately if such a vmark exists. <Esc>, <CR> or any control character
except <Tab> cancel the operation. <Tab> enters full input mode, where names
can be arbitrary strings and another <Tab> completes; again, <Esc> or entering
an empty name cancels.
REGISTER NAMES AS VMARKS vselmanager-register-mappings
Alternatively the mappings can be prefixed with a register, which acts purely as a vmark name (e.g.: "a\vm). This method bypasses the input mechanism used above (meaning such maps work in macros, don't echo any messages etc). On the other hand, the set of Vim register names (:help registers) is limited, so names created with another method might be unavailable as a prefix.
COMMANDS vselmanager-commands
In the following, {vmark} is a vmark name (vselmanager-vmark-names).
:VselmanagerSave {vmark}
Save current / most recent (gv) visual selection to {vmark}
:VselmanagerLoad {vmark}
Restore visual selection associated with {vmark}
:VselmanagerHistForward {delta} vselmanager-history-navigation
:[count]VselmanagerHistNext :VselmanagerHistNext
:[count]VselmanagerHistPrev :VselmanagerHistPrev
Navigate forwards / backwards through vmarks in alphabetical
order; the navigation pointer is not persisted, and may reset when you add
or remove vmarks. {delta} = 0 corresponds to the vmark most recently
loaded by "Hist" commands, -1 to the previous one and +1 to the next one.
{delta} can be any expr. The Next / Prev commands take a constant [count]
instead; it defaults to 1 and can precede or follow the command.
:VselmanagerDel {vmark}
Remove a previously saved vmark
:VselmanagerDelAll
Remove all vmarks from the current buffer
:VselmanagerPutA {vmark}
:VselmanagerPutB {vmark}
Paste a vmark's contents After / Before the cursor (like p / P). In
visual mode, overwrite the current visual selection.
:VselmanagerForgetFile {file}
Remove all vmarks from the specified file
:VselmanagerSwapVisual {vmark}
Swap the current visual selection with that of {vmark}; update {vmark}
to point to the its new location (its corresponding text unchanged). The
final visual selection text is the same as the initial one (but moved to
the initial {vmark} location). Both visual selections should have the same
type (e.g. both char visual or both line visual) and not overlap.
SETTINGS vselmanager-settings
Settings should be defined before the plugin loads (e.g. from vimrc; see ":help startup", ":help load-plugin").
DATABASE LOCATION g:vselmanager_DBFile
Vselmanager stores all vmarks in a single JSON file. Its default path is
let g:vselmanager_DBFile = fnamemodify('~/', ':p') .. '.vim-vselmanager.json'
This template should be portable, in case you decide to change the path / basename.
DEFAULT MAP PREFIX g:vselmanager_mapPrefix
Set to a prefix string to trigger automatic loading of default key mappings. Without it, no mappings are installed by default. See vselmanager-keys. Suggested:
let g:vselmanager_mapPrefix = '<Leader>v'
BEHAVIOR AFTER SAVING A VMARK g:vselmanager_exitVModeAfterMarking
The plugin exits visual mode after saving a vmark if this global is set to 1 (the default). Set it to 0 to remain in visual mode.
INSTALLATION vselmanager-install
With the Vim 8+ built-in package system (:help packages):
- clone (or symlink) the git repo under 'packpath'
- set the mapping prefix in
vimrc(g:vselmanager_mapPrefix) - (re)start Vim and run
:helptags ALL
For example, in Bash:
DIR=~/.vim/pack/vselmanager/start/
mkdir -p "$DIR"; cd "$DIR"
git clone "$VSELMANAGER_URL" # replace with actual URL
echo "let g:vselmanager_mapPrefix = '<Leader>v'" >> ~/.vimrc
vim -c 'helptags ALL' -cqOr use your preferred plugin manager.
LICENSE vselmanager-license
Vselmanager is released under the GPL v2.
See https://www.gnu.org/licenses/gpl-2.0.html
CREDITS vselmanager-credits
URL This repository https://github.com/kstr0k/vim-visualMarks Alin Mr. http://github.com/mralusw/ Original visualMarks https://github.com/iago-lito/vim-visualMarks Iago-lito https://github.com/iago-lito/ Steven Hall https://github.com/hallzy/
This file is based on the vim documentation (doc/vselmanager.txt) for this plugin, which is the authoritative reference (:h vselmanager.txt). It was initially generated using vimdoc2html.