feat(clipboard): enable OSC 52 clipboard provider by default (#26064)

Use the XTGETTCAP sequence to determine if the host terminal supports
the OSC 52 sequence and, if it does, enable the OSC 52 clipboard
provider by default.

This is only done automatically when all of the following are true:

  1. Nvim is running in the TUI
  2. 'clipboard' is not set to unnamed or unnamedplus
  3. g:clipboard is unset
  4. Nvim is running in an SSH connection ($SSH_TTY is set)
  5. Nvim is not running inside tmux ($TMUX is unset)

runtime/doc/news.txt

@@ -209,7 +209,8 @@ The following new APIs and features were added.
   read escape sequence responses from the terminal.
 
 • A clipboard provider which uses OSC 52 to copy the selection to the system
-  clipboard is now bundled by default. |clipboard-osc52|
+  clipboard is now bundled by default and will be automatically enabled under
+  certain conditions. |clipboard-osc52|
 
 • The 'termsync' option asks the terminal emulator to buffer screen updates
   until the redraw cycle is complete. Requires support from the terminal.

runtime/doc/provider.txt

@@ -260,27 +260,41 @@ using OSC 52. OSC 52 is an Operating System Command control sequence that
 writes the copied text to the terminal emulator. If the terminal emulator
 supports OSC 52 then it will write the copied text into the system clipboard.
 
-This is most useful when using Nvim remotely (e.g. via ssh) as Nvim does not
-have direct access to the system clipboard in that case.
+Nvim will attempt to automatically determine if the host terminal emulator
+supports the OSC 52 sequence and enable the OSC 52 clipboard provider if it
+does as long as all of the following are true:
 
-Because not all terminal emulators support OSC 52, this provider must be opted
-into explicitly by setting the following |g:clipboard| definition: >lua
+  • Nvim is running in the |TUI|
+  • |g:clipboard| is unset
+  • 'clipboard' is not set to "unnamed" or "unnamedplus"
+  • $SSH_TTY is set
+  • $TMUX is unset
+
+If any of the above conditions are not met then the OSC 52 clipboard provider
+will not be used by default and Nvim will fall back to discovering a
+|clipboard-tool| through the usual process.
+
+To force Nvim to use the OSC 52 provider you can use the following
+|g:clipboard| definition: >lua
 
     vim.g.clipboard = {
       name = 'OSC 52',
       copy = {
-        ['+'] = require('vim.ui.clipboard.osc52').copy,
-        ['*'] = require('vim.ui.clipboard.osc52').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,
+        ['+'] = require('vim.ui.clipboard.osc52').paste('+'),
+        ['*'] = require('vim.ui.clipboard.osc52').paste('*'),
       },
     }
 <
 Note that 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.
+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*

runtime/lua/vim/termcap.lua

@@ -0,0 +1,60 @@
+local M = {}
+
+--- Query the host terminal emulator for terminfo capabilities.
+---
+--- This function sends the XTGETTCAP DCS sequence to the host terminal emulator asking the terminal
+--- to send us its terminal capabilities. These are strings that are normally taken from a terminfo
+--- file, however an up to date terminfo database is not always available (particularly on remote
+--- machines), and many terminals continue to misidentify themselves or do not provide their own
+--- terminfo file, making the terminfo database unreliable.
+---
+--- Querying the terminal guarantees that we get a truthful answer, but only if the host terminal
+--- emulator supports the XTGETTCAP sequence.
+---
+--- @param caps string|table A terminal capability or list of capabilities to query
+--- @param cb function(cap:string, seq:string) Function to call when a response is received
+function M.query(caps, cb)
+  vim.validate({
+    caps = { caps, { 'string', 'table' } },
+    cb = { cb, 'f' },
+  })
+
+  if type(caps) ~= 'table' then
+    caps = { caps }
+  end
+
+  local count = #caps
+
+  vim.api.nvim_create_autocmd('TermResponse', {
+    callback = function(args)
+      local resp = args.data ---@type string
+      local k, v = resp:match('^\027P1%+r(%x+)=(%x+)$')
+      if k and v then
+        local cap = vim.text.hexdecode(k)
+        local seq =
+          vim.text.hexdecode(v):gsub('\\E', '\027'):gsub('%%p%d', ''):gsub('\\(%d+)', string.char)
+
+        -- TODO: When libtermkey is patched to accept BEL as an OSC terminator, this workaround can
+        -- be removed
+        seq = seq:gsub('\007$', '\027\\')
+
+        cb(cap, seq)
+
+        count = count - 1
+        if count == 0 then
+          return true
+        end
+      end
+    end,
+  })
+
+  local encoded = {} ---@type string[]
+  for i = 1, #caps do
+    encoded[i] = vim.text.hexencode(caps[i])
+  end
+
+  local query = string.format('\027P+q%s\027\\', table.concat(encoded, ';'))
+  io.stdout:write(query)
+end
+
+return M

runtime/lua/vim/ui/clipboard/osc52.lua

@@ -1,60 +1,75 @@
 local M = {}
 
-function M.copy(lines)
-  local s = table.concat(lines, '\n')
-  io.stdout:write(string.format('\027]52;;%s\027\\', vim.base64.encode(s)))
+--- Return the OSC 52 escape sequence
+---
+--- @param clipboard string The clipboard to read from or write to
+--- @param contents string The Base64 encoded contents to write to the clipboard, or '?' to read
+---                        from the clipboard
+local function osc52(clipboard, contents)
+  return string.format('\027]52;%s;%s\027\\', clipboard, contents)
 end
 
-function M.paste()
-  local contents = nil
-  local id = vim.api.nvim_create_autocmd('TermResponse', {
-    callback = function(args)
-      local resp = args.data ---@type string
-      local encoded = resp:match('\027%]52;%w?;([A-Za-z0-9+/=]*)')
-      if encoded then
-        contents = vim.base64.decode(encoded)
-        return true
-      end
-    end,
-  })
+function M.copy(reg)
+  local clipboard = reg == '+' and 'c' or 's'
+  return function(lines)
+    local s = table.concat(lines, '\n')
+    io.stdout:write(osc52(clipboard, vim.base64.encode(s)))
+  end
+end
 
-  io.stdout:write('\027]52;;?\027\\')
+function M.paste(reg)
+  local clipboard = reg == '+' and 'c' or 's'
+  return function()
+    local contents = nil
+    local id = vim.api.nvim_create_autocmd('TermResponse', {
+      callback = function(args)
+        local resp = args.data ---@type string
+        local encoded = resp:match('\027%]52;%w?;([A-Za-z0-9+/=]*)')
+        if encoded then
+          contents = vim.base64.decode(encoded)
+          return true
+        end
+      end,
+    })
 
-  local ok, res
+    io.stdout:write(osc52(clipboard, '?'))
 
-  -- Wait 1s first for terminals that respond quickly
-  ok, res = vim.wait(1000, function()
-    return contents ~= nil
-  end)
+    local ok, res
 
-  if res == -1 then
-    -- If no response was received after 1s, print a message and keep waiting
-    vim.api.nvim_echo(
-      { { 'Waiting for OSC 52 response from the terminal. Press Ctrl-C to interrupt...' } },
-      false,
-      {}
-    )
-    ok, res = vim.wait(9000, function()
+    -- Wait 1s first for terminals that respond quickly
+    ok, res = vim.wait(1000, function()
       return contents ~= nil
     end)
-  end
 
-  if not ok then
-    vim.api.nvim_del_autocmd(id)
     if res == -1 then
-      vim.notify(
-        'Timed out waiting for a clipboard response from the terminal',
-        vim.log.levels.WARN
+      -- If no response was received after 1s, print a message and keep waiting
+      vim.api.nvim_echo(
+        { { 'Waiting for OSC 52 response from the terminal. Press Ctrl-C to interrupt...' } },
+        false,
+        {}
       )
-    elseif res == -2 then
-      -- Clear message area
-      vim.api.nvim_echo({ { '' } }, false, {})
+      ok, res = vim.wait(9000, function()
+        return contents ~= nil
+      end)
     end
-    return 0
-  end
 
-  -- If we get here, contents should be non-nil
-  return vim.split(assert(contents), '\n')
+    if not ok then
+      vim.api.nvim_del_autocmd(id)
+      if res == -1 then
+        vim.notify(
+          'Timed out waiting for a clipboard response from the terminal',
+          vim.log.levels.WARN
+        )
+      elseif res == -2 then
+        -- Clear message area
+        vim.api.nvim_echo({ { '' } }, false, {})
+      end
+      return 0
+    end
+
+    -- If we get here, contents should be non-nil
+    return vim.split(assert(contents), '\n')
+  end
 end
 
 return M

runtime/plugin/osc52.lua

@@ -0,0 +1,37 @@
+local tty = vim.iter(vim.api.nvim_list_uis()):any(function(ui)
+  return ui.chan == 1 and ui.stdout_tty
+end)
+
+if
+  not tty
+  or vim.g.clipboard ~= nil
+  or vim.o.clipboard ~= ''
+  or not os.getenv('SSH_TTY')
+  or os.getenv('TMUX')
+then
+  return
+end
+
+require('vim.termcap').query('Ms', function(cap, seq)
+  assert(cap == 'Ms')
+
+  -- If the terminal reports a sequence other than OSC 52 for the Ms capability
+  -- then ignore it. We only support OSC 52 (for now)
+  if not seq:match('^\027%]52') then
+    return
+  end
+
+  local osc52 = require('vim.ui.clipboard.osc52')
+
+  vim.g.clipboard = {
+    name = 'OSC 52',
+    copy = {
+      ['+'] = osc52.copy('+'),
+      ['*'] = osc52.copy('*'),
+    },
+    paste = {
+      ['+'] = osc52.paste('+'),
+      ['*'] = osc52.paste('*'),
+    },
+  }
+end)