|
1 | | -*eval.txt* For Vim version 9.1. Last change: 2025 Dec 01 |
| 1 | +*eval.txt* For Vim version 9.1. Last change: 2025 Dec 19 |
2 | 2 |
|
3 | 3 |
|
4 | 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
@@ -38,6 +38,7 @@ 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| |
41 | 42 |
|
42 | 43 | Testing support is documented in |testing.txt|. |
43 | 44 | Profiling is documented at |profiling|. |
@@ -1348,7 +1349,13 @@ To compare Funcrefs to see if they refer to the same function, ignoring bound |
1348 | 1349 | Dictionary and arguments, use |get()| to get the function name: > |
1349 | 1350 | if get(Part1, 'name') == get(Part2, 'name') |
1350 | 1351 | " Part1 and Part2 refer to the same function |
1351 | | -< *E1037* |
| 1352 | +< |
| 1353 | + *E1437* |
| 1354 | +An |Object| can only be compared with another |Object|, using only the |
| 1355 | +"equal", "not equal", "is" and "isnot" operators |expr4|. An |enum| is also a |
| 1356 | +type of |Object|, and the same rules apply. |
| 1357 | + |
| 1358 | + *E1037* |
1352 | 1359 | Using "is" or "isnot" with a |List|, |Tuple|, |Dictionary| or |Blob| checks |
1353 | 1360 | whether the expressions are referring to the same |List|, |Tuple|, |
1354 | 1361 | |Dictionary| or |Blob| instance. A copy of a |List| or |Tuple| is different |
@@ -2247,7 +2254,14 @@ v:clipmethod The current method of accessing the clipboard that is being |
2247 | 2254 | x11 X11 selections are being used. |
2248 | 2255 | none The above methods are unavailable or |
2249 | 2256 | cannot be used. |
2250 | | - See 'clipmethod' for more details. |
| 2257 | + If it is set to a value not in the above list, then a |
| 2258 | + clipboard provider with the given name is being used for the |
| 2259 | + clipboard functionality. See 'clipmethod' for more details. |
| 2260 | + |
| 2261 | + *v:clipproviders* |
| 2262 | +v:clipproviders |
| 2263 | + A dictionary containing clipboard providers, see |
| 2264 | + |clipboard-providers| for more information. |
2251 | 2265 |
|
2252 | 2266 | *v:cmdarg* *cmdarg-variable* |
2253 | 2267 | v:cmdarg This variable is used for two purposes: |
@@ -2381,7 +2395,7 @@ v:echospace Number of screen cells that can be used for an `:echo` message |
2381 | 2395 | available above the last line. |
2382 | 2396 |
|
2383 | 2397 | *v:errmsg* *errmsg-variable* |
2384 | | -v:errmsg Last error message that occurred (not neccessarily displayed). |
| 2398 | +v:errmsg Last error message that occurred (not necessarily displayed). |
2385 | 2399 | It's allowed to set this variable. Example: > |
2386 | 2400 | :let v:errmsg = "" |
2387 | 2401 | :silent! next |
@@ -3833,7 +3847,7 @@ text... |
3833 | 3847 | when the screen is redrawn. |
3834 | 3848 |
|
3835 | 3849 | *:echow* *:echowin* *:echowindow* |
3836 | | -:[N]echow[indow] {expr1} .. |
| 3850 | +:[N]echow[indow] {expr1} ... |
3837 | 3851 | Like |:echomsg| but when the messages popup window is |
3838 | 3852 | available the message is displayed there. This means |
3839 | 3853 | it will show for three seconds and avoid a |
@@ -5266,5 +5280,117 @@ Usage: >vim |
5266 | 5280 | :call dist#vim9#Launch(<args>) |
5267 | 5281 | :Launch <app> <args>. |
5268 | 5282 | < |
5269 | | - |
| 5283 | +============================================================================== |
| 5284 | +15. Clipboard providers *clipboard-providers* |
| 5285 | + |
| 5286 | +The clipboard provider feature allows the "+" |quoteplus| and "*" |quotestar| |
| 5287 | +registers to be overridden by custom Vim script functions. There can be |
| 5288 | +multiple providers, and Vim chooses which one to use based on 'clipmethod'. |
| 5289 | + |
| 5290 | +Despite the name, it should be treated separate from the clipboard |
| 5291 | +functionality. It essentially overrides the existing behaviour of the |
| 5292 | +clipboard registers. |
| 5293 | + |
| 5294 | + *clipboard-providers-clipboard* |
| 5295 | +The clipboard provider feature will respect the "unnamed" and "unnamedplus" |
| 5296 | +values in the 'clipboard' option. Any other value will be ignored. |
| 5297 | + |
| 5298 | + *clipboard-providers-no-clipboard* |
| 5299 | +If the |+clipboard| feature is not enabled, then the "+" and "*" registers |
| 5300 | +will not be enabled/available unless |v:clipmethod| is set to a provider. If |
| 5301 | +it is set to a provider, then the clipboard registers will be exposed despite |
| 5302 | +not having the |+clipboard| feature. |
| 5303 | + |
| 5304 | + *clipboard-providers-plus* |
| 5305 | +If on a platform that only has the "*" register, then the "+" register will |
| 5306 | +only be available when |v:clipmethod| is set to a provider. If you want to |
| 5307 | +check if the "+" is available for use, it can be checked with: > |
| 5308 | + if has('unnamedplus') |
| 5309 | +< |
| 5310 | + *clipboard-providers-clipmethod* |
| 5311 | +To integrate the providers with Vim's clipboard functionality, the |
| 5312 | +'clipmethod' option is used on all platforms. The names of clipboard |
| 5313 | +providers should be put inside the option, and if Vim chooses it, then it |
| 5314 | +overrides the "+" and "*" registers. Note that the "+" and "*" will not be |
| 5315 | +saved in the viminfo at all. |
| 5316 | + |
| 5317 | + *clipboard-providers-define* |
| 5318 | +To define a clipboard provider, the |v:clipproviders| vim variable is used. It |
| 5319 | +is a |dict| where each key is the clipboard provider name, and the value is |
| 5320 | +another |dict| declaring the "available", "copy", and "paste" callbacks: >vim |
| 5321 | + let v:clipproviders["myprovider"] = { |
| 5322 | + \ "available": function("Available"), |
| 5323 | + \ "paste": { |
| 5324 | + \ "+": function("Paste"), |
| 5325 | + \ "*": function("Paste") |
| 5326 | + \ }, |
| 5327 | + \ "copy": { |
| 5328 | + \ "+": function("Copy"), |
| 5329 | + \ "*": function("Copy") |
| 5330 | + \ } |
| 5331 | + \ } |
| 5332 | + set clipmethod^=myprovider |
| 5333 | +< |
| 5334 | +Each callback can either be a name of a function in a string, a |Funcref|, or |
| 5335 | +a |lambda| expression. |
| 5336 | + |
| 5337 | +With the exception of the "available" callback if a callback is not provided, |
| 5338 | +Vim will not invoke anything, and this is not an error. |
| 5339 | + |
| 5340 | + *clipboard-providers-textlock* |
| 5341 | +In both the "paste" and "copy" callbacks, it is not allowed to change the |
| 5342 | +buffer text, see |textlock|. |
| 5343 | + |
| 5344 | + *clipboard-providers-available* |
| 5345 | +The "available" callback is optional, does not take any arguments and should |
| 5346 | +return a |boolean| or non-zero number, which tells Vim if it is available |
| 5347 | +for use. If it is not, then Vim skips over it and tries the next 'clipmethod' |
| 5348 | +value. If the "available" callback is not provided, Vim assumes the provider |
| 5349 | +is always available for use (true). |
| 5350 | + |
| 5351 | + *clipboard-providers-paste* |
| 5352 | +The "paste" callback takes the following arguments in the following order: |
| 5353 | + 1. Name of the register being accessed, either "+" or "*". |
| 5354 | + |
| 5355 | +It should return a |list| or |tuple| containing the following elements in |
| 5356 | +order: |
| 5357 | + 1. Register type (and optional width) conforming to |setreg()|. If it |
| 5358 | + is an empty string, then the type is automatically chosen. |
| 5359 | + 2. A |list| of strings to return to Vim, each representing a line. |
| 5360 | + |
| 5361 | + *clipboard-providers-copy* |
| 5362 | +The "copy" callback returns nothing and takes the following arguments in the |
| 5363 | +following order: |
| 5364 | + 1. Name of the register being accessed, either "+" or "*". |
| 5365 | + 2. Register type conforming to |getregtype()| |
| 5366 | + 3. List of strings to use, each representing a line. |
| 5367 | + |
| 5368 | +Below is a sample script that makes use of the clipboard provider feature: >vim |
| 5369 | + func Available() |
| 5370 | + return v:true |
| 5371 | + endfunc |
| 5372 | + |
| 5373 | + func Copy(reg, type, str) |
| 5374 | + echom "Register: " .. a:reg |
| 5375 | + echom "Register type: " .. a:type |
| 5376 | + echom "Contents: " .. string(a:str) |
| 5377 | + endfunc |
| 5378 | + |
| 5379 | + func Paste(reg) |
| 5380 | + return ("b40", ["this", "is", "the", a:reg, "register!"]) |
| 5381 | + endfunc |
| 5382 | + |
| 5383 | + let v:clipproviders["test"] = { |
| 5384 | + \ "available": function("Available"), |
| 5385 | + \ "copy": { |
| 5386 | + \ "+": function("Copy"), |
| 5387 | + \ "*": function("Copy") |
| 5388 | + \ }, |
| 5389 | + \ "paste": { |
| 5390 | + \ "+": function("Paste"), |
| 5391 | + \ "*": function("Paste") |
| 5392 | + \ } |
| 5393 | + \ } |
| 5394 | + set clipmethod^=test |
| 5395 | +< |
5270 | 5396 | vim:tw=78:ts=8:noet:ft=help:norl: |
0 commit comments