From 21f0f7bca5a13fe847478ef27dc26bced9b3f3d1 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 18 Jun 2019 00:00:51 +0200 Subject: paste: WIP #4448 --- runtime/doc/eval.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 5d30ac15b3..2ec72f7717 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -4215,11 +4215,11 @@ getchar([expr]) *getchar()* :endfunction < You may also receive synthetic characters, such as - ||. Often you will want to ignore this and get + ||. Often you will want to ignore this and get another character: > :function GetKey() : let c = getchar() - : while c == "\" + : while c == "\" : let c = getchar() : endwhile : return c -- cgit From 0221a9220a2ec0691a7139c8362aba80d1f3b8ee Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 20 Aug 2019 19:41:45 +0200 Subject: paste: edge-case: handle EOL at end-of-buffer This is "readfile()-style", see also ":help channel-lines". --- runtime/doc/eval.txt | 11 ----------- 1 file changed, 11 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 2ec72f7717..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 - ||. Often you will want to ignore this and get - another character: > - :function GetKey() - : let c = getchar() - : while c == "\" - : 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. -- cgit From eacc70fb3ebae6d76112ab10647a42339f5f223f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 24 Aug 2019 13:54:27 +0200 Subject: API: nvim_paste --- runtime/doc/api.txt | 43 +++++++++++++++++++++++++++++++++++++++++++ runtime/doc/provider.txt | 33 +++++++++++++++++++++++++++++++++ runtime/doc/term.txt | 6 ------ 3 files changed, 76 insertions(+), 6 deletions(-) (limited to 'runtime') 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 @@ -218,6 +218,39 @@ 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 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* 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": -- cgit From 87389c6a57cf9fa91746503c479cdbea348030b9 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 27 Aug 2019 05:19:25 +0200 Subject: paste: make vim.paste() "public" --- runtime/doc/if_lua.txt | 19 +++++++++++++++++++ runtime/doc/provider.txt | 20 +++++++++++--------- 2 files changed, 30 insertions(+), 9 deletions(-) (limited to 'runtime') 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 eb6d562e18..833be8a103 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -222,11 +222,11 @@ 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. +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, @@ -235,19 +235,21 @@ 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()|. +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. +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. Example: > +You can implement a custom paste handler by redefining |vim.paste()|. +Example: > - vim._paste = (function(lines, phase) + vim.paste = (function(lines, phase) vim.api.nvim_put(lines, 'c', true, true) end) -- cgit