From 85cf5385ddd65abbcacad6c09c90c0fc49cbf34e Mon Sep 17 00:00:00 2001 From: h-east Date: Sat, 18 Oct 2025 15:36:08 +0900 Subject: [PATCH 1/3] Update eval.{txt,jax} --- dict.yml | 3 + doc/eval.jax | 139 +++++++++++++++++++++++++++++- en/eval.txt | 239 ++++++++++++++++++++++++++++++++++++++++----------- 3 files changed, 327 insertions(+), 54 deletions(-) diff --git a/dict.yml b/dict.yml index ec49b8000..2586fba4b 100644 --- a/dict.yml +++ b/dict.yml @@ -119,6 +119,9 @@ Unicode: プログラマ: - プログラマー +プロバイダ: + - プロバイダー + プロパティ: - プロパティー diff --git a/doc/eval.jax b/doc/eval.jax index 3b9553443..b902fab94 100644 --- a/doc/eval.jax +++ b/doc/eval.jax @@ -36,6 +36,7 @@ Note: 式の評価はコンパイル時に無効化できる。無効化され 12. サンドボックス |eval-sandbox| 13. テキストロック |textlock| 14. Vim script ライブラリ |vim-script-library| +15. クリップボードプロバイダ |clipboard-providers| テストのサポートは |testing.txt| を参照。 プロファイリングは |profiling| に記録されている。 @@ -1829,7 +1830,7 @@ Vim script の式(|expr1| を参照)を含めることができる。任意の &l:option ローカルオプション変数 例: > - echo "タブストップは " .. &tabstop .. " です" + echo "タブストップは " .. &tabstop if &insertmode ここにはあらゆるオプション名を使うことができる。|options|を参照。ローカル変数 @@ -2184,11 +2185,16 @@ v:clipmethod 現在使用されているクリップボードへのアクセス wayland Wayland プロトコルが使用されている。 x11 X11 セレクションが使用されている。 gui GUI固有のメソッドが使用されている。 - other 他のメソッドが使用されています。 + other 他のメソッドが使用されている。 none クリップボード機能が無効または使用でき ない。 詳細は 'clipmethod' を参照。 + *v:clipproviders* +v:clipproviders + クリップボードプロバイダを含む辞書。詳細については + |clipboard-providers| を参照。 + *v:cmdarg* *cmdarg-variable* v:cmdarg 2つの目的のために使われる: 1. ファイルの読み書きコマンドに与えられる余分な引数。現在のと @@ -2215,7 +2221,7 @@ v:collate 現在のロケール設定での実行環境の照合順序。これ を使う。 |multi-lang| を参照。 *v:colornames* -v:colornames カラー名を16進数カラー文字列に対応付ける辞書。これらのカラー名 +v:colornames カラー名を16進数カラー文字列に対応付ける辞書。これらのカラー名 は、|highlight-guifg|, |highlight-guibg|, |highlight-guisp| の パラメーターで使用できる。 @@ -5107,5 +5113,132 @@ NOTE: のエスケープはユーザーに任される :call dist#vim9#Launch() :Launch . < +============================================================================== +15. クリップボードプロバイダ *clipboard-providers* + +Vim が |+clipboard_provider| 機能 (|+eval| 機能を必要とする) 付きでコンパイル +されている場合、カスタムクリップボードの作成が可能になる。これらのプロバイダは +"+" および "*" レジスタを処理する。Note |+wayland_clipboard| または +|+xterm_clipboard| 機能がコンパイルされていない場合は、"+" レジスタは使用でき +ないことに注意。 + +プロバイダを追加するには、次の形式で |v:clipproviders| 辞書に新しいエントリを +追加する: > + let v:clipproviders["name"] = { + \ "available": function("Available"), + \ "paste": { + \ '+': function("Paste"), " For the + register + \ '*': function("Paste"), " For the * register + \ }, + \ "copy": { + \ '+': function("Copy"), " Same thing as above + \ '*': function("Copy"), + \ }, + \ } + +キーは 'clipmethod' で使用するプロバイダ名である。例えば次の例では、これを使用 +するために "name" を 'clipmethod' に追加する。 > + set clipmethod=name,wayland,x11,gui + +各コールバックは、文字列内の関数名、|Funcref|、または |lambda| 式のいずれかに +なる。 + +note これらの辞書エントリはオプションであることに注意。例えば、"copy" 機能が必 +要ない場合は、単に除外することができる。Vim が何かをヤンク/コピーする場合、何 +も行われない。 + + *clipboard-provider-available* +"available" コールバックは、使用可能なクリップボードレジスタを含む文字列を返す +必要がある。例えば、"+" レジスタのみが使用可能な場合は関数は "+" を返し、"+" +と "*" の両方が使用可能な場合は "+*" を返す。 + + *clipboard-provider-paste* +"paste" コールバックは、最初の引数としてペーストするレジスタ (文字列) を、2 番 +目の引数としてアクセスの種類 (文字列) を受け取る。タプル/リスト、または文字列 +のいずれかを返す。タプル/リストを返す場合は、以下の 2 つの要素を持つ必要がある: + - |setreg()| に準拠したレジスタのタイプ。 + - 文字列のリスト +レジスタのタイプが空文字列の場合、型は自動的に選択される。|setreg()| を参照。 +文字列が返される場合は、"clear" または "previous" のいずれかになる。"clear" は +レジスタをクリアし、"previous" はレジスタの前の (または現在の) 内容を使用する +(表示方法によって異なる)。 + +2 番目の引数であるアクセスタイプは、"explicit" または "implicit" のいずれかに +なる。"explicit" とは、テキストを挿入したり、|getreg()| を呼び出したりなど、 +ユーザーがクリップボードに直接アクセスしていることを意味する。"implicit" と +は、|:registers| が呼び出されたときや、無関係な操作によって Vim がクリップボー +ドにアクセスしたときなど、クリップボードが間接的にアクセスされていることを意味 +する。 +Vim の一部の操作は暗黙的にクリップボードに間接的にアクセスするため、これは便利 +である。例えば、OSC52 コマンド (エスケープコードを介してクリップボードにアクセ +スする) のプロバイダを作成する場合などである。多くの端末では、Vim がクリップ +ボードにアクセスするかどうか確認メッセージが表示される。これは、バックグラウン +ドでクリップボードにアクセスする操作を行うたびに端末が許可を求めるため、非常に +煩わしい場合がある。暗黙的なアクセスを処理する良い方法は、レジスタの内容を変更 +せずに "previous" を返すことである。 + + *clipboard-provider-copy* +"copy" コールバックは何も返さず、指定された引数を順番に受け取る: + - 操作対象のレジスタ + - |getregtype()| に準拠したレジスタの型。 + - コピーする文字列のリスト + +プロバイダは与えられた情報を使って自由に操作できる。この関数は、クリップボード +レジスタ(群)を変更するリクエストごとに呼び出される。 + + *clipboard-provider-textlock* +"paste" および "copy" コールバックの両方で、バッファのテキストを変更することは +できない。|textlock| を参照。 + + *clipboard-provider-example* +以下は、OSC52 コマンドを通じてクリップボードプロバイダ機能を使用するスクリプト +の例: >vim + + func Available() + return "*" + endfunc + + func Paste(reg, type) + " 暗黙的なアクセスの場合は何もしない + if a:type == "implicit" + return "previous" + endif + + augroup OSC + autocmd! + autocmd TermResponseAll osc ++once call feedkeys("\", '!') + augroup END + + " コマンドを送信 + call echoraw("\]52;;?\\\") + + " 自動コマンドがトリガーされるまで待つ + while getchar(-1) != "\" + endwhile + + autocmd! OSC + + " base64 データを取り出す + let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') + + return ("", blob2str(base64_decode(l:stuff))) + endfunc + + func Copy(reg, type, lines) + call echoraw("\]52;c;" .. + \ base64_encode(str2blob(a:lines)) .. "\\\") + endfunc + let v:clipproviders["myosc"] = { + \ "available": function("Available"), + \ "paste": { + \ '*': function("Paste") + \ }, + \ "copy": { + \ '*': function("Copy") + \ }, + \ } + set clipmethod=myosc + +< vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/en/eval.txt b/en/eval.txt index ec79e9670..448220e92 100644 --- a/en/eval.txt +++ b/en/eval.txt @@ -38,6 +38,7 @@ a remark is given. 12. The sandbox |eval-sandbox| 13. Textlock |textlock| 14. Vim script library |vim-script-library| +15. Clipboard providers |clipboard-providers| Testing support is documented in |testing.txt|. Profiling is documented at |profiling|. @@ -86,7 +87,7 @@ Job Used for a job, see |job_start()|. *Job* *Jobs* Channel Used for a channel, see |ch_open()|. *Channel* *Channels* -Blob Binary Large Object. Stores any sequence of bytes. See |Blob| +Blob Binary Large Object. Stores any sequence of bytes. See |Blob| for details Example: 0zFF00ED015DAF 0z is an empty Blob. @@ -1020,7 +1021,7 @@ Blob modification ~ To change a specific byte of a blob use |:let| this way: > :let blob[4] = 0x44 -When the index is just one beyond the end of the Blob, it is appended. Any +When the index is just one beyond the end of the Blob, it is appended. Any higher index is an error. To change a sequence of bytes the [:] notation can be used: > @@ -1536,8 +1537,8 @@ byte under the cursor: > In |Vim9| script: *E1147* *E1148* If expr10 is a String this results in a String that contains the expr1'th -single character (including any composing characters) from expr10. To use byte -indexes use |strpart()|. +single character (including any composing characters) from expr10. To use +byte indexes use |strpart()|. Index zero gives the first byte or character. Careful: text column numbers start with one! @@ -1595,7 +1596,7 @@ Examples: > *slice* If expr10 is a |List| this results in a new |List| with the items indicated by the indexes expr1a and expr1b. This works like with a String, as explained -just above. Also see |sublist| below. Examples: > +just above. Also see |sublist| below. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item :let l = mylist[:] " shallow copy of a List @@ -1786,8 +1787,8 @@ A string constant accepts these special characters: Don't use to get a UTF-8 character, use \uxxxx as mentioned above. \<*xxx> Like \ but prepends a modifier instead of including it in the - character. E.g. "\" is one character 0x17 while "\<*C-w>" is four - bytes: 3 for the CTRL modifier and then character "W". + character. E.g. "\" is one character 0x17 while "\<*C-w>" is + four bytes: 3 for the CTRL modifier and then character "W". Note that "\xff" is stored as the byte 255, which may be invalid in some encodings. Use "\u00ff" to store character 255 according to the current value @@ -2185,7 +2186,7 @@ variables for each buffer. Use local buffer variables instead |b:var|. PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:* *E963* *E1063* Most variables are read-only, when a variable can be set by the user, it will -be mentioned at the variable description below. The type cannot be changed. +be mentioned at the variable description below. The type cannot be changed. *v:argv* *argv-variable* v:argv The command line arguments Vim was invoked with. This is a @@ -2198,11 +2199,11 @@ v:beval_col The number of the column, over which the mouse pointer is. Only valid while evaluating the 'balloonexpr' option. *v:beval_bufnr* *beval_bufnr-variable* -v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only - valid while evaluating the 'balloonexpr' option. +v:beval_bufnr The number of the buffer, over which the mouse pointer is. + Only valid while evaluating the 'balloonexpr' option. *v:beval_lnum* *beval_lnum-variable* -v:beval_lnum The number of the line, over which the mouse pointer is. Only +v:beval_lnum The number of the line, over which the mouse pointer is. Only valid while evaluating the 'balloonexpr' option. *v:beval_text* *beval_text-variable* @@ -2215,9 +2216,9 @@ v:beval_text The text under or after the mouse pointer. Usually a word as Only valid while evaluating the 'balloonexpr' option. *v:beval_winnr* *beval_winnr-variable* -v:beval_winnr The number of the window, over which the mouse pointer is. Only - valid while evaluating the 'balloonexpr' option. The first - window has number zero (unlike most other places where a +v:beval_winnr The number of the window, over which the mouse pointer is. + Only valid while evaluating the 'balloonexpr' option. The + first window has number zero (unlike most other places where a window gets a number). *v:beval_winid* *beval_winid-variable* @@ -2251,6 +2252,11 @@ v:clipmethod The current method of accessing the clipboard that is being unavailable. See 'clipmethod' for more details. + *v:clipproviders* +v:clipproviders + A dictionary containing clipboard providers, see + |clipboard-providers| for more information. + *v:cmdarg* *cmdarg-variable* v:cmdarg This variable is used for two purposes: 1. The extra arguments given to a file read/write command. @@ -2280,8 +2286,8 @@ v:collate The current locale setting for collation order of the runtime See |multi-lang|. *v:colornames* -v:colornames A dictionary that maps color names to hex color strings. These - color names can be used with the |highlight-guifg|, +v:colornames A dictionary that maps color names to hex color strings. + These color names can be used with the |highlight-guifg|, |highlight-guibg|, and |highlight-guisp| parameters. The key values in the dictionary (the color names) should be @@ -2289,20 +2295,20 @@ v:colornames A dictionary that maps color names to hex color strings. These name. Updating an entry in v:colornames has no immediate effect on - the syntax highlighting. The highlight commands (probably in a - colorscheme script) need to be re-evaluated in order to use - the updated color values. For example: > + the syntax highlighting. The highlight commands (probably in + a colorscheme script) need to be re-evaluated in order to use + the updated color values. For example: > :let v:colornames['fuscia'] = '#cf3ab4' :let v:colornames['mauve'] = '#915f6d' :highlight Normal guifg=fuscia guibg=mauve < This cannot be used to override the |cterm-colors| but it can - be used to override other colors. For example, the X11 colors + be used to override other colors. For example, the X11 colors defined in the `colors/lists/default.vim` (previously defined - in |rgb.txt|). When defining new color names in a plugin, the + in |rgb.txt|). When defining new color names in a plugin, the recommended practice is to set a color entry only when it does - not already exist. For example: > + not already exist. For example: > :call extend(v:colornames, { \ 'fuscia': '#cf3ab4', @@ -2310,20 +2316,20 @@ v:colornames A dictionary that maps color names to hex color strings. These \ }, 'keep') < Using |extend()| with the 'keep' option updates each color only - if it did not exist in |v:colornames|. Doing so allows the + if it did not exist in |v:colornames|. Doing so allows the user to choose the precise color value for a common name by setting it in their |.vimrc|. It is possible to remove entries from this dictionary but doing so is NOT recommended, because it is disruptive to - other scripts. It is also unlikely to achieve the desired + other scripts. It is also unlikely to achieve the desired result because the |:colorscheme| and |:highlight| commands will both automatically load all `colors/lists/default.vim` color scripts. You can make changes to that file, but make sure to add new - keys instead of updating existing ones, otherwise Vim will skip - loading the file (thinking it hasn't been changed). + keys instead of updating existing ones, otherwise Vim will + skip loading the file (thinking it hasn't been changed). *v:completed_item* *completed_item-variable* v:completed_item @@ -2426,7 +2432,7 @@ v:exception The value of the exception most recently caught and not < Output: "caught oops". *v:false* *false-variable* -v:false A Number with value zero. Used to put "false" in JSON. See +v:false A Number with value zero. Used to put "false" in JSON. See |json_encode()|. When used as a string this evaluates to "v:false". > echo v:false @@ -2519,7 +2525,7 @@ v:foldstart Used for 'foldtext': first line of closed fold. *v:hlsearch* *hlsearch-variable* v:hlsearch Variable that indicates whether search highlighting is on. Setting it makes sense only if 'hlsearch' is enabled which - requires |+extra_search|. Setting this variable to zero acts + requires |+extra_search|. Setting this variable to zero acts like the |:nohlsearch| command, setting it to one acts like > let &hlsearch = &hlsearch < Note that the value is restored when returning from a @@ -2587,7 +2593,7 @@ v:mouse_col Column number for a mouse click obtained with |getchar()|. value is zero when there was no mouse button click. *v:none* *none-variable* *None* -v:none An empty String. Used to put an empty item in JSON. See +v:none An empty String. Used to put an empty item in JSON. See |json_encode()|. This can also be used as a function argument to use the default value, see |none-function_argument|. @@ -2601,7 +2607,7 @@ v:none An empty String. Used to put an empty item in JSON. See an error. Instead, use `is v:none` and `isnot v:none` . *v:null* *null-variable* -v:null An empty String. Used to put "null" in JSON. See +v:null An empty String. Used to put "null" in JSON. See |json_encode()|. When used as a number this evaluates to zero. When used as a string this evaluates to "v:null". > @@ -2637,27 +2643,27 @@ v:oldfiles List of file names that is loaded from the |viminfo| file on {only when compiled with the |+viminfo| feature} *v:option_new* -v:option_new New value of the option. Valid while executing an |OptionSet| +v:option_new New value of the option. Valid while executing an |OptionSet| autocommand. *v:option_old* -v:option_old Old value of the option. Valid while executing an |OptionSet| - autocommand. Depending on the command used for setting and the - kind of option this is either the local old value or the +v:option_old Old value of the option. Valid while executing an |OptionSet| + autocommand. Depending on the command used for setting and + the kind of option this is either the local old value or the global old value. *v:option_oldlocal* v:option_oldlocal - Old local value of the option. Valid while executing an + Old local value of the option. Valid while executing an |OptionSet| autocommand. *v:option_oldglobal* v:option_oldglobal - Old global value of the option. Valid while executing an + Old global value of the option. Valid while executing an |OptionSet| autocommand. *v:option_type* -v:option_type Scope of the set command. Valid while executing an - |OptionSet| autocommand. Can be either "global" or "local" +v:option_type Scope of the set command. Valid while executing an + |OptionSet| autocommand. Can be either "global" or "local" *v:option_command* v:option_command - Command used to set the option. Valid while executing an + Command used to set the option. Valid while executing an |OptionSet| autocommand. value option was set via ~ "setlocal" |:setlocal| or ":let l:xxx" @@ -2704,7 +2710,7 @@ v:progpath Contains the command with which Vim was invoked, in a form To get the full path use: > echo exepath(v:progpath) < If the command has a relative path it will be expanded to the - full path, so that it still works after `:cd`. Thus starting + full path, so that it still works after `:cd`. Thus starting "./vim" results in "/home/user/path/to/vim/src/vim". On Linux and other systems it will always be the full path. On Mac it may just be "vim" and using exepath() as mentioned @@ -2871,9 +2877,9 @@ v:termresponse The escape sequence returned by the terminal for the |t_RV| terminal. The TermResponseAll event is also fired, with set to "version". You can use |terminalprops()| to see what Vim figured out about the terminal. - The response from a new xterm is: "[> Pp ; Pv ; Pc c". Pp - is the terminal type: 0 for vt100 and 1 for vt220. Pv is the - patch level (since this was introduced in patch 95, it's + The response from a new xterm is: "[> Pp ; Pv ; Pc c". + Pp is the terminal type: 0 for vt100 and 1 for vt220. Pv is + the patch level (since this was introduced in patch 95, it's always 95 or higher). Pc is always zero. If Pv is 141 or higher then Vim will try to request terminal codes. This only works with xterm |xterm-codes|. @@ -2882,7 +2888,7 @@ v:termresponse The escape sequence returned by the terminal for the |t_RV| *v:termblinkresp* *termblinkresp-variable* v:termblinkresp The escape sequence returned by the terminal for the |t_RC| termcap entry. This is used to find out whether the terminal - cursor is blinking. This is used by |term_getcursor()|. When + cursor is blinking. This is used by |term_getcursor()|. When this variable is set, the TermResponseAll autocommand event is fired, with set to "cursorblink". @@ -2951,7 +2957,7 @@ v:throwpoint The point where the exception most recently caught and not < Output: "Exception from test.vim, line 2" *v:true* *true-variable* -v:true A Number with value one. Used to put "true" in JSON. See +v:true A Number with value one. Used to put "true" in JSON. See |json_encode()|. When used as a string this evaluates to "v:true". > echo v:true @@ -2991,7 +2997,8 @@ v:vim_did_enter Zero until most of startup is done. It is set to one just before |VimEnter| autocommands are triggered. *v:warningmsg* *warningmsg-variable* -v:warningmsg Last given warning message. It's allowed to set this variable. +v:warningmsg Last given warning message. It's allowed to set this + variable. *v:wayland_display* *wayland_display-variable* v:wayland_display @@ -3289,7 +3296,8 @@ text... END < There can be multiple Vim expressions in a single line but an expression cannot span multiple lines. If any - expression evaluation fails, then the assignment fails. + expression evaluation fails, then the assignment + fails. {endmarker} must not contain white space. {endmarker} cannot start with a lower case character. @@ -5212,7 +5220,7 @@ $VIMRUNTIME/plugin/openPlugin.vim dist#vim9#Open(file: string) ~ Opens `path` with the system default handler (macOS `open`, Windows -`explorer.exe`, Linux `xdg-open`, …). If the variable |g:Openprg| exists the +`explorer.exe`, Linux `xdg-open`, …). If the variable |g:Openprg| exists the string specified in the variable is used instead. The |:Open| user command uses file completion for its argument. @@ -5224,11 +5232,11 @@ This function is by default called using the gx mapping. In visual mode tries to open the visually selected text. Associated setting variables: -`g:gx_word`: control how gx picks up the text under the cursor. Uses +`g:gx_word`: control how gx picks up the text under the cursor. Uses `g:netrw_gx` as a fallback for backward compatibility. (default: ``) -`g:nogx`: disables the gx mapping. Uses `g:netrw_nogx` as a fallback for +`g:nogx`: disables the gx mapping. Uses `g:netrw_nogx` as a fallback for backward compatibility. (default: `unset`) @@ -5242,7 +5250,7 @@ Usage: >vim *dist#vim9#Launch()* *:Launch* dist#vim9#Launch(file: string) ~ -Launches with the appropriate system programs. Intended for launching +Launches with the appropriate system programs. Intended for launching GUI programs within Vim. The |:Launch| user command uses shell completion for its first argument. @@ -5261,5 +5269,134 @@ Usage: >vim :call dist#vim9#Launch() :Launch . < +============================================================================== +15. Clipboard providers *clipboard-providers* + +When Vim is compiled with the |+clipboard_provider| feature, which requires +the |+eval| feature, creating custom clipboards is possible. These providers +handle the "+" and "*" registers. Note that if |+wayland_clipboard| or +|+xterm_clipboard| features are not compiled in, then the "+" register will +not be available. + +To add a provider, add a new entry to the |v:clipproviders| dictionary, in the +format of: > + let v:clipproviders["name"] = { + \ "available": function("Available"), + \ "paste": { + \ '+': function("Paste"), " For the + register + \ '*': function("Paste"), " For the * register + \ }, + \ "copy": { + \ '+': function("Copy"), " Same thing as above + \ '*': function("Copy"), + \ }, + \ } + +The key is the provider name, which should be used in 'clipmethod', for +example in the following example, you would add "name" to 'clipmethod' in +order to use it. > + set clipmethod=name,wayland,x11,gui + +Each callback can either be a name of a function in a string, a |Funcref|, or +a |lambda| expression. + +Note that these dictionary entries are optional, for example, if you don't +care about the "copy" functions, then you can simply exclude them. When Vim +yanks/copies something, then simply nothing will be done. + + *clipboard-provider-available* +The "available" callback should return a string, which should contain which +clipboard registers are available. For example, if the "+" register is only +available, then the function would return "+", or if both "+" and "*" are +available, then return "+*". + + *clipboard-provider-paste* +The "paste" callback takes a first argument which is the register being put +(string), and a second argument which is the type of access (string). It +should return either a tuple/list or string. If a tuple/list is returned, it +should have two elements: + - The register type conforming to |setreg()|. + - A list of strings +If the register type is an empty string, then the type is automatically +chosen, see |setreg()|. If a string is returned, then it can either be "clear" +or "previous". "clear" makes Vim clear the register, and "previous" makes Vim +use the previous register contents (or current depending on how you view it). + +The second argument, the access type, can either be "explicit" or "implicit". +"explicit" means that the user is directly accessing the clipboard, such as +putting text, or calling |getreg()|; "implicit" means that the clipboard is +being accessed indirectly, such when |:registers| is called, or when an +unrelated operation causes Vim to access the clipboard. + +This is useful since some operations in Vim implicity access the clipboard +indirectly. For example, if when you want to create a provider for the OSC52 +command (accessing the clipboard via an escape code). Many terminals show a +confirmation if you want Vim to access the clipboard. This can be very +annoying with the terminal asking for permission everytime you do something +that accesses the clipboard behind the scenes. A good way to handle implicit +access is to return "previous", which leaves the register contents unchanged. + + *clipboard-provider-copy* +The "copy" callback returns nothing, and takes the given arguments in order: + - The register being operated on + - The register type, conforming to |getregtype()| + - A list of strings to copy + +The provider can do whatever it wants with the given information. This +function is called on every request to change the clipboard register(s). + + *clipboard-provider-textlock* +In both the "paste" and "copy" callbacks, it is not allowed to change the +buffer text, see |textlock|. + + *clipboard-provider-example* +Here is an example script that uses the clipboard provider feature through the +OSC52 command: >vim + + func Available() + return "*" + endfunc + + func Paste(reg, type) + " If implicit access, don't do anything + if a:type == "implicit" + return "previous" + endif + + augroup OSC + autocmd! + autocmd TermResponseAll osc ++once call feedkeys("\", '!') + augroup END + + " Send command + call echoraw("\]52;;?\\\") + + " Wait until autocmd is triggered + while getchar(-1) != "\" + endwhile + + autocmd! OSC + + " Extract the base64 stuff + let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') + + return ("", blob2str(base64_decode(l:stuff))) + endfunc + + func Copy(reg, type, lines) + call echoraw("\]52;c;" .. + \ base64_encode(str2blob(a:lines)) .. "\\\") + endfunc + let v:clipproviders["myosc"] = { + \ "available": function("Available"), + \ "paste": { + \ '*': function("Paste") + \ }, + \ "copy": { + \ '*': function("Copy") + \ }, + \ } + set clipmethod=myosc +< vim:tw=78:ts=8:noet:ft=help:norl: From 71c57252f57a2b21ad4b5199f5188be0d58720ae Mon Sep 17 00:00:00 2001 From: h-east Date: Sun, 19 Oct 2025 09:23:15 +0900 Subject: [PATCH 2/3] Update by original --- en/eval.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/en/eval.txt b/en/eval.txt index 448220e92..b5dc5671d 100644 --- a/en/eval.txt +++ b/en/eval.txt @@ -5356,30 +5356,30 @@ OSC52 command: >vim func Available() return "*" endfunc - + func Paste(reg, type) " If implicit access, don't do anything if a:type == "implicit" return "previous" endif - + augroup OSC autocmd! autocmd TermResponseAll osc ++once call feedkeys("\", '!') augroup END - + " Send command call echoraw("\]52;;?\\\") - + " Wait until autocmd is triggered while getchar(-1) != "\" endwhile - + autocmd! OSC - + " Extract the base64 stuff let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') - + return ("", blob2str(base64_decode(l:stuff))) endfunc From 0740ea95c15537d3a05f18360a999ca038b9bba0 Mon Sep 17 00:00:00 2001 From: h-east Date: Tue, 28 Oct 2025 23:46:21 +0900 Subject: [PATCH 3/3] Update by original --- doc/eval.jax | 147 +++----------------------------------------------- en/eval.txt | 150 +++------------------------------------------------ 2 files changed, 13 insertions(+), 284 deletions(-) diff --git a/doc/eval.jax b/doc/eval.jax index b902fab94..d0ab5a80c 100644 --- a/doc/eval.jax +++ b/doc/eval.jax @@ -36,7 +36,6 @@ Note: 式の評価はコンパイル時に無効化できる。無効化され 12. サンドボックス |eval-sandbox| 13. テキストロック |textlock| 14. Vim script ライブラリ |vim-script-library| -15. クリップボードプロバイダ |clipboard-providers| テストのサポートは |testing.txt| を参照。 プロファイリングは |profiling| に記録されている。 @@ -2184,17 +2183,9 @@ v:clipmethod 現在使用されているクリップボードへのアクセス かの値になる: wayland Wayland プロトコルが使用されている。 x11 X11 セレクションが使用されている。 - gui GUI固有のメソッドが使用されている。 - other 他のメソッドが使用されている。 - none クリップボード機能が無効または使用でき - ない。 + none 上記メソッドが無効または使用できない。 詳細は 'clipmethod' を参照。 - *v:clipproviders* -v:clipproviders - クリップボードプロバイダを含む辞書。詳細については - |clipboard-providers| を参照。 - *v:cmdarg* *cmdarg-variable* v:cmdarg 2つの目的のために使われる: 1. ファイルの読み書きコマンドに与えられる余分な引数。現在のと @@ -3224,8 +3215,9 @@ text... endif END < 結果: ["if ok", " echo 'done'", "endif"] - マーカーは "let" のインデントと並ばなければならず、最 - 初の行のインデントは全てのテキスト行から取り除かれる。 + エンドマーカーは "let" のインデントと並ばなければなら + ず、最初の行のインデントは全てのテキスト行から取り除か + れる。 具体例: 最初の空でないテキスト行の先頭のインデントと完 全に一致する全ての先頭のインデントは入力行から削除され る。`let` の前の先頭のインデントと完全に一致する先頭の @@ -3314,10 +3306,10 @@ text... :cons[t] {var-name} = {expr1} :cons[t] [{name1}, {name2}, ...] = {expr1} :cons[t] [{name}, ..., ; {lastname}] = {expr1} -:cons[t] {var-name} =<< [trim] [eval] {marker} +:cons[t] {var-name} =<< [trim] [eval] {endmarker} text... text... -{marker} +{endmarker} |:let|に似ているが、加えて、値がセットされたあとに変数 がロックされる。これは、ロックされた変数と同じで、 |:let|のすぐ後に|:lockvar|を使うことで変数をロックする @@ -5113,132 +5105,5 @@ NOTE: のエスケープはユーザーに任される :call dist#vim9#Launch() :Launch . < -============================================================================== -15. クリップボードプロバイダ *clipboard-providers* - -Vim が |+clipboard_provider| 機能 (|+eval| 機能を必要とする) 付きでコンパイル -されている場合、カスタムクリップボードの作成が可能になる。これらのプロバイダは -"+" および "*" レジスタを処理する。Note |+wayland_clipboard| または -|+xterm_clipboard| 機能がコンパイルされていない場合は、"+" レジスタは使用でき -ないことに注意。 - -プロバイダを追加するには、次の形式で |v:clipproviders| 辞書に新しいエントリを -追加する: > - let v:clipproviders["name"] = { - \ "available": function("Available"), - \ "paste": { - \ '+': function("Paste"), " For the + register - \ '*': function("Paste"), " For the * register - \ }, - \ "copy": { - \ '+': function("Copy"), " Same thing as above - \ '*': function("Copy"), - \ }, - \ } - -キーは 'clipmethod' で使用するプロバイダ名である。例えば次の例では、これを使用 -するために "name" を 'clipmethod' に追加する。 > - set clipmethod=name,wayland,x11,gui - -各コールバックは、文字列内の関数名、|Funcref|、または |lambda| 式のいずれかに -なる。 -note これらの辞書エントリはオプションであることに注意。例えば、"copy" 機能が必 -要ない場合は、単に除外することができる。Vim が何かをヤンク/コピーする場合、何 -も行われない。 - - *clipboard-provider-available* -"available" コールバックは、使用可能なクリップボードレジスタを含む文字列を返す -必要がある。例えば、"+" レジスタのみが使用可能な場合は関数は "+" を返し、"+" -と "*" の両方が使用可能な場合は "+*" を返す。 - - *clipboard-provider-paste* -"paste" コールバックは、最初の引数としてペーストするレジスタ (文字列) を、2 番 -目の引数としてアクセスの種類 (文字列) を受け取る。タプル/リスト、または文字列 -のいずれかを返す。タプル/リストを返す場合は、以下の 2 つの要素を持つ必要がある: - - |setreg()| に準拠したレジスタのタイプ。 - - 文字列のリスト -レジスタのタイプが空文字列の場合、型は自動的に選択される。|setreg()| を参照。 -文字列が返される場合は、"clear" または "previous" のいずれかになる。"clear" は -レジスタをクリアし、"previous" はレジスタの前の (または現在の) 内容を使用する -(表示方法によって異なる)。 - -2 番目の引数であるアクセスタイプは、"explicit" または "implicit" のいずれかに -なる。"explicit" とは、テキストを挿入したり、|getreg()| を呼び出したりなど、 -ユーザーがクリップボードに直接アクセスしていることを意味する。"implicit" と -は、|:registers| が呼び出されたときや、無関係な操作によって Vim がクリップボー -ドにアクセスしたときなど、クリップボードが間接的にアクセスされていることを意味 -する。 - -Vim の一部の操作は暗黙的にクリップボードに間接的にアクセスするため、これは便利 -である。例えば、OSC52 コマンド (エスケープコードを介してクリップボードにアクセ -スする) のプロバイダを作成する場合などである。多くの端末では、Vim がクリップ -ボードにアクセスするかどうか確認メッセージが表示される。これは、バックグラウン -ドでクリップボードにアクセスする操作を行うたびに端末が許可を求めるため、非常に -煩わしい場合がある。暗黙的なアクセスを処理する良い方法は、レジスタの内容を変更 -せずに "previous" を返すことである。 - - *clipboard-provider-copy* -"copy" コールバックは何も返さず、指定された引数を順番に受け取る: - - 操作対象のレジスタ - - |getregtype()| に準拠したレジスタの型。 - - コピーする文字列のリスト - -プロバイダは与えられた情報を使って自由に操作できる。この関数は、クリップボード -レジスタ(群)を変更するリクエストごとに呼び出される。 - - *clipboard-provider-textlock* -"paste" および "copy" コールバックの両方で、バッファのテキストを変更することは -できない。|textlock| を参照。 - - *clipboard-provider-example* -以下は、OSC52 コマンドを通じてクリップボードプロバイダ機能を使用するスクリプト -の例: >vim - - func Available() - return "*" - endfunc - - func Paste(reg, type) - " 暗黙的なアクセスの場合は何もしない - if a:type == "implicit" - return "previous" - endif - - augroup OSC - autocmd! - autocmd TermResponseAll osc ++once call feedkeys("\", '!') - augroup END - - " コマンドを送信 - call echoraw("\]52;;?\\\") - - " 自動コマンドがトリガーされるまで待つ - while getchar(-1) != "\" - endwhile - - autocmd! OSC - - " base64 データを取り出す - let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') - - return ("", blob2str(base64_decode(l:stuff))) - endfunc - - func Copy(reg, type, lines) - call echoraw("\]52;c;" .. - \ base64_encode(str2blob(a:lines)) .. "\\\") - endfunc - let v:clipproviders["myosc"] = { - \ "available": function("Available"), - \ "paste": { - \ '*': function("Paste") - \ }, - \ "copy": { - \ '*': function("Copy") - \ }, - \ } - set clipmethod=myosc - -< vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/en/eval.txt b/en/eval.txt index b5dc5671d..9140ff235 100644 --- a/en/eval.txt +++ b/en/eval.txt @@ -38,7 +38,6 @@ a remark is given. 12. The sandbox |eval-sandbox| 13. Textlock |textlock| 14. Vim script library |vim-script-library| -15. Clipboard providers |clipboard-providers| Testing support is documented in |testing.txt|. Profiling is documented at |profiling|. @@ -2246,17 +2245,10 @@ v:clipmethod The current method of accessing the clipboard that is being used. Can either have the value of: wayland The Wayland protocol is being used. x11 X11 selections are being used. - gui GUI specific method is being used - other Some other method is being used - none Clipboard functionality is disabled or - unavailable. + none The above methods are unavailable or + cannot be used. See 'clipmethod' for more details. - *v:clipproviders* -v:clipproviders - A dictionary containing clipboard providers, see - |clipboard-providers| for more information. - *v:cmdarg* *cmdarg-variable* v:cmdarg This variable is used for two purposes: 1. The extra arguments given to a file read/write command. @@ -3315,8 +3307,9 @@ text... endif END < Results in: ["if ok", " echo 'done'", "endif"] - The marker must line up with "let" and the indentation - of the first line is removed from all the text lines. + The end marker must line up with "let" and the + indentation of the first line is removed from all the + text lines. Specifically: all the leading indentation exactly matching the leading indentation of the first non-empty text line is stripped from the input lines. @@ -3409,10 +3402,10 @@ text... :cons[t] {var-name} = {expr1} :cons[t] [{name1}, {name2}, ...] = {expr1} :cons[t] [{name}, ..., ; {lastname}] = {expr1} -:cons[t] {var-name} =<< [trim] [eval] {marker} +:cons[t] {var-name} =<< [trim] [eval] {endmarker} text... text... -{marker} +{endmarker} Similar to |:let|, but additionally lock the variable after setting the value. This is the same as locking the variable with |:lockvar| just after |:let|, thus: > @@ -5269,134 +5262,5 @@ Usage: >vim :call dist#vim9#Launch() :Launch . < -============================================================================== -15. Clipboard providers *clipboard-providers* - -When Vim is compiled with the |+clipboard_provider| feature, which requires -the |+eval| feature, creating custom clipboards is possible. These providers -handle the "+" and "*" registers. Note that if |+wayland_clipboard| or -|+xterm_clipboard| features are not compiled in, then the "+" register will -not be available. - -To add a provider, add a new entry to the |v:clipproviders| dictionary, in the -format of: > - let v:clipproviders["name"] = { - \ "available": function("Available"), - \ "paste": { - \ '+': function("Paste"), " For the + register - \ '*': function("Paste"), " For the * register - \ }, - \ "copy": { - \ '+': function("Copy"), " Same thing as above - \ '*': function("Copy"), - \ }, - \ } - -The key is the provider name, which should be used in 'clipmethod', for -example in the following example, you would add "name" to 'clipmethod' in -order to use it. > - set clipmethod=name,wayland,x11,gui - -Each callback can either be a name of a function in a string, a |Funcref|, or -a |lambda| expression. - -Note that these dictionary entries are optional, for example, if you don't -care about the "copy" functions, then you can simply exclude them. When Vim -yanks/copies something, then simply nothing will be done. - - *clipboard-provider-available* -The "available" callback should return a string, which should contain which -clipboard registers are available. For example, if the "+" register is only -available, then the function would return "+", or if both "+" and "*" are -available, then return "+*". - - *clipboard-provider-paste* -The "paste" callback takes a first argument which is the register being put -(string), and a second argument which is the type of access (string). It -should return either a tuple/list or string. If a tuple/list is returned, it -should have two elements: - - The register type conforming to |setreg()|. - - A list of strings -If the register type is an empty string, then the type is automatically -chosen, see |setreg()|. If a string is returned, then it can either be "clear" -or "previous". "clear" makes Vim clear the register, and "previous" makes Vim -use the previous register contents (or current depending on how you view it). - -The second argument, the access type, can either be "explicit" or "implicit". -"explicit" means that the user is directly accessing the clipboard, such as -putting text, or calling |getreg()|; "implicit" means that the clipboard is -being accessed indirectly, such when |:registers| is called, or when an -unrelated operation causes Vim to access the clipboard. - -This is useful since some operations in Vim implicity access the clipboard -indirectly. For example, if when you want to create a provider for the OSC52 -command (accessing the clipboard via an escape code). Many terminals show a -confirmation if you want Vim to access the clipboard. This can be very -annoying with the terminal asking for permission everytime you do something -that accesses the clipboard behind the scenes. A good way to handle implicit -access is to return "previous", which leaves the register contents unchanged. - - *clipboard-provider-copy* -The "copy" callback returns nothing, and takes the given arguments in order: - - The register being operated on - - The register type, conforming to |getregtype()| - - A list of strings to copy - -The provider can do whatever it wants with the given information. This -function is called on every request to change the clipboard register(s). - - *clipboard-provider-textlock* -In both the "paste" and "copy" callbacks, it is not allowed to change the -buffer text, see |textlock|. - - *clipboard-provider-example* -Here is an example script that uses the clipboard provider feature through the -OSC52 command: >vim - - func Available() - return "*" - endfunc - - func Paste(reg, type) - " If implicit access, don't do anything - if a:type == "implicit" - return "previous" - endif - - augroup OSC - autocmd! - autocmd TermResponseAll osc ++once call feedkeys("\", '!') - augroup END - - " Send command - call echoraw("\]52;;?\\\") - - " Wait until autocmd is triggered - while getchar(-1) != "\" - endwhile - - autocmd! OSC - - " Extract the base64 stuff - let l:stuff = matchstr(v:termosc, '52;.\+;\zs[A-Za-z0-9+/=]\+') - - return ("", blob2str(base64_decode(l:stuff))) - endfunc - - func Copy(reg, type, lines) - call echoraw("\]52;c;" .. - \ base64_encode(str2blob(a:lines)) .. "\\\") - endfunc - let v:clipproviders["myosc"] = { - \ "available": function("Available"), - \ "paste": { - \ '*': function("Paste") - \ }, - \ "copy": { - \ '*': function("Copy") - \ }, - \ } - set clipmethod=myosc -< vim:tw=78:ts=8:noet:ft=help:norl: