*yankring.txt*      For Vim version 7.0.

Author:	        David Fishburn                             July 27, 2015
Version:        19.0

For instructions on installing this file, type
	:help add-local-help |add-local-help| inside Vim.

Homepage: http://vim.sourceforge.net/script.php?script_id=1234


==============================================================================
1. Contents                                      *yankring* *yankring-contents*

    1. Contents...............................: |yankring-contents|
    2. Description............................: |yankring-description|
    3. Configuration..........................: |yankring-configure|
       3.1 Global Variables...................: |yankring-globals|
       3.2 Default Keys.......................: |yankring-mappings|
       3.3 Customizing Maps...................: |yankring-custom-maps|
       3.4 Customizing Menus..................: |yankring-custom-menus|
    4. Using the YankRing Window..............: |yankring-window|
    5. Commands...............................: |yankring-commands|
       5.1  YRToggle..........................: |:YRToggle|
       5.2  YRClear...........................: |:YRClear|
       5.3  YRShow............................: |:YRShow|
       5.5  YRGetElem.........................: |:YRGetElem|
       5.6  YRGetMultiple.....................: |:YRGetMultiple|
       5.7  YRPush............................: |:YRPush|
       5.8  YRPop.............................: |:YRPop|
       5.9  YRYankCount.......................: |:YRYankCount|
       5.10 YRYankRange.......................: |:YRYankRange|
       5.11 YRDeleteRange.....................: |:YRDeleteRange|
       5.12 YRPaste...........................: |:YRPaste|
       5.13 YRReplace.........................: |:YRReplace|
       5.14 YRMapsCreate......................: |:YRMapsCreate|
       5.15 YRMapsDelete......................: |:YRMapsDelete|
       5.16 YRSearch..........................: |:YRSearch|
       5.17 YRCheckClipboard..................: |:YRCheckClipboard|
       5.18 YRRunAfterMaps....................: |:YRRunAfterMaps|
    6. Tutorial...............................: |yankring-tutorial|
       6.1  YRShow............................: |YRShow-example|
       6.2  YRReplace.........................: |YRReplace-example|
       6.3  YRPush............................: |YRPush-example|
       6.4  YRClear...........................: |YRClear-example|
       6.8  YRPop.............................: |YRPop-example|
       6.9  Visual modes......................: |yankring-visual-example|
       6.10 Using ranges......................: |YRYankRange-example|
       6.11 :global...........................: |global-example|
       6.12 YRSearch..........................: |YRSearch-example|
    7. History................................: |yankring-history|


==============================================================================
2. Description                                   *yankring-description*

Vim already maintains a list of numbered registers containing the last 9
deletes.  These previous deletes can be referenced using [register]p, so
"1p will paste the last delete, "2p the 2nd last delete.  For more
information see |quote_number|.

Vim does not provide any mechanism to reference previously yanked text.
In Emacs this feature is called the "kill ring".

The YankRing plugin allows the user to configure the number of yanked
and deleted text.  After text has been pasted, it can be replaced with
a previous value from the yankring.

As of version 3.0, the yankring's content will persist (by default)
between starting and stopping Vim.

The plugin can be toggled on and off, and supports:
   Ranges
   Registers
   Counts
   All visual modes
   All motions
   All text-objects

If you have any suggestions for the improvement of this plugin, see the
yankring.vim file for my email address.  Suggestions / bug reports are
always welcome.

For details on the changes between versions see |yankring-history|.


==============================================================================
3. Configuration                                 *yankring-configure*

The YankRing allows the user to choose which keys are to be assigned to
the various commands.  By default, the YankRing chose keys identical
with Vim's standard behaviour/keys.

3.1 Global Variables                             *yankring-globals*

You can customize the YankRing by setting various global variables in
your |.vimrc|.
>
    yankring_max_history
<       Default: 100
        Controls how many elements to save in the yankring. >
            let g:yankring_max_history = 100
    yankring_min_element_length
<       Default: 1
        If the yanked element has a length less than this value
        if will not be added to the YankRing.  This can be useful if
        you want to bypass single letter deletes by adding the
        following to your .vimrc: >
            let g:yankring_min_element_length = 2
    yankring_max_element_length
<       Default: 1048576 (1M)
        Will truncate a new entry to the specified maximum.  If
        g:yankring_max_element_length is set to 0, there is no limit. >
            let g:yankring_max_element_length = 4194304 " 4M
    yankring_max_display
<       Default: 500
        When the YankRing window is opened, each element is displayed on a
        separate line.  Since each yank could be very large, the display of
        the element is limited to the above default.  >
            let g:yankring_max_display = 70
    yankring_enabled
<       Default: 1
        If you do not want to YankRing enabled by default, set this
        variable in your |vimrc|. >
            let g:yankring_enabled = 0  " Disables the yankring
    yankring_persist
<       Default: 1
        If you have enabled the storing of global variables in the |viminfo|
        file, the YankRing will be default persist the contents of the ring
        between starting and stopping Vim.  To disable this feature: >
            let g:yankring_persist = 0
    yankring_share_between_instances
<       Default: 1
        By default, any instance of Vim will share the same yankring
        history file.  But if want each instance to have their own history
        you can set this option to 0.  Setting g:yankring_persist = 0 and
        g:yankring_share_between_instances = 0 will ensure no 2 instances
        of Vim share the same YankRing history AND the history is not
        remembered the next time Vim is started. >
            let g:yankring_share_between_instances = 0
    yankring_dot_repeat_yank
<       Default: Based on the Vim cpoption setting
        By default Vim will not repeat (using '.') yanking of text.  This can
        be controlled via the |'cpoptions'| setting.  The YankRing now respects
        the cpoptions setting, if 'y' is included and you press '.', the
        previous yank command is repeated and added to the yankring.
        You can also add this behaviour by setting this in your |vimrc|: >
            let g:yankring_dot_repeat_yank = 1
    yankring_ignore_duplicate
<       Default: 1
        Duplicates will not be added to the YankRing by default.  If a
        duplicate is found, that element will be moved to the top of the
        yankring.  This can be controlled by setting this in your |vimrc|: >
            let g:yankring_ignore_duplicate = 0
    yankring_map_dot
<       Default: 1
        If the '.' (repeat) command should be mapped by the yankring.  Since
        most of the normal commands yy,dd,dw,... are mapped by the yankring,
        if g:yankring_map_dot is false the . operator will not repeat these
        operations.  The YankRing tracks several of the internal Vim registers
        and decides whether an action was the result of the YankRing or an
        action outside of it.  If the previous action was a result of the
        yankring, it will be executed again.  If it was an action outside of
        the yankring, it asks Vim to repeat the command. >
            let g:yankring_map_dot = 1
    yankring_paste_using_g
<       Default: 1
        By default [p] and [P] are mapped to interact with the yankring.  This
        option controls whether [gp] and [gP] are also mapped.  Setting this
        option to 0 will not create these maps.  >
            let g:yankring_paste_using_g = 1
    yankring_window_use_separate
<       Default: 1
        This is a new feature as of the 2.0 release.  The YankRing now uses a
        separate split buffer to display the yankring.  There are many buffer
        specific maps that allow you to operate over the various elements from
        within the yankring.  Setting this option to 0, uses the 1.0
        interface. >
            let g:yankring_window_use_separate = 0
    yankring_window_auto_close
<       Default: 1
        By default once you choose an option in the YankRing buffer, the
        action is performed and the buffer window is closed, returning you to
        the original buffer.  This option can be toggled from within the
        YankRing buffer by pressing [a].  The YankRing buffer status line
        visually indicates when 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_record_insert
<       Default: 0
        If you want text you insert to be recorded in the YankRing you can
        enable this feature two ways.  From within the YankRing window you can
        press [i].  The YankRing buffer status line visually indicates when
        recording inserts is enabled or disabled.  To enable this option
        at Vim startup, put the following in your .vimrc: >
            let g:yankring_record_insert = 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: 8
        If using a horizontal split, this option controls how high to make
        the window.  >
            let g:yankring_window_height = 8
    yankring_window_width
<       Default: 30
        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.
        This can be a comma separated list, which is useful if your
        .vimrc is shared across different machines.  If multipe directories
        are specified, the first valid directory will be used.
        You can put the following in your |vimrc| >
            let g:yankring_history_dir = '$VIM'
    yankring_history_file
<       Default: 'yankring_history'
        The history filename prefix can be controlled by setting this
        variable.
        You can put the following in your |vimrc| >
            let g:yankring_history_file = 'my_yankring_history_file'
    yankring_clipboard_monitor
<       Default: 1
        When flipping between applications I find I often copy text
        and attempt to use it inside of Vim.  This is typically easy
        by simply using "+p, but there are times when I will repeatedly
        want to use the same text later on.  By default, the YankRing
        will detect when Vim regains focus and check if the clipboard
        has changed since it last checked.  If so, it will add the contents
        of the clipboard to the YankRing.  This is accomplished by the
        use of the FocusGained Vim event for the GUI Vim.  For console
        Vims, the FocusGained event does not fire, so additional logic
        is added to deal with it.  To disable this feature
        you can put the following in your |vimrc| >
            let g:yankring_clipboard_monitor = 0
    yankring_manual_clipboard_check
<       Default: 0
        If running in console mode, Vim's FocusGained event will not
        fire as we flip back and forth between windows.  This normally
        instructs the YankRing to check for updates to the system
        clipboard.  When this option is set, the YankRing will check
        the clipboard under many different circumstances:
            Adding a new entry to the YankRing
            Replacing a previous paste
            Showing the YankRing window
        If the YankRing is setup to check the clipboard and the
        GUI is not running, this option will be enabled by default.
        To disable this feature you can put the following in your |vimrc| >
            let g:yankring_manual_clipboard_check = 0
    yankring_paste_check_default_register
<       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_register = 0
    yankring_default_menu_mode
<       - Menus are useful for a number of reasons:
              See a list of available commands.
              Remember what the shortcut maps are.
              Have a floating menu when using the plugin a lot.
              Quick reference guide.
          There are four settings that will control the placement
          of the menu:
              "0": Turns the menu off.
              "1": Turns the 'Yankring' menu on with no menu shortcut.
              "2": Turns the 'Yankring 'menu on with <alt>-y as the shortcut.
              "3": Turns the 'Plugin -> YankRing' menu on with <alt>-y as
                   the shortcut.
          This option defaults to a value of 3 and can be changed
          by adding the following to your .vimrc: >
            :let  g:yankring_default_menu_mode = 3
    yankring_menu_root
<       - Can be used in conjuction with g:yankring_default_menu_mode = 3 but
          it also allows you to control the fullname and location of the
          YankRing menu.  To create the menu: 'MyPlugins -> YankRing' you
          can create the following variable: >
            :let  g:yankring_menu_root = 'MyPlugin.&YankRing'
    yankring_menu_priority
<       - Menus are created in a documented order by Vim (|menu-priority|).
          This option allows you to override the setting and shift the
          YankRing menu item to the left between the Edit and Tools menu. >
            :let  g:yankring_menu_priority = 30

<
3.2 Default Keys                                 *yankring-mappings*

You can choose to override the default keys by creating these global
variables in your |vimrc|.
>
    yankring_n_keys
<       n - normal mode
        Default Vim 7.2:
            'Y D x X'
        Default Vim 7.1 and below:
            'x yy dd yw dw ye de yE dE yiw diw yaw daw y$ d$ Y D yG dG ygg dgg'

        With the introduction of some new features in Vim 7.2 it is no longer
        necessary to list all cmds which the YankRing will act upon.
        The yankring_n_keys only lists actions which an omap cannot be used.
        Using the yankring_separator, the above list is parsed and
        individual mappings are created.  For each of the above normal
        commands the YankRing will include the text those commands
        acted upon.   There are many ways to accomplish the same result
        in Vim, if you do not see a common key stroke you regularly use
        simply add the following to your |vimrc| with the additional
        keys you wished mapped.  >
            let g:yankring_n_keys = 'Y D x X'
    yankring_o_keys
<       o - omap mode
        Default:
            Standard motions: 'b B w W e E d y $ G ;'
            Vim text objects: ' iw iW aw aW as is ap ip a] a[ i] i['
                              'a) a( ab i) i( ib a> a< i> i< at it '
                              'a} a{ aB i} i{ iB a" a'' a` i" i'' i`'

        As of Vim 7.2 omaps are used to capture changes to the registers
        in Vim.  All of the standard motion commands are captured.
        New to YankRing 5.0 all default Vim text objects are also
        captured.
        Using the yankring_separator, the above list is parsed and
        individual mappings are created.  For each of the above normal
        commands the YankRing will include the text those commands
        acted upon.   There are many ways to accomplish the same result
        in Vim, if you do not see a common key stroke you regularly use
        simply add the following to your |vimrc| with the additional
        keys you wished mapped.  >
            let g:yankring_o_keys = 'b B w W e E d y $ G ; iw iW aw aW'
    yankring_zap_keys
<       Default: 'f F t T / ?'
        omaps are enough for most operations except for f and t.
        These motions prompt the user for a character or string which
        they should act upon.  These must be treated as a special case
        in YankRing. >
            let g:yankring_zap_keys = 'f t'
    yankring_ignore_operator
<       Default: 'g~ gu gU ! = gq g? > < zf g@'
        There are certain motions which do not update any registers
        in Vim.  If the registers are not changed, there is nothing
        the YankRing can capture.  This list instructs the YankRing
        to ignore any action for these keys. >
            let g:yankring_ignore_operator = 'g~ gu gU'
    yankring_v_key
<       v - visual mode
        Default: y
        Yanks visually select text.   >
    yankring_del_v_key
<       n - normal mode
        Default: d
        The visually select text is included in the YankRing and deleted. >
    yankring_paste_n_bkey
<       n - normal mode
        b - before
        Default: P
        The default Vim paste key will retrieve from the yankring.  This
        will paste the text BEFORE the current position.
        There is a special check to see if the text in the default paste
        register is the same as what is in the current position of the
        yankring.  If it is not, we assume the user used some other
        mechanism to yank text (ie yt<character>).  If this is the case
        we paste the text in the default paste buffer.  Using <C-P> the
        text can be replaced with the current entry from the yankring.
        Since there are many ways to do things in Vim, this provides
        the best integration. >
    yankring_paste_n_akey
<       n - normal mode
        a - after
        Default: p
        The default Vim paste key will retrieve from the yankring.  This
        will paste the text AFTER the current position.
        There is a special check to see if the text in the default paste
        register is the same as what is in the current position of the
        yankring.  If it is not, we assume the user used some other
        mechanism to yank text (ie yt<character>).  If this is the case
        we paste the text in the default paste buffer.  Using <C-P> the
        text can be replaced with the current entry from the yankring.
        Since there are many ways to do things in Vim, this provides
        the best integration. >
    yankring_paste_v_key
<       n - normal mode
        Default: p
        This will replace the visually select text with the contents
        from the yankring.   See yankring_paste_n_akey for additional
        details.  >
    yankring_replace_n_pkey
<       n - normal mode
        Default: <C-P>
        If you do not want to open the YankRing window to choose your
        selection, then you can paste (as usual) then use a YankRing
        mapping to cycle through items in the YankRing.  This is especially
        useful if you know you recently used the text you are looking for.
        If you wish to cycle through the yankring, replacing the previously
        pasted text with the previous yanked text you can repeatedly press
        <C-P> (or whatever keystroke you choose to map it to).  This map
        moves backwards through the yankring, so you will retrieve your
        most recent yank.

        I prefer not to use <C-P> since I like using that key to cycle
        through all the matches in the QuickFix window.  You can add
        something similar to this in your |.vimrc| to get similar
        functionality.

        On Windows use the ALT-< character to move through the YankRing.
        To determine what character # these are go into insert mode
        in a new buffer.  Press CTRL-V then ALT and the < key.
        Leave insert mode, move the cursor onto the character
        and press ga.  This will display the decimal, hex and octal
        representation of the character.  In this case it is 172. >
            if has('win32')
                let g:yankring_replace_n_pkey = '<Char-172>'
                let g:yankring_replace_n_nkey = '<Char-174>'
                " Instead map these keys to moving through items in the quickfix window.
                nnoremap <C-P> :cp<cr>
                nnoremap <C-N> :cn<cr>
            endif
<       Other users have also stated that this will work: >
            let g:yankring_replace_n_pkey = '<m-p>'
            let g:yankring_replace_n_nkey = '<m-n>'
    yankring_replace_n_nkey
<       n - normal mode
        Default: <C-N>
        If you do not want to open the YankRing window to choose your
        selection, then you can paste (as usual) then use a YankRing
        mapping to cycle through items in the YankRing.  This is especially
        useful if you know you recently used the text you are looking for.
        If you wish to cycle through the yankring, replacing the previously
        pasted text with the next yanked text you can repeatedly press
        <C-N> (or whatever keystroke you choose to map it to).  This map
        moves forwards through the YankRing, so you will retrieve your
        most recent yank.

        I prefer not to use <C-N> since I like using that key to cycle
        through all the matches in the QuickFix window.  You can add
        something similar to this in your |.vimrc| to get similar
        functionality.

        On Windows use the ALT-> character to move through the YankRing.
        To determine what character # these are go into insert mode
        in a new buffer.  Press CTRL-V then ALT and the > key.
        Leave insert mode, move the cursor onto the character
        and press ga.  This will display the decimal, hex and octal
        representation of the character.  In this case it is 174. >
        if has('win32')
            let g:yankring_replace_n_pkey = '<Char-172>'
            let g:yankring_replace_n_nkey = '<Char-174>'
            " Instead map these keys to moving through items in the quickfix window.
            nnoremap <C-P> :cp<cr>
            nnoremap <C-N> :cn<cr>
        endif
<       Other users have also stated that this will work: >
            let g:yankring_replace_n_pkey = '<m-p>'
            let g:yankring_replace_n_nkey = '<m-n>'

3.3 Customizing Maps                             *yankring-custom-maps*

The YankRing plugin uses the yankring_n_keys global variable to create
a number of defaults maps.  The maps are of the form: >
    nnoremap Y  :<C-U>YRYankCount 'Y'<CR>
<
When capital Y is pressed, the YankRing will execute 'Y' and capture the
output from Vim.  But there are cases where you do not want the default
behaviour of Vim, since you have customized some of these maps.

In this case, I usually map Y to be |y$|, which makes it consistent with
the |D| and |C| operators.  The way yankring_n_keys works does not allow
me to customize this behaviour.  Since many people may like to customize
the behaviour of these maps the YankRing will check to see if a
function called YRRunAfterMaps() exists.  If it does, it will call
this function after it has created the maps.  So in my case, I created
the following function in my |vimrc|: >
    function! YRRunAfterMaps()
        nnoremap Y   :<C-U>YRYankCount 'y$'<CR>
    endfunction
<
You can do anything you need in this function.  >
        nnoremap Y   :<C-U>YRYankCount 'y$'<CR>
<
This line remaps Y (which the user presses) to the YRYankCount command.  The
YRYankCount tells Vim to execute y$ instead.

3.4 Customizing Menus                            *yankring-custom-menus*

There are several global variables which can be created in your .vimrc to
allow you to customize where and what is displayed for the YankRing menu.
Simply look up the following global variables: >
    yankring_default_menu_mode
    yankring_menu_root
    yankring_menu_priority


==============================================================================
4. Using the YankRing Window:                    *yankring-window*

This is a new feature as of the 2.0 release.  The YankRing uses a
separate split buffer to display the yankring.  There are many buffer
specific maps that allow you to operate over the various elements from
within the yankring.

To display the YankRing buffer you can issue the :YRShow command.  For
convenience you can map a key, <F11>, to this command: >
	:nnoremap <silent> <F11> :YRShow<CR>

Status line~
The first line in the YankRing window is the status line. >
    AutoClose=1;ClipboardMonitor=1;Cmds:[g]p,[g]P,1-9,d,r,s,a,c,u,q,<enter>,<space>;Help=?
<
Help=?, pressing [?] will toggle the display of available commands the
yankring window supports.  Pressing [?] again will remove the additional
items.

AutoClose=1 indicates the window will close when an action is performed
against elements within the yankring.  If you wish to perform multiple
yankring operations press [a] to toggle the auto close feature off.  Use the
commands below and when finished you can press [a] to toggle the option,
yankring_window_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 the option, yankring_clipboard_monitor, since it may not
be useful at times.

Inserts=0 indicates the YankRing will recorder newly inserted text
rather than just deletes and changes.  Pressing [i] toggles the option
yankring_record_insert.

YankRing window key list~
The following table lists the description of the keys that can be used
in the YankRing window.

  Key           Description~
  p             Puts text after the cursor.  In visual mode, all elements
                selected will be pasted.
  P             Puts text before the cursor.  In visual mode, all elements
                selected will be pasted.
  gp            Just like "p", but leave the cursor just after the new text.
  gP            Just like "P", but leave the cursor just after the new text.
  <CR>          Just like "p".
  <Enter>       Just like "p".
  <2-LeftMouse> Just like "p".  Normal mode only.
  1-9           Shortcut to paste the n'th number from the YankRing.
  d             Removes the element from the yankring.  In visual mode all
                elements selected will be removed.
  r             Just like "p", but in visual mode if many lines are selected
                it will paste these items in reverse order.
  s             Prompts you for a regex to search the YankRing and display
                only matching items.
  a             Toggles the g:yankring_window_auto_close setting.
  u             Updates the YankRing window.
  q             Closes the YankRing window.
  <Space>       Toggles the width of the vertical window by the
                g:yankring_window_increment setting.
  ?             Toggles the display of the help.


==============================================================================
5. Commands:                                     *yankring-commands*

The predefined mappings call some specific commands with special parameters.
If you are going to create additional maps, it is important you mirror
the same parameters.  Most of these commands have been made obsolete by
the YankRing window, since it incorporates the functionality below, but
through maps against a buffer, instead of commands.  This makes it much easier
to use.


5.1  YRToggle                                    *:YRToggle*
         Allows you to enable and disable the YankRing quickly.  This
         command will remove the default maps and recreate them.

         Examples: >
            :YRToggle    " Toggles it
            :YRToggle 1  " Enables it
            :YRToggle 0  " Disables it
<

5.2  YRClear                                     *:YRClear*
         Clears all elements from the yankring.
         See also |YRClear-example|.


5.3  YRShow                                      *:YRShow*
         Similar to |:register|, will display all the entries in the yankring.
         The element at the top will be the next element pasted from the
         yankring.

         Examples:  >
            :YRShow     " Shows all entries in the yankring

            --- YankRing ---
            Elem  Content
            1     five^@
            2     four^@
            3     three^@
            4     two^@
            5     one^@
<

5.5  YRGetElem                                   *:YRGetElem*
        This command has two modes.  If no parameters are provided, it
        becomes interactive.  It uses YRShow to display the list and
        allows you to choose which element to paste.  If a parameter
        is supplied it will paste that element from the yankring.  If the
        number specified is outside of the YankRing an error is returned.
        You may want to create a separate mapping for this call. >
            nnoremap <silent> <Leader>yr :YRGetElem<CR>
<       See also |YRSearch|.

        Examples:
            Assume there are 10 elements in the YankRing and element 6 is
            at the top of the ring. >
            :YRGetElem     " Interactive mode, you choose from a list
            :YRGetElem 4   " Will paste element 5.
            :YRGetElem 12  " Will paste element 6.
            :YRGetElem 99  " Error, invalid choice is reported
            :YRGetElem 0   " Error, invalid choice is reported


5.6  YRGetMultiple                               *:YRGetMultiple*
        Will paste many elements from the YankRing in one command.
        If the number specified is 1 or less, it is assumed you want
        just the current element pasted.  If the number specified is
        greater than or equal to the number of elements in the yankring,
        it is assumed you want all elements pasted.  If a ! is included
        as part of the command, paste the items in reverse order.
        See the |yankring-tutorial| for more examples.

        Examples:
            Assume there are 10 elements in the YankRing. >
            :YRGetMultiple  4   " Will paste elements 1,2,3,4
            :YRGetMultiple! 4   " Will paste elements 4,3,2,1
            :YRGetMultiple      " Will paste element  1
            :YRGetMultiple  12  " Will paste elements 1,2,...,10
            :YRGetMultiple  99  " Will paste elements 1,2,...,10
            :YRGetMultiple  0   " Will paste element  1


5.7  YRPush                                      *:YRPush*
         Allows the user to "push" additional entries into the yankring.
         If you yanked text via a key mapping which does not use the
         YankRing (or there is text on the clipboard) you can use this
         command to add the text to the yankring.

         Examples: >
            :YRPush      " Push the "  register's contents
            :YRPush '*'  " Push the "* register's contents (clipboard)
            :YRPush '+'  " Push the "+ register's contents (clipboard)
            :YRPush 'a'  " Push the "a register's contents
<           See also |YRPush-example|.


5.8  YRPop                                       *:YRPop*
         Allows you to pop any elements from the yankring.  If no parameters
         are provided, the 1st element is removed from the yankring.  The
         command optionally takes a second parameter to specify how many
         elements to pop.  The default value is 1.

         Examples: >
            :YRPop      " Removes the highest numbered element from the
                          yankring
            :YRPop 3    " Removes the 3rd element from the yankring
            :YRPop 3,5  " Removes 5 elements from the YankRing beginning
                          at element 3
<           See also |YRPop-example|.


5.9  YRYankCount                                 *:YRYankCount*
         This command has the most mappings created for it.  If you are
         in normal mode and you are not specifying a range, this command
         will add the text to the yankring.

         The goal of this command is to allow the YankRing to be integrated
         as seamlessly as possible with Vim.  So it supports counts and
         registers.  If you create a mapping to it, you must pass as a
         parameter the action you want Vim to perform.  You could do the
         following: >
            nnoremap \test  :<C-U>YRYankCount 'dd'<CR>
<        This map is executed when you hit the '\test' keystrokes, but
         it will actually delete the current line and add it to the
         yankring.

         The following are the default mappings: >
            nnoremap yy  :<C-U>YRYankCount 'yy'<CR>
            nnoremap dd  :<C-U>YRYankCount 'dd'<CR>
            nnoremap yw  :<C-U>YRYankCount 'yw'<CR>
            nnoremap dw  :<C-U>YRYankCount 'dw'<CR>
            nnoremap ye  :<C-U>YRYankCount 'ye'<CR>
            nnoremap de  :<C-U>YRYankCount 'de'<CR>
            nnoremap yiw :<C-U>YRYankCount 'yiw'<CR>
            nnoremap diw :<C-U>YRYankCount 'diw'<CR>
            nnoremap Y   :<C-U>YRYankCount 'Y'<CR>
            nnoremap D   :<C-U>YRYankCount 'D'<CR>
            nnoremap y$  :<C-U>YRYankCount 'y$'<CR>
            nnoremap d$  :<C-U>YRYankCount 'd$'<CR>
            nnoremap yG  :<C-U>YRYankCount 'yG'<CR>
            nnoremap dG  :<C-U>YRYankCount 'dG'<CR>
<
         Examples:
                yy - Adds the current line to the yankring.
                dd - Adds the current line to the YankRing and deletes it.
               5yw - Adds 5 words to the yankring.
              "ade - Deletes the word, and puts it into both the yankring
                     and the "a register.
            10"zyy - Places 10 lines into both the YankRing and the "z
                     register.
            See also |yankring-tutorial|.


5.10 YRYankRange                                 *:YRYankRange*
         This command by default is only called in visual mode.  All
         visual modes (|characterwise-visual|, |linewise-visual|,
         |blockwise-visual|) are supported.  Any visually selected text
         is added to the yankring.  You can also call this command
         directly using a range.

         Examples:
            Visual mode
            -----------
            Press v (to enter visual mode), highlight want you want,
            press y (to yank the selected area).
            Repeat using V and Control-V.

            Normal mode
            ----------- >
            :5,20YRYankRange   " Will yank lines 5-20 into the yankring
            :5,20YRDeleteRange " Will delete lines 5-20 and add them to
                                 the yankring
<           See also |YRYankRange-example|.


5.11 YRDeleteRange                               *:YRDeleteRange*
         This command is identical to YRYankRange, except the range is
         also deleted.


5.12 YRPaste                                     *:YRPaste*
        This command will paste elements from the yankring.  By default it has
        been mapped to p and P to match Vim's native key strokes.  The text
        pasted is exactly what was yanked, including newline characters and
        blockwise-visual mode behaviours.  It supports counts and registers.

        Examples:
            p   " Paste the current element from the YankRing after the cursor
            P   " Paste the current element from the YankRing before the cursor
           5p   " Paste the current element from the YankRing after the cursor
                  5 times
          "ap   " Ignore the YankRing and paste the contents of register "a
         5"ap   " Ignore the YankRing and paste the contents of register "a
                  5 times
            See also |yankring-tutorial|.


5.13 YRReplace                                   *:YRReplace*
        The purpose of the YankRing is to gain access to previously yanked
        (or deleted) elements.  This command will replace the previous
        paste with a different entry from the yankring.
        By default, I choose <C-P> (P for previous) to replace the last paste
        while moving backwards through the yankring.  <C-N> (N for next)
        replaces the last paste while moving forward through the yankring.

        Examples:
            See the |yankring-tutorial| for examples.

        On the Windows platform, I use ALT-< and ALT-> to move back and
        forwards through the yankring instead of C-P and C-N. ALT-< is
        actually ALT-, since I do not press the Shift key to get the <.

        To do this, I added the following to my .vimrc:
            " Do not map the default <C-N> and <C-P> keys
            " These two characters are the ALT-< and ALT->.
            " To determine what character # these are go into insert mode
            " in a new buffer.  Press CTRL-V then ALT and the > key.
            " Leave insert mode, move the cursor onto the character
            " and press ga.  This will display the decimal, hex and octal
            " representation of the character.  In this case, they are
            " 172 and 174.
            if has('win32')
                let g:yankring_replace_n_pkey = '<Char-172>'
                let g:yankring_replace_n_nkey = '<Char-174>'
            endif

5.14 YRMapsCreate                                *:YRMapsCreate*
        This public function is responsible for creating the maps which
        enable the yankring.  This function is called by the YRToggle
        command.


5.15 YRMapsDelete                                *:YRMapsDelete*
        This public function removes the YankRing maps and disables
        the yankring.  This function is called by the YRToggle command.


5.16 YRSearch                                    *:YRSearch*
        This command is similar to |YRGetElem|.  The command takes
        one parameter which is a regular expression.  Similar to
        YRGetElem, it will display all items in the YankRing that match
        the regular expression.  It is also interactive, and will
        prompt you to enter which match you wish pasted.
        See also |YRSearch-example|.

5.17 YRCheckClipboard                            *:YRCheckClipboard*
        Normally the GUI Vims will automatically (via autocmds)
        check for changes to the system clipboard and add any new
        changes to the YankRing.  Most console Vim's do not fire
        the required autocmds.  This command will perform the check
        manually.

5.18 YRRunAfterMaps                              *:YRRunAfterMaps*
        See the following section |yankring-custom-maps|.


==============================================================================
6. Tutorial                                      *yankring-tutorial*

To understand how to use the yankring, the following example will
demonstrate the various features.  Assume you have created the following
mapping: >
    nnoremap <silent> <F11> :YRShow<CR>
<
    Assume we have this buffer: >
        one
        two
        three
        four
        five
<                                                *YRShow-example*
     Now yank (yy) each line separately starting at line 1.
     Display the contents of the YankRing by executing the command
     YRShow, or pressing <F11>.  The contents of the YankRing is
     displayed in a new buffer.  The size, location and type of buffer
     is configurable via various options.  See section 3 for more details. >
        :YRShow or F11
            --- YankRing ---
            Elem  Content
            1     five^@
            2     four^@
            3     three^@
            4     two^@
            5     one^@
<    Since we yanked the text starting at line 1 and finishing at
     line 5, the most current YankRing element is the last one, the
     contents of line 5.  "five^@" is displayed, the "^@" is a
     newline character (since we issued a "yy").

                                                 *yankring-window-example*
     At this point, you have two options.  You can choose which element
     from the YankRing you wish to paste and press <CR> or 'p' or 'P'
     and a variety of other options, see |yankring-window|. After pressing
     the key, the YankRing window will close (default behaviour).  Pressing
     '?' will display additional help for the commands that are active within
     the YankRing window.  Pressing '?' will toggle the help.

     You do not need to interact with the YankRing using the YankRing window.
     Using the window makes many tasks must easier, but for speed using some
     of the other maps can be preferable 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.

    As a short cut, when using the YankRing window, you can press the numbers
    1-9 to paste that item directly and close the YankRing window.  This can
    be faster than navigating to the correct line number and pressing 'p'.

                                                 *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*

  19.0: July 27, 2015
         NF: Updated documentation displayed in the YankRing window when
             pressing ? to explain the Insert=0 status (Oskar Kvist).

  18.0: September 24, 2013
         NF: Handle the @: command (Lingnan Dai).
         NF: Added new global option to specify the YankRing buffer name,
             g:yankring_buffer_name (Štefan Sakalík).
         BF: Did not properly highlight new commands in the YankRing
             window (Thilo Six).

  17.0: April 28, 2013
         NF: The yankring_history_dir option can now take a comma separated
             list.  First valid directory found will be used (Alex Bel).
         NF: YankRing can now monitor inserted text and place it in the ring.
             This is disabled by default, but can be enabled either through
             the YankRing window or via your .vimrc using the new option:
             g:yankring_record_insert = 1 (Alexandre Viau).
         BF: When g:yankring_persist = 0, the YankRing was still reading
             and writing to the yankring file (Vladimir Marek).
         BF: The YankRing menu entry, "Replace with Next", was performing
             the "Replace with Previous" action (Thilo Six).

  16.0: January 20, 2013
         BF: YankRing could report "YR: A register cannot be specified in
             replace mode" when using clipboard = unnamed or unnamedplus.
             This can often happen when fetching previous values from
             the YankRing (i.e. <C-N> or <C-P>).

  15.0: January 2, 2013
         NF: Automatically turn off relativenumber for the YankRing
             window (Emma Tramp).
         NF: The YankRing window supports 1-9 to choose to paste those
             items for quicker access to the top 9 items.
         BF: When re-executing a macro using @<letter> and the macro
             used f, F, t, T, a "Press ENTER to continue" prompt
             was displayed (Greg Sexton).
         BF: Some documentation updates and script tweaks (Dominique Pellé).
         BF: The 0 register was updated during delete operations
             (Christian Brabandt).
         BF: When running a macro (@a), pressing @ displays a YankRing prompt
             (YR:Enter character:) to choose which macro name to run.  This
             prompt was displayed twice leading to a "Press ENTER or type
             command to continue" Vim message.  This change suppresses
             the "Press ENTER" message (Greg Sexton).
         BF: The YankRing prevented you from re-running the last macro
             using @@.
         BF: YRToggle (to disable / enable the YankRing) did not
             unmap @.
         BF: When prompted for a macro to run, if an invalid value was
             provided, Vim could report "E354: Invalid register name".
         BF: When using a Vim instance with < 80 columns and using a
             horizontal YankRing window after opening and closing the
             YankRing window the Vim window did not shrink back to
             its original size (Eric Weir).
         BF: Updated documented values of yankring_window_height and
             yankring_window_width (Paul).
         BF: It was not possible to paste from the * register if the
             clipboard option contains unnamedplus before unnamed
             (Marcin Szamotulski).

  14.0: April 1, 2012
         NF: The YankRing window supports 1-9 to choose to paste those
             items for quicker access to the top 9 items.
         NF: The YankRing now maps the @ key to run macros.  Not all actions
             performed during the macro are recorded by the YankRing
             as a number of items had to be unmapped to support the replay
             of actions which can prompt the user for input (i.e. t and f)
             (Asis Hallab).
         BF: When flipping between applications the system clipboard
             was not added to the YankRing in all cases.
         BF: The YankRing could report E121: Undefined variable:
             g:yankring_manual_clipboard_check (Thilo Six).
         BF: The YankRing could report: E132: Function call depth is higher
             than 'maxfuncdepth'.  When executing a YRClear or YRPop or
             when flipping between applications (Marcin Szamotulski).
         BF: Strange behaviour when opening the YankRing with
             :e [YankRing] instead of :YRShow (Marcin Szamotulski).

  13.0: February 5, 2012
         NF: [p, ]p, [P, ]P are now supported within the YankRing
             window (Alexandre Provencio).
         NF: When using the console version of Vim the yankring was not
             detecting the "+ register automatically as the FocusGained
             event does not fire in console mode.  When new elements are
             added or the YankRing is shown the clipboard will be
             checked for new values (Giuseppe Rota).
         NF: Added a new option, g:yankring_manual_clipboard_check which
             when enabled will manually check for clipboard changes at
             certain times within the YankRing.  This option is not used
             if the GUI is running as the FocusGained will perform checks
             at appropriate times (Erik Westrup).
         BF: With clipboard=unnamed replacing the previous paste with a
             different value from the YankRing did not work in all cases
             (Chris Lott).
         BF: Under certain conditions the YankRing would still check
             the system clipboard even if g:yankring_clipboard_monitor == 0.
             This can lead to delays when attempting to access the
             clipboard when running in console mode.  Starting Vim with
             the -X switch removes the delay (Erik Westrup).
         BF: Incorrect syntax setting cpoptions (Thilo Six).

  12.0: October 15, 2011
         NF: A console Vim does not necessarily react to a FocusGained event
             which means as you switch Focus back and forth between a
             console Vim, the YankRing's feature to automatically gather
             changes to the system clipboard is not triggered.  Now special
             processing takes place in various spots when you are not running
             Vim with a GUI, to check for changes to the clipboard.  Those
             already running a GUI Vim, are unaffected by this change
             (Giuseppe Rota).
         NF: New command, YRCheckClipboard, which allows you to force
             the YankRing to check the system clipboard and if the
             value is not present already in the YankRing, it will add it.
             This is typically done automatically, but certain console
             Vim's do not receive the necessary events for automation.
         BF: Some additional changes were required for the "unnamedplus"
             support.
         BF: YRGetMultiple reported an error, though typically you would
             use YRShow to paste the items.

  12.0: September 16, 2011
         NF: Added support for the clipboard option "unnamedplus" which was
             added after 7.3 (Hong Xu).
         NF: When displaying the YankRing using YRShow, a new command "R"
             has been added to display all of Vim's registers [0-9a-z].
         BF: YRMapsDelete did not remove the normal mode @ map, which
             interferes with recorded macros (Philippe Vaucher).

  11.0: August 09, 2010
         NF: Documented the global variables to customize the location
             of the YankRing menu.
         NF: The YankRing menu now shows the maps used for the default
             actions to help learn them more easily.
         NF: Added g:yankring_menu_root and g:yankring_menu_priority
             (David Barsam).
         NF: Added a warning indicating a stored value has been truncated
             based on g:yankring_max_element_length and a new option to
             suppress this warning, g:yankring_warn_on_truncate (Hans-Günter).
         BF: The YRAfterMaps() function (if it exists) was not re-run if
             YRToggle was used to disable and enable the YankRing.
         BF: Multibyte strings may not have been pasted correctly (Dr. Chip).
         BF: When pasting a string of 1111's, and additional -1 could also
             be included in the output.

  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 clipboard 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 turned 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
