*yankring.txt* For Vim version 7.0.
Author: David Fishburn August 29, 2009
Version: 10.0
For instructions on installing this file, type
:help add-local-help |add-local-help| inside Vim.
==============================================================================
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|
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 YRRunAfterMaps....................: |yankring-custom-maps|
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. To disable this feature
you can put the following in your |vimrc| >
let g:yankring_clipboard_monitor = 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
<
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.
==============================================================================
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:p,P,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.
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 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 previously
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.
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|.
==============================================================================
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
From the clipboard
three
< <C-P> replaces this with the #1 entry in the yankring: >
four
five
five
three
< Now add the contents of the clipboard to the yankring: >
:YRPush '+'
< Move the cursor to the last row 'three' and press 'p'. The result is: >
four
five
one
three
From the clipboard
< YRPush '+' adds the value of the register '+' to the yankring, but it
also adds its contents to the default Vim paste buffer. So pressing
'p' pasted this text. Adding a new value to the YankRing we have
repositioned it which you can see with: >
:YRShow or F11
--- YankRing ---
Elem Content
1 From the clipboard^@
2 five^@
3 four^@
4 three^@
5 two^@
6 one^@
< *YRClear-example*
Now we will clear the yankring, and begin over again. Delete all lines
from the buffer and replace them with the original rows: >
one
two
three
four
five
< Now run this command to clear the YankRing to start over: >
:YRClear
<
Issue a 'yy' on each of the 5 lines. If you run the YRShow command you
should see the following: >
:YRShow or F11
--- YankRing ---
Elem Content
1 five^@
2 four^@
3 three^@
4 two^@
5 one^@
< *any-item-example*
If you need to quickly browse the YankRing to determine which element you
wish to paste you can simply press 'p' or <CR> or <Enter> on any element
displayed in the YankRing window. Press '?' for more detailed description
of the commands available.
Using the YankRing window can be much faster if you do not want to cycle
through the YankRing using <C-P> and <C-N> to find the element.
*multiple-items-example*
There are times when you need to move through a buffer capturing many
different lines (or snippets of code) and eventually want to switch
buffers and paste these elements. With some advance planning you can do
this without the YankRing by issuing commands of the form: >
"ayy
"Ayy
< When specifying the register using UPPERCASE, Vim appends the yanked text
to register "a, instead of replacing it. Many times you forget the
advance planning (or didn't even know about this great feature) you can
use the YankRing window to do this easily. If this is the current
yankring: >
:YRShow or F11
--- YankRing ---
Elem Content
1 five^@
2 four^@
3 three^@
4 two^@
5 one^@
< The YankRing works in |visual-mode|. To demonstrate move the cursor in
the buffer to the line with 'two'. Press 'F11' to display the yankring
window. Move the cursor to element 2, press 'V' to enable
|linewise-visual| mode and then press 'j' twice. This should have
visually highlighted elements 2,3,4. Press 'p' to paste all the
highlighted elements: >
one
two
four
three
two
three
four
five
< You can see here it has pasted four, three, two after the second line of
the buffer. Now press 'u' to undo our last change. Leave the cursor
on the second line 'two'. Press 'F11' to show the YankRing again.
Visually select the same lines, but this time press 'r' instead of 'p'.
'r' is for reverse, so it will paste the following: >
one
two
two
three
four
three
four
five
<
*YRGetMultiple-example*
The same behaviour listed above (by visually selecting items in the
YankRing window) can be achieved using the YRGetMultiple command.
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
<
*YRSearch-example*
The default size of the YankRing is 100 elements. It can be
tedious searching through the YankRing to find the element you
need. YRSearch is similar to YRShow except it will limit the
items displayed to only those items matching the regex provided. >
:YRShow
--- YankRing ---
Elem Content
1 Three Mississippi
2 Two Mississippi
3 One Mississippi
4 @", '\\/.*$^~[]' )
:YRSearch Mississippi
--- YankRing ---
Elem Content
1 Three Mississippi
2 Two Mississippi
3 One Mississippi
< Consider some items which require escaping the search string: >
:YRSearch @", '\\
--- YankRing ---
Elem Content
1 @", '\\/.*$^~[]' )
< Forward slashes and various other symbols require escapes, in this
case the slash was not escaped enough: >
:YRSearch @", '\\/
--- YankRing ---
Elem Content
< There are enough escapes this time: >
:YRSearch @", '\\\\/
--- YankRing ---
Elem Content
1 @", '\\/.*$^~[]' )
< Period, star, dollar and so on require one slash: >
:YRSearch @", '\\\\/\.\*\$\^\~\[\]
--- YankRing ---
Elem Content
1 @", '\\/.*$^~[]' )
< *YRPop-example*
You can remove any element from the YankRing by pressing pressing 'd' from
within the YankRing window. Visual mode is also supported to remove more
than one element at a time. >
:YRShow
--- YankRing ---
Elem Content
1 four^@
2 three^@
3 two^@
4 one^@
< Visually select elements 2,3. Press 'd', the result is: >
:YRShow
--- YankRing ---
Elem Content
1 four^@
2 one^@
< *yankring-visual-example*
There are 3 visual modes and all are supported. Any visually selected
text is added to the yankring. You can try the various modes. Move
the cursor to inside the buffer (not the YankRing window).
|characterwise-visual|
Go to line 1, press 'v' and move using the cursor keys until you have
highlighted some text. Then press y to yank the visually selected
area. Pressing p with paste the yanked region.
|linewise-visual|
Go to line 2, press 'V' and move using the cursor keys until you have
highlighted some text. Notice the entire line is selected (including
the carriage returns). Then press y to yank the visually selected
area. Pressing p with paste the yanked region.
|blockwise-visual|
Go to line 3 column 4, press CTRL-V and move to the right using the
cursor keys until you have highlighted some text. Then press y to
yank the visually selected area. Pressing p with paste the yanked
region. Notice the pasted text retained its blockwise visual
characteristics.
*YRYankRange-example*
YRYankRange is called during visual modes, but it is also possible to
use this via the command line. >
:1,4YRYankRange
:3,$YRDeleteRange
:YRShow
<
*global-example*
Using Vim's |:global| command can be very useful at times. The example
adds all rows (in a buffer) to the YankRing if they have a certain
phrase: >
:g/addme/YRYankCount 'yy'
< This is the breakdown for the above command: >
:g - for each line in the buffer
/addme - check if the string "addme" is in the line
/YRYankCount 'yy' - Ask the YankRing to execute the 'yy' command
==============================================================================
7. History *yankring-history*
10.0: January 31, 2010
NF: Change the buffer name to [YankRing] to resemble other
non-user buffers.
NF: Added g:yankring_min_element_length which can prevent
items from being added to the YankRing if they are too small.
For example, single character deletes (Vedran M).
BF: When shifting focus back to Vim, the YankRing may incorrectly
report: "YR:Failed to change to the yankring buffer,
please contact author".
BF: When entering Vim for the first time and hitting "p"
nothing was pasted (Mark Huiskes).
BF: When entering Vim for the first time and the
yankring_clipboard_monitor = 1, the clipboard entry
was not automatically added to the yankring.
BF: When overriding the default and setting
g:yankring_window_use_bottom = 0, the YankRing would
report the error (Sergey Khorev):
E21: Cannot make changes, 'modifiable' is off
9.0: August 29, 2009:
BF: You cannot execute a macro with ":normal @a". It is still
not possible, but you can execute it with ":normal! @a"
(A S Budden).
BF: When g:yankring_persist = 0 the YankRing could go into
an infinite loop (A S Budden).
BF: When replaying a macro which used any of the zap
keys (f,F,t,T,/,?) you were prompted again for the
string to match on (Ovidiu C).
BF: When checking the clipboard for changes
(g:yankring_clipboard_monitor == 1) only add the item
if it is not already in the ring. Previously, the item
was moved to the top of the YankRing each time you flipped
focus.
8.0: December 21, 2008:
NF: Changed the implementation of YRGetSearch() (David Liang).
BF: Under some unknown circumstances, the yankring can fail
to change to the correct buffer. Put in code to double
check and abort.
BF: Yanking and pasting a line which ends in a backslash
resulted in the backslash being replaced by "@@@".
BF: When repeating a command (".") which used any of the zap
keys (f,F,t,T,/,?) you were prompted again for the
string to match on (Vasilii Pascal).
7.0: November 14, 2008:
NF: Added support for the / and ? motions so that y/search is
supported (Vasilii Pascal).
NF: When the YankRing window is displayed (or updated) an additional
check is made against the default register. If it has changed
since the YankRing recorded it, the value will be added to the
history.
NF: Added support for more motions h, j, k, l, H, M, L, ^, 0, -, +, _.
And a pile of g motions g_, g^, gm, g$, gk, gj, gg, ge, gE.
NF: The YankRing window will display a message it is operating
in a limited mode if not using Vim 7.2 or the correct patch
level.
BF: Correction to some internal code which could lead to an
endless loop (John Beckett).
BF: Opening and closing the YankRing window with "set report=0"
reported "1 line less" messages (Bill McCarthy).
BF: Changed the default value of g:yankring_paste_check_default_buffer
to check if the default paste buffer has changed when pressing
'p'. For example, if a plugin has changed the default registers
it will be pasted rather than the top item from the YankRing.
BF: YRMapsDelete did not remove all the maps created by the YankRing.
BF: Under particular circumstances, yanking text with embedded @
characters were not properly stored and retrieved from the
YankRing (Andrew Long).
BF: Changed to use xmaps instead of vmaps so that the maps only work
in visual mode and not select mode (David Liang).
6.1: October 31, 2008:
BF: If the g:yankring_history_dir contains spaces (default on
Windows) an error was reported. A simple work around was to
let g:yankring_history_dir = 'c:\Vim' or no spaces (Matt).
6.0: October 25, 2008:
NF: The YankRing now maintains the history in a file. This means
if you are running multiple instances of Vim, they all see
the same yankring.
NF: The location and name of the file is configurable by the user.
NF: The g:yankring_separator is no longer used and has been removed.
NF: The g:yankring_max_element_length can be used to limit the size
of an element in the yankring.
NF: The g:yankring_share_between_instances can be used to indicate
whether each instance of Vim running on a machine should share
the history file or whether each should have their own
individual history file.
NF: The g:yankring_clipboard_monitor can be used to indicate
whether changes to the system clipboard should be added to the
YankRing (default is on).
NF: The YankRing window can toggle the clipboard monitor by pressing
'c'. See the help in the window by pressing ?.
NF: Added some highlighting to the YankRing window (Marty Grenfell).
5.0: September 21, 2008:
NF: The YankRing can recognize certain Vim commands which do not
change the contents of a buffer and not attempt to capture it.
NF: The global variables which allow you to customize the behaviour
are now space separated instead of comma separated. This
provides greater flexibility but will require you to modify
your vimrc (if you have customized it). (Andy Wokula)
BF: If using <C-O> from within insert mode, the YankRing inserted
characters into the buffer instead of capturing the changes,
this was fixed by Andy Wokula (Agathoklis Hatzimanikas).
BF: The YankRing did not properly account for all the different
forms of counts "5yy" worked but "y5y" did not (Edwin Shao).
4.1: August 9, 2008:
NF: The YankRing now allows you to override which operators should
be ignored (yankring_ignore_operator). By default this is
set for the standard Vim operators which do not modify any
registers (Examples: = and gu) (Andy Wokula).
NF: The YankRing did not map v_x (Matt Tolton).
BF: The expression register (quote=) was not accounted for correctly
(Agathoklis Hatzimanikas).
BF: Using the v:operator variable must be escaped when used in
a regular expression.
4.0: June 24, 2008:
NF: The YankRing by default now captures all |text-objects| and
all motions (|motion.txt|) which Vim supports. Version 3.0 only
supported a subset of the basic motion commands.
NF: Prior to this version only predefined maps triggered the
capture of data into the yankring. These maps only supported
yanks and deletes. The YankRing now also supports
operator-pending mode, which allows a greater range of operations
to be automatically captured and added to the yankring.
Operating pending mode functionality requires Vim 7.2 or Vim 7.1
with patch #205. If using Vim 7.1 you can determine this with:
echo has("patch205")
NF: Prior to this version only yanks and deletes were registered
in the yankring. Changes are now also captured into the
yankring.
NF: The YankRing will also capture the system cliboard when focus is
returned to the vim window. This is useful if you copy text
between applications.
NF: The YankRing window always opened bottom horizontal. Now it
can be opened top or bottom and horizontal or vertically.
This can be controlled via variables in your .vimrc.
BF: The YankRing has an option to persist between instances
of Vim by storing the values in global variables within
the viminfo. This has led to some unusual ordering of
items in the ring from conflicts between instances.
This option has been turn off by default.
BF: Their was an issue with yanking using y$.
3.1: September 10, 2007:
NF: YRClear will now unlet all global variables it uses to store
the data if the persist storage is specified (the default).
Large values in the viminfo file could possibly affect other
applications.
3.0: September 7, 2007:
NF: Converted the YankRing to use the new Vim7's List object which
means it is no longer compatible with Vim6.
NF: By default the YankRing will now maintain the yankring's items
persistently by default. It does this via the |viminfo| file.
This means the contents of the YankRing rely on the internal
variables of only 1 Vim instance.
BF: YRToggle was not unmapping 'gp' and 'gP'.
BF: YRSearch prompted the user for a regex even if one was provided
on the command line.
BF: If g:yankring_manage_numbered_reg is enabled, the "." operator
did not correctly repeat the previous action (Pedro DeRose).
2.2: November 1, 2005:
NF: Added 'x' to the list of yankring_n_keys. This is very useful
in visual mode since it can delete a lot of characters.
2.2: October 19, 2005:
BF: If you pressed '?' to toggle the display of the help in the
YankRing window, the window would close. This also applied to
'a', which allowed you to toggle the autoclose feature.
2.1: October 11, 2005:
NF: Added the ability for the YankRing to override Vim's numbered
registers. Instead of the numbered registers holding the last
yanked value, and the 9 previous deletes, they will now reflect
the top 10 items in the yankring. This allows you to reference
them directly with "5p.
2.0: August 20, 2005:
NF: Much improved usability, the YankRing now has a "GUI" to service
the yankring. If YRShow or YRSearch is used, a split buffer is
opened which displays all the elements in the yankring. There
are a number of maps that allow you to interact with the
contents. The window can be positioned vertically or
horizontally as well as being sized all through options
specified in your vimrc.
NF: YRPop can now delete any items from the yankring, rather
that just from the top.
NF: YRSetTop has been removed, it is no longer required as the
internal representation of the YankRing has changed.
BF: If g:yankring_ignore_duplicate is set (which is the default)
you could get some unpredicable results when moving
backwards and forwards (<C-P> and <C-N>) through the
previous values.
1.7: June 10, 2005:
BF: The expression register support added in version 1.6 used
getreg('='), which has the side effect of executing the
expression register. Depending on what was in the register
this could have unusual results. Changed to use histget().
1.6: April 20, 2005:
NF: YRSearch is similar to YRGetElem. Given a regular expression
it will interactively display all the elements in the yankring
that match the regular expression. You can enter the number
of the element to paste it. If you have many elements within
the yankring, this can help you identify them more easily.
NF: Updated the default history size from 30 to 100, which is
partially the reason for the YRSearch command.
NF: By default it supports "gp" and "gP", in addition to "p" and "P".
NF: Added support for the expression register (:h quote=). Here
is an example of how it is used:
"="X"<CR>P
1.5: March 30, 2005:
NF: The YankRing now respects the cpoptions setting, if 'y' is
included and you press '.', the previous yank command is executed
and added to the yankring. You can also add this behaviour by
setting this in your |vimrc|: >
let g:yankring_dot_repeat_yank = 1
< NF: Duplicates will not be added to the YankRing by default. If
a duplicate is found, the 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 (1 is default)
< BF: Regression from version 1.4, the '.' operator may incorrectly
insert garbage.
1.4: March 28, 2005:
NF: YRToggle has been updated. If you toggle the YankRing off
(disable) the maps it creates are removed. Calling YRToggle
again will recreate the maps. This truly disables the yankring,
where the previous version attempted to do this via code.
BF: Using the '.' operator was not correctly replaying operations
that did not move text in some way (g~t_) changed the case
of the text but a '.' did not replay it.
BF: When replacing previously pasted text the YankRing did not
respect what key was used to paste the text originally.
All replaced items were pasted using 'p', even if you had
originally pasted the text with 'P'.
1.3: March 16, 2005:
BF: The '.' operator did not handle the <<, >> shift operator.
Pressing '.' would result in the previous YankRing operation
instead of repeating the shift.
1.2: March 14, 2005:
NF: Added support for '.' operator to repeat the last change.
NF: Changed YRGetElem to show the contents of the yankring
and allow you to choose which element you want pasted.
It is only interactive if you do not provide a parameter.
NF: Added 'ygg,dgg' default maps by extending the yankring_n_keys
variable.
1.1: March 09, 2005:
NF: Added support for the black hole register |quote_|.
NF: Custom Maps allows the user to more finely tune the yankring
maps to perform whatever action they require. This function,
YRRunAfterMaps(), is run automatically after the YankRing
creates it's default mappings. See |yankring-custom-maps|.
NF: Added some more default maps by extending the yankring_n_keys
variable. It now contains:
yy,dd,yw,dw,ye,de,yE,dE,yiw,diw,yaw,daw,y$,d$,Y,D,yG,dG
NOTE: You can easily extend these default mappings by
creating this global variable in your |vimrc|, you do not
have to wait for the plugin to be updated.
NF: Added support for Dr. Chips GetLatestVimScripts plugin.
BF: The check for g:yankring_n_keys was incorrect, so it was not
possible to override the default maps.
1.0: March 08, 2005:
NF: Initial release.
vim: ts=4 ft=help tw=78