API: nvim_paste

3 files changed, 76 insertions, 6 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":