mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 11:28:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clipboard, eval #33328

Browse Source
This commit is contained in:
Justin M. Keyes
2025-04-12 10:56:28 -07:00
committed by GitHub
parent b8e5fd51fd
commit 7384983721
7 changed files with 143 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
runtime/doc/builtin.txt generated
View File

@@ -11972,14 +11972,13 @@ windowsversion() *windowsversion()*
(`string`) (`string`)
winheight({nr}) *winheight()* winheight({nr}) *winheight()*
The result is a Number, which is the height of window {nr}. Gets the height of |window-ID| {nr} (zero for "current
{nr} can be the window number or the |window-ID|. window"), excluding any 'winbar' and 'statusline'. Returns -1
When {nr} is zero, the height of the current window is if window {nr} doesn't exist. An existing window always has
returned. When window {nr} doesn't exist, -1 is returned. a height of zero or more.
An existing window always has a height of zero or more.
This excludes any window toolbar line.
Examples: >vim Examples: >vim
echo "The current window has " .. winheight(0) .. " lines." echo "Current window has " .. winheight(0) .. " lines."
< <
Parameters: ~ Parameters: ~
@@ -12146,18 +12145,21 @@ winsaveview() *winsaveview()*
(`vim.fn.winsaveview.ret`) (`vim.fn.winsaveview.ret`)
winwidth({nr}) *winwidth()* winwidth({nr}) *winwidth()*
The result is a Number, which is the width of window {nr}. Gets the width of |window-ID| {nr} (zero for "current
{nr} can be the window number or the |window-ID|. window"), including columns (|sign-column|, 'statuscolumn',
When {nr} is zero, the width of the current window is etc.). Returns -1 if window {nr} doesn't exist. An existing
returned. When window {nr} doesn't exist, -1 is returned. window always has a width of zero or more.
An existing window always has a width of zero or more.
Examples: >vim Example: >vim
echo "The current window has " .. winwidth(0) .. " columns." echo "Current window has " .. winwidth(0) .. " columns."
if winwidth(0) <= 50 if winwidth(0) <= 50
50 wincmd | 50 wincmd |
endif endif
< For getting the terminal or screen size, see the 'columns' <
option. To get the buffer "viewport", use |getwininfo()|: >vim
:echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
<
To get the Nvim screen size, see the 'columns' option.
Parameters: ~ Parameters: ~
• {nr} (`integer`) • {nr} (`integer`)

8
runtime/doc/options.txt
View File

@@ -7155,13 +7155,13 @@ A jump table for the options with a short description can be found at |Q_op|.
global global
Defines the default border style of floating windows. The default value Defines the default border style of floating windows. The default value
is empty, which is equivalent to "none". Valid values include: is empty, which is equivalent to "none". Valid values include:
- "bold": Bold line box.
- "double": Double-line box.
- "none": No border. - "none": No border.
- "single": A single line box.
- "double": A double line box.
- "rounded": Like "single", but with rounded corners ("╭" etc.). - "rounded": Like "single", but with rounded corners ("╭" etc.).
- "shadow": Drop shadow effect, by blending with the background.
- "single": Single-line box.
- "solid": Adds padding by a single whitespace cell. - "solid": Adds padding by a single whitespace cell.
- "shadow": A drop shadow effect by blending with the background.
- "bold": A bold line box.
*'window'* *'wi'* *'window'* *'wi'*
'window' 'wi' number (default screen height - 1) 'window' 'wi' number (default screen height - 1)

161
runtime/doc/provider.txt
View File

@@ -182,121 +182,112 @@ the "+" and/or "*" registers explicitly): >vim
See 'clipboard' for details and options. See 'clipboard' for details and options.
*clipboard-tool* *clipboard-tool*
The presence of a working clipboard tool implicitly enables the '+' and "*" The presence of a working clipboard tool implicitly enables the "+" and "*"
registers. Nvim looks for these clipboard tools, in order of priority: registers. Nvim supports these clipboard tools, in order of priority:
- |g:clipboard| (unless unset or `false`) - |g:clipboard| : User override (if set to a dict or any string "name" below;
- pbcopy, pbpaste (macOS) e.g. `g:clipboard="tmux"` forces tmux clipboard and skips auto-detection).
- wl-copy, wl-paste (if $WAYLAND_DISPLAY is set) - "pbcopy" : pbcopy, pbpaste (macOS)
- waycopy, waypaste (if $WAYLAND_DISPLAY is set) - "wl-copy" : wl-copy, wl-paste (if $WAYLAND_DISPLAY is set)
- xsel (if $DISPLAY is set) - "wayclip" : waycopy, waypaste (if $WAYLAND_DISPLAY is set)
- xclip (if $DISPLAY is set) - "xsel" : xsel (if $DISPLAY is set)
- lemonade (for SSH) https://github.com/pocke/lemonade - "xclip" : xclip (if $DISPLAY is set)
- doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/ - "lemonade" : lemonade (for SSH) https://github.com/pocke/lemonade
- *win32yank* (Windows) - "doitclient": doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/
- putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html - "win32yank" : *win32yank* (Windows)
- clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip - "putclip" : putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html
- termux (via termux-clipboard-set, termux-clipboard-set) - "clip" : clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip
- tmux (if $TMUX is set) - "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* *g:clipboard*
To configure a custom clipboard tool, set g:clipboard to a dictionary. To configure a custom clipboard tool, set `g:clipboard` to a string name (from
For example this configuration integrates the tmux clipboard: >vim the above |clipboard-tool| list), or dict (to explicitly specify the shell
commands or |lambda| functions).
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': ['tmux', 'load-buffer', '-'],
\ '*': ['tmux', 'load-buffer', '-'],
\ },
\ 'paste': {
\ '+': ['tmux', 'save-buffer', '-'],
\ '*': ['tmux', 'save-buffer', '-'],
\ },
\ 'cache_enabled': 1,
\ }
If "cache_enabled" is |TRUE| then when a selection is copied Nvim will cache 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 the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied. process has not died the cached selection is applied.
g:clipboard can also use functions (see |lambda|) instead of strings.
For example this configuration uses the g:foo variable 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', [])},
\ },
\ }
The "copy" function stores a list of lines and the register type. The "paste" 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 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()|. a list of lines and `regtype` is a register type conforming to |setreg()|.
Nvim also supports setting g:clipboard to a string to use a builtin clipboard provider: Example: set to "osc52" to force OSC52, skipping auto-detection of terminal
support: >vim
- "tmux" - Use tmux clipboard let g:clipboard = 'osc52'
- "xclip" - Use xclip for X11 clipboard
- "xsel" - Use xsel for X11 clipboard
- "wl-copy" - Use Wayland clipboard with wl-copy/wl-paste
- "wayclip" - Use Wayland clipboard with waycopy/waypaste
- "lemonade" - Use lemonade clipboard (for SSH)
- "doitclient" - Use doitclient clipboard (for SSH)
- "win32yank" - Use win32yank clipboard (for Windows)
- "clip" - Use clip/powershell clipboard (for Windows)
- "putclip" - Use putclip/getclip clipboard (for Windows/Cygwin)
- "termux" - Use Termux clipboard
- "pbcopy" - Use macOS clipboard
- "osc52" - Use OSC 52 sequence
Example: >vim Example: set to "wayclip" to force waycopy/waypaste: >vim
let g:clipboard = 'tmux'
This is equivalent to using the full dictionary configuration for tmux shown above. 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* *clipboard-wsl*
For Windows WSL, try this g:clipboard definition: For Windows WSL, try this g:clipboard definition:
>vim >vim
let g:clipboard = { let g:clipboard = {
\ 'name': 'WslClipboard', \ 'name': 'WslClipboard',
\ 'copy': { \ 'copy': {
\ '+': 'clip.exe', \ '+': 'clip.exe',
\ '*': 'clip.exe', \ '*': 'clip.exe',
\ }, \ },
\ 'paste': { \ '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", ""))',
\ '*': '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, \ 'cache_enabled': 0,
\ } \ }
< <
*clipboard-osc52* *clipboard-osc52*
Nvim bundles a clipboard provider that allows copying to the system clipboard Nvim bundles a clipboard provider that allows copying to the system clipboard
using OSC 52. OSC 52 is an Operating System Command control sequence that using OSC 52, an "Operating System Command" control-sequence that causes the
causes the terminal emulator to write to or read from the system clipboard. terminal emulator to write to or read from the system clipboard.
When Nvim is running in the |TUI|, it will automatically attempt to determine if When Nvim is running in the |TUI|, it automatically detects host terminal
the host terminal emulator supports OSC 52. If it does, then Nvim will use OSC support for OSC 52. If successful, then Nvim will use OSC 52 for copying and
52 for copying and pasting if no other |clipboard-tool| is found and when pasting if no other |clipboard-tool| is found and when 'clipboard' is unset.
'clipboard' is unset. NOTE: Using a terminal multiplexer (e.g. tmux) may NOTE: Using a terminal multiplexer (e.g. tmux) may inhibit automatic OSC 52
inhibit automatic OSC 52 support detection. support detection.
*g:termfeatures* *g:termfeatures*
To disable the automatic detection, set the "osc52" key of |g:termfeatures| to To disable the automatic detection, set the "osc52" key of |g:termfeatures| to
|v:false| in the |config| file. Example: >lua false early in your |config|. Example: >lua
local termfeatures = vim.g.termfeatures or {} local termfeatures = vim.g.termfeatures or {}
termfeatures.osc52 = false termfeatures.osc52 = false
vim.g.termfeatures = termfeatures vim.g.termfeatures = termfeatures
< <
To force Nvim to always use the OSC 52 provider you can use the following To force Nvim to use the OSC 52 provider you can set |g:clipboard|: >lua
|g:clipboard| definition: >lua
vim.g.clipboard = 'osc52' vim.g.clipboard = 'osc52'
@@ -313,7 +304,7 @@ Which is equivalent to: >lua
}, },
} }
< <
Note that not all terminal emulators support reading from the system clipboard Note: not all terminal emulators support reading from the system clipboard
(and even for those that do, users should be aware of the security (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 implications), so using OSC 52 for pasting may not be possible (and not
necessary, because you can |paste| instead using your system paste function). necessary, because you can |paste| instead using your system paste function).

8
runtime/lua/vim/_meta/options.lua generated
View File

@@ -7834,13 +7834,13 @@ vim.wo.winbl = vim.wo.winblend
--- Defines the default border style of floating windows. The default value --- Defines the default border style of floating windows. The default value
--- is empty, which is equivalent to "none". Valid values include: --- is empty, which is equivalent to "none". Valid values include:
--- - "bold": Bold line box.
--- - "double": Double-line box.
--- - "none": No border. --- - "none": No border.
--- - "single": A single line box.
--- - "double": A double line box.
--- - "rounded": Like "single", but with rounded corners ("╭" etc.). --- - "rounded": Like "single", but with rounded corners ("╭" etc.).
--- - "shadow": Drop shadow effect, by blending with the background.
--- - "single": Single-line box.
--- - "solid": Adds padding by a single whitespace cell. --- - "solid": Adds padding by a single whitespace cell.
--- - "shadow": A drop shadow effect by blending with the background.
--- - "bold": A bold line box.
--- ---
--- @type ''|'double'|'single'|'shadow'|'rounded'|'solid'|'bold'|'none' --- @type ''|'double'|'single'|'shadow'|'rounded'|'solid'|'bold'|'none'
vim.o.winborder = "" vim.o.winborder = ""

34
runtime/lua/vim/_meta/vimfn.lua generated
View File

@@ -10878,14 +10878,13 @@ function vim.fn.wincol() end
--- @return string --- @return string
function vim.fn.windowsversion() end function vim.fn.windowsversion() end
--- The result is a Number, which is the height of window {nr}. --- Gets the height of |window-ID| {nr} (zero for "current
--- {nr} can be the window number or the |window-ID|. --- window"), excluding any 'winbar' and 'statusline'. Returns -1
--- When {nr} is zero, the height of the current window is --- if window {nr} doesn't exist. An existing window always has
--- returned. When window {nr} doesn't exist, -1 is returned. --- a height of zero or more.
--- An existing window always has a height of zero or more. ---
--- This excludes any window toolbar line.
--- Examples: >vim --- Examples: >vim
--- echo "The current window has " .. winheight(0) .. " lines." --- echo "Current window has " .. winheight(0) .. " lines."
--- < --- <
--- ---
--- @param nr integer --- @param nr integer
@@ -11037,18 +11036,21 @@ function vim.fn.winrestview(dict) end
--- @return vim.fn.winsaveview.ret --- @return vim.fn.winsaveview.ret
function vim.fn.winsaveview() end function vim.fn.winsaveview() end
--- The result is a Number, which is the width of window {nr}. --- Gets the width of |window-ID| {nr} (zero for "current
--- {nr} can be the window number or the |window-ID|. --- window"), including columns (|sign-column|, 'statuscolumn',
--- When {nr} is zero, the width of the current window is --- etc.). Returns -1 if window {nr} doesn't exist. An existing
--- returned. When window {nr} doesn't exist, -1 is returned. --- window always has a width of zero or more.
--- An existing window always has a width of zero or more. ---
--- Examples: >vim --- Example: >vim
--- echo "The current window has " .. winwidth(0) .. " columns." --- echo "Current window has " .. winwidth(0) .. " columns."
--- if winwidth(0) <= 50 --- if winwidth(0) <= 50
--- 50 wincmd | --- 50 wincmd |
--- endif --- endif
--- <For getting the terminal or screen size, see the 'columns' --- <
--- option. --- To get the buffer "viewport", use |getwininfo()|: >vim
--- :echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
--- <
--- To get the Nvim screen size, see the 'columns' option.
--- ---
--- @param nr integer --- @param nr integer
--- @return integer --- @return integer

38
src/nvim/eval.lua
View File

@@ -13182,16 +13182,14 @@ M.funcs = {
args = 1, args = 1,
base = 1, base = 1,
desc = [=[ desc = [=[
The result is a Number, which is the height of window {nr}. Gets the height of |window-ID| {nr} (zero for "current
{nr} can be the window number or the |window-ID|. window"), excluding any 'winbar' and 'statusline'. Returns -1
When {nr} is zero, the height of the current window is if window {nr} doesn't exist. An existing window always has
returned. When window {nr} doesn't exist, -1 is returned. a height of zero or more.
An existing window always has a height of zero or more.
This excludes any window toolbar line.
Examples: >vim
echo "The current window has " .. winheight(0) .. " lines."
<
Examples: >vim
echo "Current window has " .. winheight(0) .. " lines."
<
]=], ]=],
name = 'winheight', name = 'winheight',
params = { { 'nr', 'integer' } }, params = { { 'nr', 'integer' } },
@@ -13374,19 +13372,21 @@ M.funcs = {
args = 1, args = 1,
base = 1, base = 1,
desc = [=[ desc = [=[
The result is a Number, which is the width of window {nr}. Gets the width of |window-ID| {nr} (zero for "current
{nr} can be the window number or the |window-ID|. window"), including columns (|sign-column|, 'statuscolumn',
When {nr} is zero, the width of the current window is etc.). Returns -1 if window {nr} doesn't exist. An existing
returned. When window {nr} doesn't exist, -1 is returned. window always has a width of zero or more.
An existing window always has a width of zero or more.
Examples: >vim Example: >vim
echo "The current window has " .. winwidth(0) .. " columns." echo "Current window has " .. winwidth(0) .. " columns."
if winwidth(0) <= 50 if winwidth(0) <= 50
50 wincmd | 50 wincmd |
endif endif
<For getting the terminal or screen size, see the 'columns' <
option. To get the buffer "viewport", use |getwininfo()|: >vim
:echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
<
To get the Nvim screen size, see the 'columns' option.
]=], ]=],
name = 'winwidth', name = 'winwidth',
params = { { 'nr', 'integer' } }, params = { { 'nr', 'integer' } },

8
src/nvim/options.lua
View File

@@ -10196,13 +10196,13 @@ local options = {
desc = [=[ desc = [=[
Defines the default border style of floating windows. The default value Defines the default border style of floating windows. The default value
is empty, which is equivalent to "none". Valid values include: is empty, which is equivalent to "none". Valid values include:
- "bold": Bold line box.
- "double": Double-line box.
- "none": No border. - "none": No border.
- "single": A single line box.
- "double": A double line box.
- "rounded": Like "single", but with rounded corners ("╭" etc.). - "rounded": Like "single", but with rounded corners ("╭" etc.).
- "shadow": Drop shadow effect, by blending with the background.
- "single": Single-line box.
- "solid": Adds padding by a single whitespace cell. - "solid": Adds padding by a single whitespace cell.
- "shadow": A drop shadow effect by blending with the background.
- "bold": A bold line box.
]=], ]=],
full_name = 'winborder', full_name = 'winborder',
scope = { 'global' }, scope = { 'global' },