80

I've recently found a vim plugin using something called <Plug>. For example there is a command <Plug>abc_def which I would like to execute.

I've tried everything like :<Plug>abc_def and similar. Nothing worked. And :help <Plug> gave no information.

However, I've been able to execute it by creating a mapping :map x <Plug>(unite_redraw). Then I can execute it by pressing x.

Now, is there any way to execute :<Plug>abc_def without creating a dummy mapping just to run it? The actual plugin I use is Unite.

Tarrasch
  • 10,199
  • 6
  • 41
  • 57

1 Answers1

115

<Plug> mappings are meant to be mapped and called via the map. A <Plug> map is a device to expose a clean interface of plugin actions to the user.

Example: Instead of mapping some key to some plugin function in the plugin's hard code, such as "map zz to the action 'center cursor aesthetically'":

nnoremap <expr> zz 'zz'.float2nr(winheight(0)*0.1).'<C-E>'

it is better to expose only a named <Plug> mapping from the plugin:

nnoremap <expr> <Plug>NiceCenterCursor 'zz'.float2nr(winheight(0)*0.1).'<C-E>'

that the user can then remap in their config, without having to copy and paste the "action":

nmap zz <Plug>NiceCenterCursor

This is then easy to override, reuse, plug into by the user.

<Plug> mappings are active only in the modes they have been defined for. To execute a <Plug> mapping that is defined for normal mode, you can do as with any normal command: use :normal (without the exclamation mark).

:execute "normal \<Plug>NiceCenterCursor"

Since <Plug> actually represents a special magic key, we need to use :normal together with :execute and escape the <Plug>.

The <Plug> mechanism is described in depth at :h 41.11. See also this article about this topic by a Vim master.

Michael Härtl
  • 8,428
  • 5
  • 35
  • 62
glts
  • 21,808
  • 12
  • 73
  • 94
  • 11
    Oh, so it's essential that the `nmap` is `nmap` and not `nnoremap`, because it will think of `NiceCenterCursor` as just another mapping. Correct? – Tarrasch Aug 31 '13 at 13:01
  • 9
    @Tarrasch Exactly, the right-hand side of the map must be remapped for this to work. Same with `:normal`: it's essential to use the (remapping) `:normal`, not the non-remapping `:normal!`. – glts Aug 31 '13 at 13:03
  • 1
    The specific part about `` is [here](http://vimdoc.sourceforge.net/htmldoc/usr_41.html#using-%3CPlug%3E). – jdhao Apr 02 '19 at 07:55
  • Thanks for your post! But, how is it compare with create a command? – roachsinai Jun 17 '21 at 01:43