neovim/runtime/doc/provider.txt

*provider.txt*		Nvim


		 NVIM REFERENCE MANUAL    by Thiago de Arruda


Providers					*provider*

Nvim delegates some features to dynamic "providers". This document describes
the providers and how to install them.
						*E319*
Use of a feature requiring a missing provider is an error: >

    E319: No "foo" provider found. Run ":checkhealth vim.provider"

Run the |:checkhealth| command, and review the sections below.

				      Type |gO| to see the table of contents.

==============================================================================
Python integration				*provider-python*

Nvim supports Python |remote-plugin|s and the Vim legacy |python3| and
|pythonx| interfaces (which are implemented as remote-plugins).

Note: Only the Vim 7.3 legacy interface is supported, not later features such
as |python-bindeval| (Vim 7.4); use the Nvim API instead. Python 2 is not
supported.


PYTHON QUICKSTART ~

To use Python plugins, you need the "pynvim" module. Run |:checkhealth| to see
if you already have it (some package managers install the module with Nvim
itself).

For Python 3 plugins:
1. Make sure Python 3.9+ is available in your $PATH.
2. Install either uv (https://docs.astral.sh/uv/) or pipx
   (https://pipx.pypa.io/stable/).
3. Install the module: >bash
   uv tool install --upgrade pynvim
   # or:
   pipx install --upgrade pynvim

The `--upgrade` flag ensures that you get the latest version even if
a previous version was already installed.

See also |python-virtualenv|.

PYTHON PROVIDER CONFIGURATION ~
						*g:python3_host_prog*
Command to start Python 3 (executable, not directory). Setting this makes
startup faster. Useful for working with virtualenvs. Must be set before any
check for has("python3").  >vim
    let g:python3_host_prog = '/path/to/python3'
<
						*g:loaded_python3_provider*
To disable Python 3 support: >vim
    let g:loaded_python3_provider = 0


PYTHON VIRTUALENVS ~
						*python-virtualenv*
Using pynvim 0.6.0+ installed via uv or pipx, Nvim will automatically detect
pynvim even if other Python virtual environments are activated (technical
note: via the "pynvim-python" global python tool).  For older pynvim (or older
Neovim), where detection involved finding the first Python interpreter and
checking if it could import pynvim, automatic detection would fail when
another virtual environment is active.  Upgrading to the latest pynvim is the
recommended solution to this; but if that's not an option, then you can set
the variable |g:python3_host_prog| in `init.vim` to point to the full path to
the Python interpreter where `pynvim` is installed, e.g.: >vim

  let g:python3_host_prog = '/path/to/pynvim-venv/bin/python'
<
See also: https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim

==============================================================================
Ruby integration			      *provider-ruby*

Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface
(which is itself implemented as a Nvim remote-plugin).


RUBY QUICKSTART ~

To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >bash
    gem install neovim

Run |:checkhealth| to see if your system is up-to-date.


RUBY PROVIDER CONFIGURATION ~
						*g:loaded_ruby_provider*
To disable Ruby support: >vim
    let g:loaded_ruby_provider = 0
<
						*g:ruby_host_prog*
Command to start the Ruby host. By default this is "neovim-ruby-host". With
project-local Ruby versions (via tools like RVM or rbenv) setting this can
avoid the need to install the "neovim" gem in every project.

To use an absolute path (e.g. to an rbenv installation): >vim
    let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host'

To use the RVM "system" Ruby installation: >vim
    let g:ruby_host_prog = 'rvm system do neovim-ruby-host'

==============================================================================
Perl integration				*provider-perl*

Nvim supports Perl |remote-plugin|s on Unix platforms. Support for polling STDIN
on MS-Windows is currently lacking from all known event loop implementations.
The Vim legacy |perl-vim| interface is also supported (which is itself
implemented as a Nvim remote-plugin).
https://github.com/jacquesg/p5-Neovim-Ext

Note: Only perl versions from 5.22 onward are supported.

PERL QUICKSTART~

To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package: >bash
    cpanm -n Neovim::Ext

Run |:checkhealth| to see if your system is up-to-date.


PERL PROVIDER CONFIGURATION~
						*g:loaded_perl_provider*
To disable Perl support: >vim
    :let g:loaded_perl_provider = 0
<
						*g:perl_host_prog*
Command to start the Perl executable. Must be set before any
check for has("perl").  >vim
    let g:perl_host_prog = '/path/to/perl'
<
==============================================================================
Node.js integration				*provider-nodejs*

Nvim supports Node.js |remote-plugin|s.
https://github.com/neovim/node-client/


NODEJS QUICKSTART~

To use javascript remote-plugins with Nvim, install the "neovim" npm package: >bash
    npm install -g neovim

Run |:checkhealth| to see if your system is up-to-date.


NODEJS PROVIDER CONFIGURATION~
						*g:loaded_node_provider*
To disable Node.js support: >vim
    :let g:loaded_node_provider = 0
<
						*g:node_host_prog*
Command to start the Node.js host. Setting this makes startup faster.

By default, Nvim searches for "neovim-node-host" using "npm root -g", which
can be slow. To avoid this, set g:node_host_prog to the host path: >vim
    let g:node_host_prog = '/usr/local/bin/neovim-node-host'
<
==============================================================================
Clipboard integration			      *provider-clipboard* *clipboard*

Nvim has no direct connection to the system clipboard. Instead it depends on
a |provider| which transparently uses shell commands to communicate with the
system clipboard or any other clipboard "backend".

To ALWAYS use the clipboard for ALL operations (instead of interacting with
the "+" and/or "*" registers explicitly): >vim
    set clipboard+=unnamedplus

See 'clipboard' for details and options.

							      *clipboard-tool*
The presence of a working clipboard tool implicitly enables the "+" and "*"
registers. Nvim supports these clipboard tools, in order of priority:

- |g:clipboard| : User override (if set to a dict or any string "name" below;
  e.g. `g:clipboard="tmux"` forces tmux clipboard and skips auto-detection).
- "pbcopy"    : pbcopy, pbpaste (macOS)
- "wl-copy"   : wl-copy, wl-paste (if $WAYLAND_DISPLAY is set)
- "wayclip"   : waycopy, waypaste (if $WAYLAND_DISPLAY is set)
- "xsel"      : xsel (if $DISPLAY is set)
- "xclip"     : xclip (if $DISPLAY is set)
- "lemonade"  : lemonade (for SSH) https://github.com/pocke/lemonade
- "doitclient": doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/
- "win32yank" : *win32yank* (Windows)
- "putclip"   : putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html
- "clip"      : clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip
- "termux"    : termux (via termux-clipboard-set, termux-clipboard-set)
- "tmux"      : tmux (if $TMUX is set)
- "osc52"     : |clipboard-osc52| (if supported by your terminal)

								 *g:clipboard*
To configure a custom clipboard tool, set `g:clipboard` to a string name (from
the above |clipboard-tool| list), or dict (to explicitly specify the shell
commands or |lambda| functions).

If "cache_enabled" is |TRUE| then when a selection is copied Nvim will cache
the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied.

The "copy" function stores a list of lines and the register type. The "paste"
function returns the clipboard as a `[lines, regtype]` list, where `lines` is
a list of lines and `regtype` is a register type conforming to |setreg()|.

Example: set to "osc52" to force OSC52, skipping auto-detection of terminal
support: >vim

    let g:clipboard = 'osc52'

Example: set to "wayclip" to force waycopy/waypaste: >vim

    let g:clipboard = 'wayclip'

Example: set to a dict which integrates the tmux clipboard: >vim

    let g:clipboard = {
      \   'name': 'myClipboard',
      \   'copy': {
      \      '+': ['tmux', 'load-buffer', '-'],
      \      '*': ['tmux', 'load-buffer', '-'],
      \    },
      \   'paste': {
      \      '+': ['tmux', 'save-buffer', '-'],
      \      '*': ['tmux', 'save-buffer', '-'],
      \   },
      \   'cache_enabled': 1,
      \ }


Example: set to a dict which uses g:foo as a fake clipboard: >vim

    let g:clipboard = {
      \   'name': 'myClipboard',
      \   'copy': {
      \      '+': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
      \      '*': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
      \    },
      \   'paste': {
      \      '+': {-> get(g:, 'foo', [])},
      \      '*': {-> get(g:, 'foo', [])},
      \   },
      \ }
<
							      *clipboard-wsl*
For Windows WSL, try this g:clipboard definition:
>vim
    let g:clipboard = {
      \   'name': 'WslClipboard',
      \   'copy': {
      \      '+': 'clip.exe',
      \      '*': 'clip.exe',
      \    },
      \   'paste': {
      \      '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
      \      '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
      \   },
      \   'cache_enabled': 0,
      \ }
<
							    *clipboard-osc52*
Nvim bundles a clipboard provider that allows copying to the system clipboard
using OSC 52, an "Operating System Command" control-sequence that causes the
terminal emulator to write to or read from the system clipboard.

When Nvim is running in the |TUI|, it automatically detects host terminal
support for OSC 52. If successful, then Nvim will use OSC 52 for copying and
pasting if no other |clipboard-tool| is found and when 'clipboard' is unset.
NOTE: Using a terminal multiplexer (e.g. tmux) may inhibit automatic OSC 52
support detection.

							*g:termfeatures*
To disable the automatic detection, set the "osc52" key of |g:termfeatures| to
false early in your |config|. Example: >lua
	local termfeatures = vim.g.termfeatures or {}
	termfeatures.osc52 = false
	vim.g.termfeatures = termfeatures
<
To force Nvim to use the OSC 52 provider you can set |g:clipboard|: >lua

    vim.g.clipboard = 'osc52'

Which is equivalent to: >lua
    vim.g.clipboard = {
      name = 'OSC 52',
      copy = {
        ['+'] = require('vim.ui.clipboard.osc52').copy('+'),
        ['*'] = require('vim.ui.clipboard.osc52').copy('*'),
      },
      paste = {
        ['+'] = require('vim.ui.clipboard.osc52').paste('+'),
        ['*'] = require('vim.ui.clipboard.osc52').paste('*'),
      },
    }
<
Note: not all terminal emulators support reading from the system clipboard
(and even for those that do, users should be aware of the security
implications), so using OSC 52 for pasting may not be possible (and not
necessary, because you can |paste| instead using your system paste function).
Users may need to configure their terminal emulator to allow reading from the
clipboard.
<
==============================================================================
Paste							*provider-paste* *paste*

"Paste" is a separate concept from |clipboard|: paste means "dump a bunch of
text to the editor", whereas clipboard provides features like |quote+| to get
and set the OS clipboard directly.  For example, middle-click or CTRL-SHIFT-v
(macOS: CMD-v) in your terminal is "paste", not "clipboard": the terminal
application (Nvim) just gets a stream of text, it does not interact with the
clipboard directly.

							*bracketed-paste-mode*
Pasting in the |TUI| depends on the "bracketed paste" terminal capability,
which allows terminal applications to distinguish between user input and
pasted text.  https://cirw.in/blog/bracketed-paste
This works automatically if your terminal supports it.

							*ui-paste*
GUIs can paste by calling |nvim_paste()|.

PASTE BEHAVIOR ~

Paste inserts text after the cursor.  Lines break at <NL>, <CR>, and <CR><NL>.
When pasting a huge amount of text, screen-updates are throttled and the
message area shows a "..." pulse.

In cmdline-mode only the first line is pasted, to avoid accidentally executing
many commands.  Use the |cmdline-window| if you really want to paste multiple
lines to the cmdline.

You can implement a custom paste handler by redefining |vim.paste()|.
Example: >lua

  vim.paste = (function(lines, phase)
    vim.api.nvim_put(lines, 'c', true, true)
  end)

==============================================================================
X11 selection mechanism			      *clipboard-x11* *x11-selection*

X11 clipboard providers store text in "selections". Selections are owned by an
application, so when the application gets closed, the selection text is lost.
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed to another application when that other application
requests them (e.g., upon a paste).

				*primary-selection* *quotestar* *quoteplus* *quote+*

There are three documented X11 selections: PRIMARY, SECONDARY, and CLIPBOARD.
CLIPBOARD is typically used in X11 applications for copy/paste operations
(CTRL-c/CTRL-v), while PRIMARY is used for the last selected text, which is
generally inserted with the middle mouse button.

Nvim's X11 clipboard providers only use the PRIMARY and CLIPBOARD selections,
for the "*" and "+" registers, respectively.

==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl: