|
1 | | -*eval.txt* For Vim version 9.1. Last change: 2025 Oct 18 |
| 1 | +*eval.txt* For Vim version 9.1. Last change: 2025 Oct 26 |
2 | 2 |
|
3 | 3 |
|
4 | 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
@@ -38,7 +38,6 @@ a remark is given. |
38 | 38 | 12. The sandbox |eval-sandbox| |
39 | 39 | 13. Textlock |textlock| |
40 | 40 | 14. Vim script library |vim-script-library| |
41 | | -15. Clipboard providers |clipboard-providers| |
42 | 41 |
|
43 | 42 | Testing support is documented in |testing.txt|. |
44 | 43 | Profiling is documented at |profiling|. |
@@ -2246,17 +2245,10 @@ v:clipmethod The current method of accessing the clipboard that is being |
2246 | 2245 | used. Can either have the value of: |
2247 | 2246 | wayland The Wayland protocol is being used. |
2248 | 2247 | x11 X11 selections are being used. |
2249 | | - gui GUI specific method is being used |
2250 | | - other Some other method is being used |
2251 | | - none Clipboard functionality is disabled or |
2252 | | - unavailable. |
| 2248 | + none The above methods are unavailable or |
| 2249 | + cannot be used. |
2253 | 2250 | See 'clipmethod' for more details. |
2254 | 2251 |
|
2255 | | - *v:clipproviders* |
2256 | | -v:clipproviders |
2257 | | - A dictionary containing clipboard providers, see |
2258 | | - |clipboard-providers| for more information. |
2259 | | - |
2260 | 2252 | *v:cmdarg* *cmdarg-variable* |
2261 | 2253 | v:cmdarg This variable is used for two purposes: |
2262 | 2254 | 1. The extra arguments given to a file read/write command. |
@@ -5269,134 +5261,5 @@ Usage: >vim |
5269 | 5261 | :call dist#vim9#Launch(<args>) |
5270 | 5262 | :Launch <app> <args>. |
5271 | 5263 | < |
5272 | | -============================================================================== |
5273 | | -15. Clipboard providers *clipboard-providers* |
5274 | | - |
5275 | | -When Vim is compiled with the |+clipboard_provider| feature, which requires |
5276 | | -the |+eval| feature, creating custom clipboards is possible. These providers |
5277 | | -handle the "+" and "*" registers. Note that if |+wayland_clipboard| or |
5278 | | -|+xterm_clipboard| features are not compiled in, then the "+" register will |
5279 | | -not be available. |
5280 | | - |
5281 | | -To add a provider, add a new entry to the |v:clipproviders| dictionary, in the |
5282 | | -format of: > |
5283 | | - let v:clipproviders["name"] = { |
5284 | | - \ "available": function("Available"), |
5285 | | - \ "paste": { |
5286 | | - \ '+': function("Paste"), " For the + register |
5287 | | - \ '*': function("Paste"), " For the * register |
5288 | | - \ }, |
5289 | | - \ "copy": { |
5290 | | - \ '+': function("Copy"), " Same thing as above |
5291 | | - \ '*': function("Copy"), |
5292 | | - \ }, |
5293 | | - \ } |
5294 | | -
|
5295 | | -The key is the provider name, which should be used in 'clipmethod', for |
5296 | | -example in the following example, you would add "name" to 'clipmethod' in |
5297 | | -order to use it. > |
5298 | | - set clipmethod=name,wayland,x11,gui |
5299 | | -
|
5300 | | -Each callback can either be a name of a function in a string, a |Funcref|, or |
5301 | | -a |lambda| expression. |
5302 | | - |
5303 | | -Note that these dictionary entries are optional, for example, if you don't |
5304 | | -care about the "copy" functions, then you can simply exclude them. When Vim |
5305 | | -yanks/copies something, then simply nothing will be done. |
5306 | | - |
5307 | | - *clipboard-provider-available* |
5308 | | -The "available" callback should return a string, which should contain which |
5309 | | -clipboard registers are available. For example, if the "+" register is only |
5310 | | -available, then the function would return "+", or if both "+" and "*" are |
5311 | | -available, then return "+*". |
5312 | | - |
5313 | | - *clipboard-provider-paste* |
5314 | | -The "paste" callback takes a first argument which is the register being put |
5315 | | -(string), and a second argument which is the type of access (string). It |
5316 | | -should return either a tuple/list or string. If a tuple/list is returned, it |
5317 | | -should have two elements: |
5318 | | - - The register type conforming to |setreg()|. |
5319 | | - - A list of strings |
5320 | | -If the register type is an empty string, then the type is automatically |
5321 | | -chosen, see |setreg()|. If a string is returned, then it can either be "clear" |
5322 | | -or "previous". "clear" makes Vim clear the register, and "previous" makes Vim |
5323 | | -use the previous register contents (or current depending on how you view it). |
5324 | | - |
5325 | | -The second argument, the access type, can either be "explicit" or "implicit". |
5326 | | -"explicit" means that the user is directly accessing the clipboard, such as |
5327 | | -putting text, or calling |getreg()|; "implicit" means that the clipboard is |
5328 | | -being accessed indirectly, such when |:registers| is called, or when an |
5329 | | -unrelated operation causes Vim to access the clipboard. |
5330 | | - |
5331 | | -This is useful since some operations in Vim implicity access the clipboard |
5332 | | -indirectly. For example, if when you want to create a provider for the OSC52 |
5333 | | -command (accessing the clipboard via an escape code). Many terminals show a |
5334 | | -confirmation if you want Vim to access the clipboard. This can be very |
5335 | | -annoying with the terminal asking for permission everytime you do something |
5336 | | -that accesses the clipboard behind the scenes. A good way to handle implicit |
5337 | | -access is to return "previous", which leaves the register contents unchanged. |
5338 | | - |
5339 | | - *clipboard-provider-copy* |
5340 | | -The "copy" callback returns nothing, and takes the given arguments in order: |
5341 | | - - The register being operated on |
5342 | | - - The register type, conforming to |getregtype()| |
5343 | | - - A list of strings to copy |
5344 | | - |
5345 | | -The provider can do whatever it wants with the given information. This |
5346 | | -function is called on every request to change the clipboard register(s). |
5347 | | - |
5348 | | - *clipboard-provider-textlock* |
5349 | | -In both the "paste" and "copy" callbacks, it is not allowed to change the |
5350 | | -buffer text, see |textlock|. |
5351 | | - |
5352 | | - *clipboard-provider-example* |
5353 | | -Here is an example script that uses the clipboard provider feature through the |
5354 | | -OSC52 command: >vim |
5355 | | - |
5356 | | - func Available() |
5357 | | - return "*" |
5358 | | - endfunc |
5359 | | - |
5360 | | - func Paste(reg, type) |
5361 | | - " If implicit access, don't do anything |
5362 | | - if a:type == "implicit" |
5363 | | - return "previous" |
5364 | | - endif |
5365 | 5264 |
|
5366 | | - augroup OSC |
5367 | | - autocmd! |
5368 | | - autocmd TermResponseAll osc ++once call feedkeys("\<F30>", '!') |
5369 | | - augroup END |
5370 | | - |
5371 | | - " Send command |
5372 | | - call echoraw("\<Esc>]52;;?\<Esc>\\") |
5373 | | - |
5374 | | - " Wait until autocmd is triggered |
5375 | | - while getchar(-1) != "\<F30>" |
5376 | | - endwhile |
5377 | | - |
5378 | | - autocmd! OSC |
5379 | | - |
5380 | | - " Extract the base64 stuff |
5381 | | - let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') |
5382 | | - |
5383 | | - return ("", blob2str(base64_decode(l:stuff))) |
5384 | | - endfunc |
5385 | | - |
5386 | | - func Copy(reg, type, lines) |
5387 | | - call echoraw("\<Esc>]52;c;" .. |
5388 | | - \ base64_encode(str2blob(a:lines)) .. "\<Esc>\\") |
5389 | | - endfunc |
5390 | | - let v:clipproviders["myosc"] = { |
5391 | | - \ "available": function("Available"), |
5392 | | - \ "paste": { |
5393 | | - \ '*': function("Paste") |
5394 | | - \ }, |
5395 | | - \ "copy": { |
5396 | | - \ '*': function("Copy") |
5397 | | - \ }, |
5398 | | - \ } |
5399 | | - set clipmethod=myosc |
5400 | | - |
5401 | | -< |
5402 | 5265 | vim:tw=78:ts=8:noet:ft=help:norl: |
0 commit comments