*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 [] will increase the size of the window by this number of columns. Pressing [] 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). If this is the case we paste the text in the default paste buffer. Using 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). If this is the case we paste the text in the default paste buffer. Using 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: 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 (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 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 = '' let g:yankring_replace_n_nkey = '' " Instead map these keys to moving through items in the quickfix window. nnoremap :cp nnoremap :cn endif < Other users have also stated that this will work: > let g:yankring_replace_n_pkey = '' let g:yankring_replace_n_nkey = '' yankring_replace_n_nkey < n - normal mode Default: 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 (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 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 = '' let g:yankring_replace_n_nkey = '' " Instead map these keys to moving through items in the quickfix window. nnoremap :cp nnoremap :cn endif < Other users have also stated that this will work: > let g:yankring_replace_n_pkey = '' let g:yankring_replace_n_nkey = '' 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 :YRYankCount 'Y' < 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 :YRYankCount 'y$' endfunction < You can do anything you need in this function. > nnoremap Y :YRYankCount 'y$' < 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, , to this command: > :nnoremap :YRShow 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,,;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. Just like "p". 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. 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 yr :YRGetElem < 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 :YRYankCount 'dd' < 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 :YRYankCount 'yy' nnoremap dd :YRYankCount 'dd' nnoremap yw :YRYankCount 'yw' nnoremap dw :YRYankCount 'dw' nnoremap ye :YRYankCount 'ye' nnoremap de :YRYankCount 'de' nnoremap yiw :YRYankCount 'yiw' nnoremap diw :YRYankCount 'diw' nnoremap Y :YRYankCount 'Y' nnoremap D :YRYankCount 'D' nnoremap y$ :YRYankCount 'y$' nnoremap d$ :YRYankCount 'd$' nnoremap yG :YRYankCount 'yG' nnoremap dG :YRYankCount 'dG' < 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 (P for previous) to replace the last paste while moving backwards through the yankring. (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 :YRShow < 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 . 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 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. 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. 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 the buffer results in: > one two three four five four < Now press 2. This would be the same as pressing two times in a row. This results in: > one two three four five two < Now press 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 . 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 < 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 or 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 and 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 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 ( and ) 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"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