forked from iago-lito/vim-visualMarks
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathvselmanager.txt
250 lines (189 loc) · 11.5 KB
/
vselmanager.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
*vselmanager.txt* Save & restore visual selections
Version 0.2.1
==============================================================================
CONTENTS *vselmanager-toc*
- 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.
------------------------------------------------------------------------------
FEATURES
- 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 key 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)
*<Plug>VselmanagerYankVMark*
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 / 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*
The plugin 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' -cq
Or use your preferred plugin manager.
==============================================================================
LICENSE *vselmanager-license*
Vselmanager is released under the GPL v2.
See https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
==============================================================================
CREDITS *vselmanager-credits*
URL ~
This repository https://github.com/kstr0k/vim-vselmanager
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/
vim:tw=78:ts=8:ft=help:norl: