/
yankring.txt
1585 lines (1446 loc) · 75 KB
/
yankring.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
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*yankring.txt* For Vim version 7.0.
Author: David Fishburn April 1, 2011
Version: 14.0
For instructions on installing this file, type
:help add-local-help |add-local-help| inside Vim.
Homepage: http://vim.sourceforge.net/script.php?script_id=1234
==============================================================================
1. Contents *yankring* *yankring-contents*
1. Contents...............................: |yankring-contents|
2. Description............................: |yankring-description|
3. Configuration..........................: |yankring-configure|
3.1 Global Variables...................: |yankring-globals|
3.2 Default Keys.......................: |yankring-mappings|
3.3 Customizing Maps...................: |yankring-custom-maps|
3.4 Customizing Menus..................: |yankring-custom-menus|
4. Using the YankRing Window..............: |yankring-window|
5. Commands...............................: |yankring-commands|
5.1 YRToggle..........................: |:YRToggle|
5.2 YRClear...........................: |:YRClear|
5.3 YRShow............................: |:YRShow|
5.5 YRGetElem.........................: |:YRGetElem|
5.6 YRGetMultiple.....................: |:YRGetMultiple|
5.7 YRPush............................: |:YRPush|
5.8 YRPop.............................: |:YRPop|
5.9 YRYankCount.......................: |:YRYankCount|
5.10 YRYankRange.......................: |:YRYankRange|
5.11 YRDeleteRange.....................: |:YRDeleteRange|
5.12 YRPaste...........................: |:YRPaste|
5.13 YRReplace.........................: |:YRReplace|
5.14 YRMapsCreate......................: |:YRMapsCreate|
5.15 YRMapsDelete......................: |:YRMapsDelete|
5.16 YRSearch..........................: |:YRSearch|
5.17 YRCheckClipboard..................: |:YRCheckClipboard|
5.18 YRRunAfterMaps....................: |:YRRunAfterMaps|
6. Tutorial...............................: |yankring-tutorial|
6.1 YRShow............................: |YRShow-example|
6.2 YRReplace.........................: |YRReplace-example|
6.3 YRPush............................: |YRPush-example|
6.4 YRClear...........................: |YRClear-example|
6.8 YRPop.............................: |YRPop-example|
6.9 Visual modes......................: |yankring-visual-example|
6.10 Using ranges......................: |YRYankRange-example|
6.11 :global...........................: |global-example|
6.12 YRSearch..........................: |YRSearch-example|
7. History................................: |yankring-history|
==============================================================================
2. Description *yankring-description*
Vim already maintains a list of numbered registers containing the last 9
deletes. These previous deletes can be referenced using [register]p, so
"1p will paste the last delete, "2p the 2nd last delete. For more
information see |quote_number|.
Vim does not provide any mechanism to reference previously yanked text.
In Emacs this feature is called the "kill ring".
The YankRing plugin allows the user to configure the number of yanked
and deleted text. After text has been pasted, it can be replaced with
a previous value from the yankring.
As of version 3.0, the yankring's content will persist (by default)
between starting and stopping Vim.
The plugin can be toggled on and off, and supports:
Ranges
Registers
Counts
All visual modes
All motions
All text-objects
If you have any suggestions for the improvement of this plugin, see the
yankring.vim file for my email address. Suggestions / bug reports are
always welcome.
For details on the changes between versions see |yankring-history|.
==============================================================================
3. Configuration *yankring-configure*
The YankRing allows the user to choose which keys are to be assigned to
the various commands. By default, the YankRing chose keys identical
with Vim's standard behaviour/keys.
3.1 Global Variables *yankring-globals*
You can customize the YankRing by setting various global variables in
your |.vimrc|.
>
yankring_max_history
< Default: 100
Controls how many elements to save in the yankring. >
let g:yankring_max_history = 100
yankring_min_element_length
< Default: 1
If the yanked element has a length less than this value
if will not be added to the YankRing. This can be useful if
you want to bypass single letter deletes by adding the
following to your .vimrc: >
let g:yankring_min_element_length = 2
yankring_max_element_length
< Default: 1048576 (1M)
Will truncate a new entry to the specified maximum. If
g:yankring_max_element_length is set to 0, there is no limit. >
let g:yankring_max_element_length = 4194304 " 4M
yankring_max_display
< Default: 500
When the YankRing window is opened, each element is displayed on a
separate line. Since each yank could be very large, the display of
the element is limited to the above default. >
let g:yankring_max_display = 70
yankring_enabled
< Default: 1
If you do not want to YankRing enabled by default, set this
variable in your |vimrc|. >
let g:yankring_enabled = 0 " Disables the yankring
yankring_persist
< Default: 1
If you have enabled the storing of global variables in the |viminfo|
file, the YankRing will be default persist the contents of the ring
between starting and stopping Vim. To disable this feature: >
let g:yankring_persist = 0
yankring_share_between_instances
< Default: 1
By default, any instance of Vim will share the same yankring
history file. But if want each instance to have their own history
you can set this option to 0. Setting g:yankring_persist = 0 and
g:yankring_share_between_instances = 0 will ensure no 2 instances
of Vim share the same YankRing history AND the history is not
remembered the next time Vim is started. >
let g:yankring_share_between_instances = 0
yankring_dot_repeat_yank
< Default: Based on the Vim cpoption setting
By default Vim will not repeat (using '.') yanking of text. This can
be controlled via the |'cpoptions'| setting. The YankRing now respects
the cpoptions setting, if 'y' is included and you press '.', the
previous yank command is repeated and added to the yankring.
You can also add this behaviour by setting this in your |vimrc|: >
let g:yankring_dot_repeat_yank = 1
yankring_ignore_duplicate
< Default: 1
Duplicates will not be added to the YankRing by default. If a
duplicate is found, that element will be moved to the top of the
yankring. This can be controlled by setting this in your |vimrc|: >
let g:yankring_ignore_duplicate = 0
yankring_map_dot
< Default: 1
If the '.' (repeat) command should be mapped by the yankring. Since
most of the normal commands yy,dd,dw,... are mapped by the yankring,
if g:yankring_map_dot is false the . operator will not repeat these
operations. The YankRing tracks several of the internal Vim registers
and decides whether an action was the result of the YankRing or an
action outside of it. If the previous action was a result of the
yankring, it will be executed again. If it was an action outside of
the yankring, it asks Vim to repeat the command. >
let g:yankring_map_dot = 1
yankring_paste_using_g
< Default: 1
By default [p] and [P] are mapped to interact with the yankring. This
option controls whether [gp] and [gP] are also mapped. Setting this
option to 0 will not create these maps. >
let g:yankring_paste_using_g = 1
yankring_window_use_separate
< Default: 1
This is a new feature as of the 2.0 release. The YankRing now uses a
separate split buffer to display the yankring. There are many buffer
specific maps that allow you to operate over the various elements from
within the yankring. Setting this option to 0, uses the 1.0
interface. >
let g:yankring_window_use_separate = 0
yankring_window_auto_close
< Default: 1
By default once you choose an option in the YankRing buffer, the
action is performed and the buffer window is closed, returning you to
the original buffer. This option can be toggled from within the
YankRing buffer by pressing [a]. The YankRing buffer status line
visually indicates where auto close is enabled or disabled. There are
many times where you need to paste (or delete) many items from the
yankring. Pressing [a], disables auto close, allows you to paste many
items, and finally you can press [a] to re-enable auto close, followed
by [q] to quit the buffer window. >
let g:yankring_window_auto_close = 1
yankring_window_use_horiz
< Default: 1
When the YankRing window is opened, it uses a horizontal split at the
bottom of the Vim window. It can optionally use a vertical split by
setting this option to 0. >
let g:yankring_window_use_horiz = 0 " Use vertical split
yankring_window_height
< Default: 1
If using a horizontal split, this option controls how high to make
the window. >
let g:yankring_window_height = 8
yankring_window_width
< Default: 1
If using a vertical split, this option controls how wide to make the
window. >
let g:yankring_window_width = 30
yankring_window_use_bottom
< Default: 1
If using a horizontal split, this option control whether the window is
opened at the top or bottom of the Vim window. Setting this option to
0 forces the window to open at the top of the Vim window. >
let g:yankring_window_use_bottom = 1
yankring_window_use_right
< Default: 1
If using a vertical split, this option control whether the window is
opened on the left or right side of the Vim window. To force the
window to open on the left side, set this option to 0. >
let g:yankring_window_use_right = 1
yankring_window_increment
< Default: 1
If using a vertical split the default width of the vertical window may
be too narrow to view enough of the elements. Pressing [<space>] will
increase the size of the window by this number of columns. Pressing
[<space>] again will toggle it back to the original size. >
let g:yankring_window_increment = 50
yankring_manage_numbered_reg
< Default: 0
Vim already maintains a list of numbered registers containing the last
yanked item and the previous 9 deletes. These items can be referenced
using [register]p, so "0p will paste the last yank, "1p will paste the
last delete, "2p the 2nd last delete. For more information see
|quote_number|.
If you wish the YankRing to maintain these numbered registers so
the top 10 elements in the YankRing are in the numbered reqisters 0-9
you can put the following in your |vimrc| >
let g:yankring_manage_numbered_reg = 1
yankring_ignore_operator
< Default: 'g~ gu gU ! = gq g? > < zf g@'
There are a number of Vim operations which do not change any
registers, and therefore should not be captured by the yankring.
This list is used to ignore the appropriate operators.
You can put the following in your |vimrc| >
let g:yankring_ignore_operator = 'g~ gu gU ! = gq g? > < zf g@'
yankring_history_dir
< Default: $HOME
The YankRing stores the text in a file. This global variable
allows you to customize where the file(s) will be stored.
You can put the following in your |vimrc| >
let g:yankring_history_dir = '$VIM'
yankring_history_file
< Default: 'yankring_history'
The history filename prefix can be controlled by setting this
variable.
You can put the following in your |vimrc| >
let g:yankring_history_file = 'my_yankring_history_file'
yankring_clipboard_monitor
< Default: 1
When flipping between applications I find I often copy text
and attempt to use it inside of Vim. This is typically easy
by simply using "+p, but there are times when I will repeatedly
want to use the same text later on. By default, the YankRing
will detect when Vim regains focus and check if the clipboard
has changed since it last checked. If so, it will add the contents
of the clipboard to the YankRing. This is accomplished by the
use of the FocusGained Vim event for the GUI Vim. For console
Vims, the FocusGained event does not fire, so additional logic
is added to deal with it. To disable this feature
you can put the following in your |vimrc| >
let g:yankring_clipboard_monitor = 0
yankring_manual_clipboard_check
< Default: 0
If running in console mode, Vim's FocusGained event will not
fire as we flip back and forth between windows. This normally
instructs the YankRing to check for updates to the system
clipboard. When this option is set, the YankRing will check
the clipboard under many different circumstances:
Adding a new entry to the YankRing
Replacing a previous paste
Showing the YankRing window
If the YankRing is setup to check the clipboard and the
GUI is not running, this option will be enabled by default.
To disable this feature you can put the following in your |vimrc| >
let g:yankring_manual_clipboard_check = 0
yankring_paste_check_default_buffer
< Default: 1
If the default register has changed without the YankRing registering
the change the YankRing will paste the top item from the history
rather than what is currently in the default register.
This option allows you to control the behaviour. Plugins can
intentionally change the default buffer which the YankRing has
no way to noticing. To disable this feature you can put the following
in your |vimrc| >
let g:yankring_paste_check_default_buffer = 0
yankring_default_menu_mode
< - Menus are useful for a number of reasons:
See a list of available commands.
Remember what the shortcut maps are.
Have a floating menu when using the plugin a lot.
Quick reference guide.
There are four settings that will control the placement
of the menu:
"0": Turns the menu off.
"1": Turns the 'Yankring' menu on with no menu shortcut.
"2": Turns the 'Yankring 'menu on with <alt>-y as the shortcut.
"3": Turns the 'Plugin -> YankRing' menu on with <alt>-y as
the shortcut.
This option defaults to a value of 3 and can be changed
by adding the following to your vimrc: >
:let g:yankring_default_menu_mode = 3
yankring_menu_root
< - Can be used in conjuction with g:yankring_default_menu_mode = 3 but
it also allows you to control the fullname and location of the
YankRing menu. To create the menu: 'MyPlugins -> YankRing' you
can create the following variable: >
:let g:yankring_menu_root = 'MyPlugin.&YankRing'
yankring_menu_priority
< - Menus are created in a documented order by Vim (|menu-priority|).
This option allows you to override the setting and shift the
YankRing menu item to the left between the Edit and Tools menu. >
:let g:yankring_menu_priority = 30
<
3.2 Default Keys *yankring-mappings*
You can choose to override the default keys by creating these global
variables in your |vimrc|.
>
yankring_n_keys
< n - normal mode
Default Vim 7.2:
'Y D x X'
Default Vim 7.1 and below:
'x yy dd yw dw ye de yE dE yiw diw yaw daw y$ d$ Y D yG dG ygg dgg'
With the introduction of some new features in Vim 7.2 it is no longer
necessary to list all cmds which the YankRing will act upon.
The yankring_n_keys only lists actions which an omap cannot be used.
Using the yankring_separator, the above list is parsed and
individual mappings are created. For each of the above normal
commands the YankRing will include the text those commands
acted upon. There are many ways to accomplish the same result
in Vim, if you do not see a common key stroke you regularly use
simply add the following to your |vimrc| with the additional
keys you wished mapped. >
let g:yankring_n_keys = 'Y D x X'
yankring_o_keys
< o - omap mode
Default:
Standard motions: 'b B w W e E d y $ G ;'
Vim text objects: ' iw iW aw aW as is ap ip a] a[ i] i['
'a) a( ab i) i( ib a> a< i> i< at it '
'a} a{ aB i} i{ iB a" a'' a` i" i'' i`'
As of Vim 7.2 omaps are used to capture changes to the registers
in Vim. All of the standard motion commands are captured.
New to YankRing 5.0 all default Vim text objects are also
captured.
Using the yankring_separator, the above list is parsed and
individual mappings are created. For each of the above normal
commands the YankRing will include the text those commands
acted upon. There are many ways to accomplish the same result
in Vim, if you do not see a common key stroke you regularly use
simply add the following to your |vimrc| with the additional
keys you wished mapped. >
let g:yankring_o_keys = 'b B w W e E d y $ G ; iw iW aw aW'
yankring_zap_keys
< Default: 'f F t T / ?'
omaps are enough for most operations except for f and t.
These motions prompt the user for a character or string which
they should act upon. These must be treated as a special case
in YankRing. >
let g:yankring_zap_keys = 'f t'
yankring_ignore_operator
< Default: 'g~ gu gU ! = gq g? > < zf g@'
There are certain motions which do not update any registers
in Vim. If the registers are not changed, there is nothing
the YankRing can capture. This list instructs the YankRing
to ignore any action for these keys. >
let g:yankring_ignore_operator = 'g~ gu gU'
yankring_v_key
< v - visual mode
Default: y
Yanks visually select text. >
yankring_del_v_key
< n - normal mode
Default: d
The visually select text is included in the YankRing and deleted. >
yankring_paste_n_bkey
< n - normal mode
b - before
Default: P
The default Vim paste key will retrieve from the yankring. This
will paste the text BEFORE the current position.
There is a special check to see if the text in the default paste
register is the same as what is in the current position of the
yankring. If it is not, we assume the user used some other
mechanism to yank text (ie yt<character>). If this is the case
we paste the text in the default paste buffer. Using <C-P> the
text can be replaced with the current entry from the yankring.
Since there are many ways to do things in Vim, this provides
the best integration. >
yankring_paste_n_akey
< n - normal mode
a - after
Default: p
The default Vim paste key will retrieve from the yankring. This
will paste the text AFTER the current position.
There is a special check to see if the text in the default paste
register is the same as what is in the current position of the
yankring. If it is not, we assume the user used some other
mechanism to yank text (ie yt<character>). If this is the case
we paste the text in the default paste buffer. Using <C-P> the
text can be replaced with the current entry from the yankring.
Since there are many ways to do things in Vim, this provides
the best integration. >
yankring_paste_v_key
< n - normal mode
Default: p
This will replace the visually select text with the contents
from the yankring. See yankring_paste_n_akey for additional
details. >
yankring_replace_n_pkey
< n - normal mode
Default: <C-P>
If you do not want to open the YankRing window to choose your
selection, then you can paste (as usual) then use a YankRing
mapping to cycle through items in the YankRing. This is especially
useful if you know you recently used the text you are looking for.
If you wish to cycle through the yankring, replacing the previously
pasted text with the previous yanked text you can repeatedly press
<C-P> (or whatever keystroke you choose to map it to). This map
moves backwards through the yankring, so you will retrieve your
most recent yank.
I prefer not to use <C-P> since I like using that key to cycle
through all the matches in the QuickFix window. You can add
something similar to this in your |.vimrc| to get similar
functionality.
On Windows use the ALT-< character to move through the YankRing.
To determine what character # these are go into insert mode
in a new buffer. Press CTRL-V then ALT and the < key.
Leave insert mode, move the cursor onto the character
and press ga. This will display the decimal, hex and octal
representation of the character. In this case it is 172. >
if has('win32')
let g:yankring_replace_n_pkey = '<Char-172>'
let g:yankring_replace_n_nkey = '<Char-174>'
" Instead map these keys to moving through items in the quickfix window.
nnoremap <C-P> :cp<cr>
nnoremap <C-N> :cn<cr>
endif
< Other users have also stated that this will work: >
let g:yankring_replace_n_pkey = '<m-p>'
let g:yankring_replace_n_nkey = '<m-n>'
yankring_replace_n_nkey
< n - normal mode
Default: <C-N>
If you do not want to open the YankRing window to choose your
selection, then you can paste (as usual) then use a YankRing
mapping to cycle through items in the YankRing. This is especially
useful if you know you recently used the text you are looking for.
If you wish to cycle through the yankring, replacing the previously
pasted text with the next yanked text you can repeatedly press
<C-N> (or whatever keystroke you choose to map it to). This map
moves forwards through the YankRing, so you will retrieve your
most recent yank.
I prefer not to use <C-N> since I like using that key to cycle
through all the matches in the QuickFix window. You can add
something similar to this in your |.vimrc| to get similar
functionality.
On Windows use the ALT-> character to move through the YankRing.
To determine what character # these are go into insert mode
in a new buffer. Press CTRL-V then ALT and the > key.
Leave insert mode, move the cursor onto the character
and press ga. This will display the decimal, hex and octal
representation of the character. In this case it is 174. >
if has('win32')
let g:yankring_replace_n_pkey = '<Char-172>'
let g:yankring_replace_n_nkey = '<Char-174>'
" Instead map these keys to moving through items in the quickfix window.
nnoremap <C-P> :cp<cr>
nnoremap <C-N> :cn<cr>
endif
< Other users have also stated that this will work: >
let g:yankring_replace_n_pkey = '<m-p>'
let g:yankring_replace_n_nkey = '<m-n>'
3.3 Customizing Maps *yankring-custom-maps*
The YankRing plugin uses the yankring_n_keys global variable to create
a number of defaults maps. The maps are of the form: >
nnoremap Y :<C-U>YRYankCount 'Y'<CR>
<
When capital Y is pressed, the YankRing will execute 'Y' and capture the
output from Vim. But there are cases where you do not want the default
behaviour of Vim, since you have customized some of these maps.
In this case, I usually map Y to be |y$|, which makes it consistent with
the |D| and |C| operators. The way yankring_n_keys works does not allow
me to customize this behaviour. Since many people may like to customize
the behaviour of these maps the YankRing will check to see if a
function called YRRunAfterMaps() exists. If it does, it will call
this function after it has created the maps. So in my case, I created
the following function in my |vimrc|: >
function! YRRunAfterMaps()
nnoremap Y :<C-U>YRYankCount 'y$'<CR>
endfunction
<
You can do anything you need in this function. >
nnoremap Y :<C-U>YRYankCount 'y$'<CR>
<
This line remaps Y (which the user presses) to the YRYankCount command. The
YRYankCount tells Vim to execute y$ instead.
3.4 Customizing Menus *yankring-custom-menus*
There are several global variables which can be created in your vimrc to
allow you to customize where and what is displayed for the YankRing menu.
Simply look up the following global variables: >
yankring_default_menu_mode
yankring_menu_root
yankring_menu_priority
==============================================================================
4. Using the YankRing Window: *yankring-window*
This is a new feature as of the 2.0 release. The YankRing uses a
separate split buffer to display the yankring. There are many buffer
specific maps that allow you to operate over the various elements from
within the yankring.
To display the YankRing buffer you can issue the :YRShow command. For
convience you can map a key, <F11>, to this command: >
:nnoremap <silent> <F11> :YRShow<CR>
Status line~
The first line in the YankRing window is the status line. >
AutoClose=1;ClipboardMonitor=1;Cmds:[g]p,[g]P,1-9,d,r,s,a,c,u,q,<enter>,<space>;Help=?
<
Help=?, pressing [?] will toggle the display of available commands the
yankring window supports. Pressing [?] again will remove the additional
items.
AutoClose=1 indicates the window will close when an action is performed
against elements within the yankring. If you wish to perform multiple
yankring operations press [a] to toggle the auto close feature off. Use the
commands below and when finished you can press [a] to toggle auto close on and
press [q] to close the window. The Cmds displayed are simply reminders of
the available keys.
ClipboardMonitor=1 indicates the YankRing will monitor the clipboard (+)
during Focus change events. If the clipboard has changed since the YankRing
last checked, the contents are added to the YankRing. Pressing [c] allows
you to quickly toggle this setting since it may not be useful at times.
YankRing window key list~
The following table lists the description of the keys that can be used
in the YankRing window.
Key Description~
p Puts text after the cursor. In visual mode, all elements
selected will be pasted.
P Puts text before the cursor. In visual mode, all elements
selected will be pasted.
gp Just like "p", but leave the cursor just after the new text.
gP Just like "P", but leave the cursor just after the new text.
<CR> Just like "p".
<Enter> Just like "p".
<2-LeftMouse> Just like "p". Normal mode only.
1-9 Short cut to paste the n'th number from the YankRing.
d Removes the element from the yankring. In visual mode all
elements selected will be removed.
r Just like "p", but in visual mode if many lines are selected
it will paste these items in reverse order.
s Prompts you for a regex to search the YankRing and display
only matching items.
a Toggles the g:yankring_window_auto_close setting.
u Updates the YankRing window.
q Closes the YankRing window.
<Space> Toggles the width of the vertical window by the
g:yankring_window_increment setting.
? Toggles the display of the help.
==============================================================================
5. Commands: *yankring-commands*
The predefined mappings call some specific commands with special parameters.
If you are going to create additional maps, it is important you mirror
the same parameters. Most of these commands have been made obsolete by
the YankRing window, since it incorporates the functionality below, but
through maps against a buffer, instead of commands. This makes it much easier
to use.
5.1 YRToggle :*YRToggle*
Allows you to enable and disable the YankRing quickly. This
command will remove the default maps and recreate them.
Examples: >
:YRToggle " Toggles it
:YRToggle 1 " Enables it
:YRToggle 0 " Disables it
<
5.2 YRClear :*YRClear*
Clears all elements from the yankring.
See also |YRClear-example|.
5.3 YRShow :*YRShow*
Similar to |:register|, will display all the entries in the yankring.
The element at the top will be the next element pasted from the
yankring.
Examples: >
:YRShow " Shows all entries in the yankring
--- YankRing ---
Elem Content
1 five^@
2 four^@
3 three^@
4 two^@
5 one^@
<
5.5 YRGetElem :*YRGetElem*
This command has two modes. If no parameters are provided, it
becomes interactive. It uses YRShow to display the list and
allows you to choose which element to paste. If a parameter
is supplied it will paste that element from the yankring. If the
number specified is outside of the YankRing an error is returned.
You may want to create a separate mapping for this call. >
nnoremap <silent> <Leader>yr :YRGetElem<CR>
< See also |YRSearch|.
Examples:
Assume there are 10 elements in the YankRing and element 6 is
at the top of the ring. >
:YRGetElem " Interactive mode, you choose from a list
:YRGetElem 4 " Will paste element 5.
:YRGetElem 12 " Will paste element 6.
:YRGetElem 99 " Error, invalid choice is reported
:YRGetElem 0 " Error, invalid choice is reported
5.6 YRGetMultiple :*YRGetMultiple*
Will paste many elements from the YankRing in one command.
If the number specified is 1 or less, it is assumed you want
just the current element pasted. If the number specified is
greater than or equal to the number of elements in the yankring,
it is assumed you want all elements pasted. If a ! is included
as part of the command, paste the items in reverse order.
See the |yankring-tutorial| for more examples.
Examples:
Assume there are 10 elements in the YankRing. >
:YRGetMultiple 4 " Will paste elements 1,2,3,4
:YRGetMultiple! 4 " Will paste elements 4,3,2,1
:YRGetMultiple " Will paste element 1
:YRGetMultiple 12 " Will paste elements 1,2,...,10
:YRGetMultiple 99 " Will paste elements 1,2,...,10
:YRGetMultiple 0 " Will paste element 1
5.7 YRPush :*YRPush*
Allows the user to "push" additional entries into the yankring.
If you yanked text via a key mapping which does not use the
YankRing (or there is text on the clipboard) you can use this
command to add the text to the yankring.
Examples: >
:YRPush " Push the " register's contents
:YRPush '*' " Push the "* register's contents (clipboard)
:YRPush '+' " Push the "+ register's contents (clipboard)
:YRPush 'a' " Push the "a register's contents
< See also |YRPush-example|.
5.8 YRPop :*YRPop*
Allows you to pop any elements from the yankring. If no parameters
are provided, the 1st element is removed from the yankring. The
command optionally takes a second parameter to specify how many
elements to pop. The default value is 1.
Examples: >
:YRPop " Removes the highest numbered element from the
yankring
:YRPop 3 " Removes the 3rd element from the yankring
:YRPop 3,5 " Removes 5 elements from the YankRing beginning
at element 3
< See also |YRPop-example|.
5.9 YRYankCount :*YRYankCount*
This command has the most mappings created for it. If you are
in normal mode and you are not specifying a range, this command
will add the text to the yankring.
The goal of this command is to allow the YankRing to be integrated
as seamlessly as possible with Vim. So it supports counts and
registers. If you create a mapping to it, you must pass as a
parameter the action you want Vim to perform. You could do the
following: >
nnoremap \test :<C-U>YRYankCount 'dd'<CR>
< This map is executed when you hit the '\test' keystrokes, but
it will actually delete the current line and add it to the
yankring.
The following are the default mappings: >
nnoremap yy :<C-U>YRYankCount 'yy'<CR>
nnoremap dd :<C-U>YRYankCount 'dd'<CR>
nnoremap yw :<C-U>YRYankCount 'yw'<CR>
nnoremap dw :<C-U>YRYankCount 'dw'<CR>
nnoremap ye :<C-U>YRYankCount 'ye'<CR>
nnoremap de :<C-U>YRYankCount 'de'<CR>
nnoremap yiw :<C-U>YRYankCount 'yiw'<CR>
nnoremap diw :<C-U>YRYankCount 'diw'<CR>
nnoremap Y :<C-U>YRYankCount 'Y'<CR>
nnoremap D :<C-U>YRYankCount 'D'<CR>
nnoremap y$ :<C-U>YRYankCount 'y$'<CR>
nnoremap d$ :<C-U>YRYankCount 'd$'<CR>
nnoremap yG :<C-U>YRYankCount 'yG'<CR>
nnoremap dG :<C-U>YRYankCount 'dG'<CR>
<
Examples:
yy - Adds the current line to the yankring.
dd - Adds the current line to the YankRing and deletes it.
5yw - Adds 5 words to the yankring.
"ade - Deletes the word, and puts it into both the yankring
and the "a register.
10"zyy - Places 10 lines into both the YankRing and the "z
register.
See also |yankring-tutorial|.
5.10 YRYankRange :*YRYankRange*
This command by default is only called in visual mode. All
visual modes (|characterwise-visual|, |linewise-visual|,
|blockwise-visual|) are supported. Any visually selected text
is added to the yankring. You can also call this command
directly using a range.
Examples:
Visual mode
-----------
Press v (to enter visual mode), highlight want you want,
press y (to yank the selected area).
Repeat using V and Control-V.
Normal mode
----------- >
:5,20YRYankRange " Will yank lines 5-20 into the yankring
:5,20YRDeleteRange " Will delete lines 5-20 and add them to
the yankring
< See also |YRYankRange-example|.
5.11 YRDeleteRange :*YRDeleteRange*
This command is identical to YRYankRange, except the range is
also deleted.
5.12 YRPaste :*YRPaste*
This command will paste elements from the yankring. By default it has
been mapped to p and P to match Vim's native key strokes. The text
pasted is exactly what was yanked, including newline characters and
blockwise-visual mode behaviours. It supports counts and registers.
Examples:
p " Paste the current element from the YankRing after the cursor
P " Paste the current element from the YankRing before the cursor
5p " Paste the current element from the YankRing after the cursor
5 times
"ap " Ignore the YankRing and paste the contents of register "a
5"ap " Ignore the YankRing and paste the contents of register "a
5 times
See also |yankring-tutorial|.
5.13 YRReplace :*YRReplace*
The purpose of the YankRing is to gain access to previously yanked
(or deleted) elements. This command will replace the previous
paste with a different entry from the yankring.
By default, I choose <C-P> (P for previous) to replace the last paste
while moving backwards through the yankring. <C-N> (N for next)
replaces the last paste while moving forward through the yankring.
Examples:
See the |yankring-tutorial| for examples.
On the Windows platform, I use ALT-< and ALT-> to move back and
forwards through the yankring instead of C-P and C-N. ALT-< is
actually ALT-, since I do not press the Shift key to get the <.
To do this, I added the following to my .vimrc:
" Do not map the default <C-N> and <C-P> keys
" These two characters are the ALT-< and ALT->.
" To determine what character # these are go into insert mode
" in a new buffer. Press CTRL-V then ALT and the > key.
" Leave insert mode, move the cursor onto the character
" and press ga. This will display the decimal, hex and octal
" representation of the character. In this case, they are
" 172 and 174.
if has('win32')
let g:yankring_replace_n_pkey = '<Char-172>'
let g:yankring_replace_n_nkey = '<Char-174>'
endif
5.14 YRMapsCreate :*YRMapsCreate*
This public function is responsible for creating the maps which
enable the yankring. This function is called by the YRToggle
command.
5.15 YRMapsDelete :*YRMapsDelete*
This public function removes the YankRing maps and disables
the yankring. This function is called by the YRToggle command.
5.16 YRSearch :*YRSearch*
This command is similar to |YRGetElem|. The command takes
one parameter which is a regular expression. Similar to
YRGetElem, it will display all items in the YankRing that match
the regular expression. It is also interactive, and will
prompt you to enter which match you wish pasted.
See also |YRSearch-example|.
5.17 YRCheckClipboard :*YRCheckClipboard*
Normally the GUI Vims will automatically (via autocmds)
check for changes to the system clipboard and add any new
changes to the YankRing. Most console Vim's do not fire
the required autocmds. This command will perform the check
manually.
5.18 YRRunAfterMaps :*YRRunAfterMaps*
See the following section |yankring-custom-maps|.
==============================================================================
6. Tutorial *yankring-tutorial*
To understand how to use the yankring, the following example will
demonstrate the various features. Assume you have created the following
mapping: >
nnoremap <silent> <F11> :YRShow<CR>
<
Assume we have this buffer: >
one
two
three
four
five
< *YRShow-example*
Now yank (yy) each line separately starting at line 1.
Display the contents of the YankRing by executing the command
YRShow, or pressing <F11>. The contents of the YankRing is
displayed in a new buffer. The size, location and type of buffer
is configurable via various options. See section 3 for more details. >
:YRShow or F11
--- YankRing ---
Elem Content
1 five^@
2 four^@
3 three^@
4 two^@
5 one^@
< Since we yanked the text starting at line 1 and finishing at
line 5, the most current YankRing element is the last one, the
contents of line 5. "five^@" is displayed, the "^@" is a
newline character (since we issued a "yy").
*yankring-window-example*
At this point, you have two options. You can choose which element
from the YankRing you wish to paste and press <CR> or 'p' or 'P'
and a variety of other options, see |yankring-window|. After pressing
the key, the YankRing window will close (default behaviour). Pressing
'?' will display additional help for the commands that are active within
the YankRing window. Pressing '?' will toggle the help.
You do not need to interact with the YankRing using the YankRing window.
Using the window makes many tasks must easier, but for speed using some
of the other maps can be preferrable if you know what you have yanked /
deleted recently. It was designed to work with Vim in the usual manner.
You can press, 'p', to paste the last item in yanked or deleted.
Close the YankRing window by pressing 'q' or F11 (which toggles it).
*YRReplace-example*
Now, go to the end of the file and press 'p'. The resulting
buffer appears as: >
one
two
three
four
five
five
<
Assume you did not want 'five", but a different entry from within the
yankring. <C-P> moves backwards through the yankring, it will replace
the previous pasted text with a different item from the yankring. This
allows you to quickly iterate through different elements. <C-P> is the
default mapping, this can be user defined. See the following options for
more details: >
yankring_replace_n_nkey, yankring_replace_n_pkey
<
After pressing <C-P> the buffer results in: >
one
two
three
four
five
four
< Now press 2<C-P>. This would be the same as pressing
<C-P> two times in a row. This results in: >
one
two
three
four
five
two
< Now press <C-N> to move forwards through the yankring,
this results in: >
one
two
three
four
five
three
< Display the contents of the yankring. >
:YRShow
--- YankRing ---
Elem Content
1 five^@
2 four^@
3 three^@
4 two^@
5 one^@
<
Now lets yank some text with a key stroke that has not been
mapped to the yankring. Place your cursor at the start of
line 4. Press 'ytr', yank-to-(to the character r), which yanks
the 'fou' letters (no newline character). Now press p. Here is
the result: >
one
two
three
ffouour
five
three
< This is good, even though the keys 'ytr' has not been mapped
to YRYankCount, the YankRing still pasted the most recently
yanked text. Since the text did not have a newline character
the 'fou' was inserted after the 'f'.
Now replace that previous paste with the current element from
the YankRing by pressing <C-N>. This is the result: >
one
two
three
four
one
five
three
< The #1 entry in the YankRing is still the line "five@". When
choosing the next entry, it wraps around to the last entry in
the yankring, element #5. The 'fou' was replaced with 'one^@'.
Since it had a newline character in it (when it was yanked) the
newline is included when it is pasted.
*YRPush-example*
Assume you need to paste text from the system clipboard, and this
is text you will need routinely. We can simulate this by running
this command (see |quote+|): >
:let @+ = "From the clipboard\n"
:echo @+
< With the cursor at the start of the line with the word 'five', press 'p'.
We still have pasted the 'fou' which is in the default paste buffer. >
one
two
three
four
two
ffouive
three
< We have the option of getting the text from the clipboard directly
with the following. >
First undo the previous change - u
Next - "+p
< The line changes since we bypassed the yankring, and specified
which register to get the text from: >
four
five