diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/api.txt | 43 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/if_lua.txt | 19 | ||||
| -rw-r--r-- | runtime/doc/provider.txt | 35 | ||||
| -rw-r--r-- | runtime/doc/term.txt | 6 |
5 files changed, 97 insertions, 17 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/eval.txt b/runtime/doc/eval.txt index 5d30ac15b3..897b5df072 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -4214,17 +4214,6 @@ getchar([expr]) *getchar()* : endwhile :endfunction < - You may also receive synthetic characters, such as - |<CursorHold>|. Often you will want to ignore this and get - another character: > - :function GetKey() - : let c = getchar() - : while c == "\<CursorHold>" - : let c = getchar() - : endwhile - : return c - :endfunction - getcharmod() *getcharmod()* The result is a Number which is the state of the modifiers for the last obtained character with getchar() or in another way. diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index a9b8c5fae8..1837e14623 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -533,6 +533,25 @@ inspect({object}, {options}) *vim.inspect()* See also: ~ https://github.com/kikito/inspect.lua +paste({lines}, {phase}) *vim.paste()* + Paste handler, invoked by |nvim_paste()| when a conforming UI + (such as the |TUI|) pastes text into the editor. + + Parameters: ~ + {lines} |readfile()|-style list of lines to paste. + |channel-lines| + {phase} -1: "non-streaming" paste: the call contains all + lines. If paste is "streamed", `phase` indicates the stream state: + • 1: starts the paste (exactly once) + • 2: continues the paste (zero or more times) + • 3: ends the paste (exactly once) + + Return: ~ + false if client should cancel the paste. + + See also: ~ + |paste| + diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index dc045c360a..833be8a103 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -219,6 +219,41 @@ 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 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 always inserts text after the cursor. 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. + +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 by redefining |vim.paste()|. +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": |