API: nvim_paste

10 files changed, 205 insertions, 67 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 2c6b053994..32d7f5eb1e 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -793,6 +793,49 @@ nvim_get_namespaces()                                  *nvim_get_namespaces()*
                 Return: ~
                     dict that maps from names to namespace ids.
 
+nvim_paste({data}, {phase})                                     *nvim_paste()*
+                Pastes at cursor, in any mode.
+
+                Invokes the `vim.paste` handler, which handles each mode
+                appropriately. Sets redo/undo. Faster than |nvim_input()|.
+
+                Errors ('nomodifiable', `vim.paste()` failure, …) are
+                reflected in `err` but do not affect the return value (which
+                is strictly decided by `vim.paste()` ). On error, subsequent
+                calls are ignored ("drained") until the next paste is
+                initiated (phase 1 or -1).
+
+                Parameters: ~
+                    {data}   Multiline input. May be binary (containing NUL
+                             bytes).
+                    {phase}  -1: paste in a single call (i.e. without
+                             streaming). To "stream" a paste, call `nvim_paste` sequentially with these `phase` values:
+                             • 1: starts the paste (exactly once)
+                             • 2: continues the paste (zero or more times)
+                             • 3: ends the paste (exactly once)
+
+                Return: ~
+
+                    • true: Client may continue pasting.
+                    • false: Client must cancel the paste.
+
+nvim_put({lines}, {type}, {after}, {follow})                      *nvim_put()*
+                Puts text at cursor, in any mode.
+
+                Compare |:put| and |p| which are always linewise.
+
+                Parameters: ~
+                    {lines}   |readfile()|-style list of lines.
+                              |channel-lines|
+                    {type}    Edit behavior:
+                              • "b" |blockwise-visual| mode
+                              • "c" |characterwise| mode
+                              • "l" |linewise| mode
+                              • "" guess by contents
+                    {after}   Insert after cursor (like |p|), or before (like
+                              |P|).
+                    {follow}  Place cursor at end of inserted text.
+
 nvim_subscribe({event})                                     *nvim_subscribe()*
                 Subscribes to event broadcasts.
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index dc045c360a..eb6d562e18 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -219,6 +219,39 @@ 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()|.
 
 ==============================================================================
+Paste 							*provider-paste* *paste*
+
+"Paste" is a separate concept from |clipboard|: paste means "dump a bunch of
+text to the editor", whereas clipboard adds features like |quote-+| to get and
+set the OS clipboard buffer directly.  When you middle-click or CTRL-SHIFT-v
+(macOS: CMD-v) to paste text into your terminal, this 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 opt-into Nvim's amazing paste-handling by calling |nvim_paste()|.
+
+PASTE BEHAVIOR ~
+
+Paste always inserts text after the cursor.  In cmdline-mode only the first
+line is pasted, to avoid accidentally executing many commands.
+
+When pasting a huge amount of text, screen updates are throttled and the
+message area shows a "..." pulse.
+
+You can implement a custom paste handler.  Example: >
+
+  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
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 978f50dd55..4f4d379f01 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -219,12 +219,6 @@ effect on some UIs.
 ==============================================================================
 Using the mouse						*mouse-using*
 
-							*bracketed-paste-mode*
-Nvim enables bracketed paste by default. Bracketed paste mode allows terminal
-applications to distinguish between typed text and pasted text. Thus you can
-paste text without Nvim trying to format or indent the text.
-See also https://cirw.in/blog/bracketed-paste
-
 					*mouse-mode-table* *mouse-overview*
 Overview of what the mouse buttons do, when 'mousemodel' is "extend":
 
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index 6b05d1ac0a..3443f85e20 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -745,6 +745,35 @@ String ga_take_string(garray_T *ga)
   return str;
 }
 
+/// Creates "readfile()-style" ArrayOf(String).
+///
+/// - NUL bytes are replaced with NL (form-feed).
+/// - If last line ends with NL an extra empty list item is added.
+Array string_to_array(const String input)
+{
+  Array ret = ARRAY_DICT_INIT;
+  for (size_t i = 0; i < input.size; i++) {
+    const char *start = input.data + i;
+    const char *end = xmemscan(start, NL, input.size - i);
+    const size_t line_len = (size_t)(end - start);
+    i += line_len;
+
+    String s = {
+      .size = line_len,
+      .data = xmemdupz(start, line_len),
+    };
+    memchrsub(s.data, NUL, NL, line_len);
+    ADD(ret, STRING_OBJ(s));
+    // If line ends at end-of-buffer, add empty final item.
+    // This is "readfile()-style", see also ":help channel-lines".
+    if (i + 1 == input.size && end[0] == NL) {
+      ADD(ret, STRING_OBJ(cchar_to_string(NUL)));
+    }
+  }
+
+  return ret;
+}
+
 /// Set, tweak, or remove a mapping in a mode. Acts as the implementation for
 /// functions like @ref nvim_buf_set_keymap.
 ///
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 02000907f9..b355491dcc 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1206,6 +1206,42 @@ Dictionary nvim_get_namespaces(void)
   return retval;
 }
 
+/// Paste
+///
+/// Invokes the `vim.paste` handler, which handles each mode appropriately.
+/// Sets redo/undo. Faster than |nvim_input()|.
+///
+/// @param data  Multiline input. May be binary (containing NUL bytes).
+/// @param phase  Pass -1 to paste as one big buffer (i.e. without streaming).
+///               To "stream" a paste, call `nvim_paste` sequentially with
+///               these `phase` values:
+///                 - 1: starts the paste (exactly once)
+///                 - 2: continues the paste (zero or more times)
+///                 - 3: ends the paste (exactly once)
+/// @param[out] err Error details, if any
+/// @return true if paste should continue, false if paste was canceled
+Boolean nvim_paste(String data, Integer phase, Error *err)
+  FUNC_API_SINCE(6)
+{
+  if (phase < -1 || phase > 3) {
+    api_set_error(err, kErrorTypeValidation, "Invalid phase: %"PRId64, phase);
+    return false;
+  }
+  Array args = ARRAY_DICT_INIT;
+  ADD(args, ARRAY_OBJ(string_to_array(data)));
+  ADD(args, INTEGER_OBJ(phase));
+  Object rv
+    = nvim_execute_lua(STATIC_CSTR_AS_STRING("return vim._paste(...)"),
+                       args, err);
+  // Abort paste if handler does not return true.
+  bool ok = !ERROR_SET(err)
+    && (rv.type == kObjectTypeBoolean && rv.data.boolean);
+  api_free_object(rv);
+  api_free_array(args);
+
+  return ok;
+}
+
 /// Puts text at cursor.
 ///
 /// Compare |:put| and |p| which are always linewise.
@@ -1225,11 +1261,8 @@ void nvim_put(ArrayOf(String) lines, String type, Boolean after,
 {
   yankreg_T *reg = xcalloc(sizeof(yankreg_T), 1);
   if (!prepare_yankreg_from_object(reg, type, lines.size)) {
-    api_set_error(err,
-                  kErrorTypeValidation,
-                  "Invalid regtype %s",
-                  type.data);
-    return;
+    api_set_error(err, kErrorTypeValidation, "Invalid type: '%s'", type.data);
+    goto cleanup;
   }
   if (lines.size == 0) {
     goto cleanup;  // Nothing to do.
@@ -1237,9 +1270,8 @@ void nvim_put(ArrayOf(String) lines, String type, Boolean after,
 
   for (size_t i = 0; i < lines.size; i++) {
     if (lines.items[i].type != kObjectTypeString) {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "All items in the lines array must be strings");
+      api_set_error(err, kErrorTypeValidation,
+                    "Invalid lines (expected array of strings)");
       goto cleanup;
     }
     String line = lines.items[i].data.string;
diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c
index d1b4751a00..0ef0c852a4 100644
--- a/src/nvim/getchar.c
+++ b/src/nvim/getchar.c
@@ -523,15 +523,12 @@ void AppendToRedobuff(const char *s)
   }
 }
 
-/*
- * Append to Redo buffer literally, escaping special characters with CTRL-V.
- * K_SPECIAL and CSI are escaped as well.
- */
-void 
-AppendToRedobuffLit (
-    char_u *str,
-    int len                    /* length of "str" or -1 for up to the NUL */
-)
+/// Append to Redo buffer literally, escaping special characters with CTRL-V.
+/// K_SPECIAL and CSI are escaped as well.
+///
+/// @param str  String to append
+/// @param len  Length of `str` or -1 for up to the NUL.
+void AppendToRedobuffLit(const char_u *str, int len)
 {
   if (block_redo) {
     return;
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index dca61d814a..637a4baf33 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -105,9 +105,10 @@ local _paste = (function()
       tdots = now
       tredraw = now
       tick = 0
-      if (call('mode', {})):find('[vV]') then
-        vim.api.nvim_feedkeys('', 'n', false)
-      end
+      -- TODO
+      -- if mode == 'i' or mode == 'R' then
+      --   nvim_cancel()
+      -- end
     end
     vim.api.nvim_put(lines, 'c', true, true)
     if (now - tredraw >= 1000) or phase == 1 or phase == 3 then
@@ -119,6 +120,8 @@ local _paste = (function()
       local dots = ('.'):rep(tick % 4)
       tdots = now
       tick = tick + 1
+      -- Use :echo because Lua print('') is a no-op, and we want to clear the
+      -- message when there are zero dots.
       vim.api.nvim_command(('echo "%s"'):format(dots))
     end
     if phase == 3 then
diff --git a/src/nvim/tui/input.c b/src/nvim/tui/input.c
index fc06f21339..33062e88d3 100644
--- a/src/nvim/tui/input.c
+++ b/src/nvim/tui/input.c
@@ -100,31 +100,6 @@ static void tinput_done_event(void **argv)
   input_done();
 }
 
-static Array string_to_array(const String input)
-{
-  Array ret = ARRAY_DICT_INIT;
-  for (size_t i = 0; i < input.size; i++) {
-    const char *start = input.data + i;
-    const char *end = xmemscan(start, NL, input.size - i);
-    const size_t line_len = (size_t)(end - start);
-    i += line_len;
-
-    String s = {
-      .size = line_len,
-      .data = xmemdupz(start, line_len),
-    };
-    memchrsub(s.data, NUL, NL, line_len);
-    ADD(ret, STRING_OBJ(s));
-    // If line ends at end-of-buffer, add empty final item.
-    // This is "readfile()-style", see also ":help channel-lines".
-    if (i + 1 == input.size && end[0] == NL) {
-      ADD(ret, STRING_OBJ(cchar_to_string(NUL)));
-    }
-  }
-
-  return ret;
-}
-
 static void tinput_wait_enqueue(void **argv)
 {
   TermInput *input = argv[0];
@@ -132,18 +107,9 @@ static void tinput_wait_enqueue(void **argv)
     const String keys = { .data = buf, .size = len };
     if (input->paste) {
       Error err = ERROR_INIT;
-      Array args = ARRAY_DICT_INIT;
-      ADD(args, ARRAY_OBJ(string_to_array(keys)));
-      ADD(args, INTEGER_OBJ(input->paste));
-      Object rv
-        = nvim_execute_lua(STATIC_CSTR_AS_STRING("return vim._paste(...)"),
-                           args, &err);
-      input->paste = (rv.type == kObjectTypeBoolean && rv.data.boolean)
-        ? 2   // Paste phase: "continue".
-        : 0;  // Abort paste if handler does not return true.
-
-      api_free_object(rv);
-      api_free_array(args);
+      Boolean rv = nvim_paste(keys, input->paste, &err);
+      // Paste phase: "continue" (unless handler failed).
+      input->paste = rv && !ERROR_SET(&err) ? 2 : 0;
       rbuffer_consumed(input->key_buffer, len);
       rbuffer_reset(input->key_buffer);
       if (ERROR_SET(&err)) {
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 3f3d9b74bb..212c4f4300 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -366,7 +366,44 @@ describe('API', function()
     end)
   end)
 
+  describe('nvim_paste', function()
+    it('validates args', function()
+      expect_err('Invalid phase: %-2', request,
+        'nvim_paste', 'foo', -2)
+      expect_err('Invalid phase: 4', request,
+        'nvim_paste', 'foo', 4)
+    end)
+    it('non-streaming', function()
+      -- With final "\n".
+      nvim('paste', 'line 1\nline 2\nline 3\n', -1)
+      expect([[
+        line 1
+        line 2
+        line 3
+        ]])
+      -- Cursor follows the paste.
+      eq({0,4,1,0}, funcs.getpos('.'))
+      eq(false, nvim('get_option', 'paste'))
+      command('%delete _')
+      -- Without final "\n".
+      nvim('paste', 'line 1\nline 2\nline 3', -1)
+      expect([[
+        line 1
+        line 2
+        line 3]])
+      -- Cursor follows the paste.
+      eq({0,3,6,0}, funcs.getpos('.'))
+      eq(false, nvim('get_option', 'paste'))
+    end)
+  end)
+
   describe('nvim_put', function()
+    it('validates args', function()
+      expect_err('Invalid lines %(expected array of strings%)', request,
+        'nvim_put', {42}, 'l', false, false)
+      expect_err("Invalid type: 'x'", request,
+        'nvim_put', {'foo'}, 'x', false, false)
+    end)
     it('inserts text', function()
       -- linewise
       nvim('put', {'line 1','line 2','line 3'}, 'l', true, true)
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index adf968712d..414838444f 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/test/functional/terminal/tui_spec.lua
@@ -298,19 +298,23 @@ describe('TUI', function()
   end)
 
   -- TODO
-  it('in normal-mode', function()
+  it('paste: normal-mode', function()
   end)
 
   -- TODO
-  it('in command-mode', function()
+  it('paste: command-mode inserts 1 line', function()
   end)
 
   -- TODO
-  it('sets undo-point after consecutive pastes', function()
+  it('paste: sets undo-point after consecutive pastes', function()
+  end)
+
+  it('paste: other modes', function()
+    -- Other modes act like CTRL-C + paste.
   end)
 
   -- TODO
-  it('handles missing "stop paste" sequence', function()
+  it('paste: handles missing "stop paste" sequence', function()
   end)
 
   -- TODO: error when pasting into 'nomodifiable' buffer: