Merge pull request #2687 from h-east/update-map

Update map.{txt,jax}

Author: h-east

doc/map.jax

@@ -1,4 +1,4 @@
-*map.txt*	For Vim バージョン 9.2.  Last change: 2026 May 23
+*map.txt*	For Vim バージョン 9.2.  Last change: 2026 Jun 13
 
 
 		  VIM リファレンスマニュアル	by Bram Moolenaar
@@ -1604,6 +1604,11 @@ non-id	  マッチした場所の前がスペース、タブ、行頭、挿入
 
 	:MyCmd2 two values
 
+引数エリア全体をそのまま単一の値として扱いたい場合は、-nargs=_ を使用する。複
+数の引数が必要で、かつ個々の引数自体にスペースが含まれる可能性がある場合 (その
+ため、分割処理を継続させる必要がある場合) は、代わりに -nargs=+/* を、
+|:command-completeopt| (-completeopt=escape) と組み合わせて使用する。
+
 
 Note: 引数は Vim script の式としてではなく、テキストとして解釈されることに注
 意。具体的な例を上げると、"s:var" を引数として渡すと、そのコマンドを実行したス
@@ -1737,6 +1742,50 @@ Note: いくつかの補完方法は環境変数を展開します。
 <
 この例はファイル名にスペースが含まれていると機能しません!
 
+							*:command-completeopt*
+"custom" および "customlist" タイプの場合、-completeopt= 属性を使用して特定の
+動作をさらに選択できる。この属性は、オプション名をコンマで区切ったリストを受け
+取る。現在認識されるのは "escape" のみである。
+
+	-completeopt=escape
+		補完関数は、スペース、タブ、バックスラッシュを含むマッチを返す
+		場合がある。このようなマッチがコマンドラインに挿入されると、各
+		スペース、タブ、バックスラッシュの前にバックスラッシュが付加さ
+		れ、値が単一の引数として保持される。表示にはエスケープされてい
+		ない形式が使用される (ポップアップメニュー / ワイルドメニュー
+		/ |getcompletion()|)。補完関数に渡される ArgLead もエスケープ
+		されていない。ユーザーが `:Cmd foo\ b<Tab>` と入力すると、関数
+		は `foo b` で呼び出され、`foo\ b` では呼び出されない。コマンド
+		の置換テキストでは、|<q-args>| と |<f-args>| も同様にエスケー
+		プされていない値を返す。
+
+例: >
+    :func MyComplete(ArgLead, CmdLine, CursorPos)
+    :    return filter(['hello world', 'good morning'],
+    :    \              {_, v -> stridx(v, a:ArgLead) ==# 0})
+    :endfunc
+    :com! -nargs=1 -complete=customlist,MyComplete -completeopt=escape MyCmd
+		\ echo <q-args>
+<
+`:MyCmd <Tab>` の後、ポップアップには `hello world` と `good morning` が表示さ
+れる。`:MyCmd hello\ w<Tab>` と入力すると、ArgLead が `hello w` (スペースの前
+のバックスラッシュが削除される) に設定された状態で MyComplete が呼び出され、
+フィルタが `hello world` を見つけ、`<Tab>` がそれを `:MyCmd hello\ world` とし
+て挿入する。その後、`<q-args>` は論理値 `hello world` に評価される。
+
+-completeopt=escape を指定しない場合、リテラル文字列 `hello world` がコマンド
+ラインに挿入されるため、Vim の引数分割機能はそれを 2 つの引数として扱う。
+
+-completeopt=escape と -nargs=_ (|:command-nargs| を参照) は異なる形態を対象と
+しており、同じ形態に対する競合する解決策ではない:
+	"行全体を 1 つの引数として扱う。エスケープなし"
+			-nargs=_ を使用する
+	"複数の引数があり、それぞれにスペースを含めることができる"
+			-completeopt=escape と一緒に -nargs=+ または -nargs=*
+			を使用する
+-nargs=_ は引数分割を無効にするため、エスケープは効果がない。したがって、
+-nargs=_ と -completeopt=escape を組み合わせるとエラーになる (E1579)。
+
 
 範囲指定 ~
 				*E177* *E178* *:command-range* *:command-count*

en/map.txt

@@ -1,4 +1,4 @@
-*map.txt*	For Vim version 9.2.  Last change: 2026 May 23
+*map.txt*	For Vim version 9.2.  Last change: 2026 Jun 13
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1620,6 +1620,11 @@ Completing ":MyCmd2 two va<tab>" will complete with: >
 
 	:MyCmd2 two values
 
+Use -nargs=_ when the whole argument area should be taken as a single value
+as-is.  When you need several arguments and an individual argument may itself
+contain spaces (so the splitter must keep running), use -nargs=+/* together
+with |:command-completeopt| (-completeopt=escape) instead.
+
 
 Note that arguments are used as text, not as expressions.  Specifically,
 "s:var" will use the script-local variable in the script where the command was
@@ -1758,6 +1763,50 @@ the 'path' option: >
 <
 This example does not work for file names with spaces!
 
+							*:command-completeopt*
+For the "custom" and "customlist" types you can further opt into specific
+behaviors with the -completeopt= attribute.  It takes a comma-separated list
+of option names; currently only "escape" is recognized:
+
+	-completeopt=escape
+		The completion function may return matches containing spaces,
+		tabs or backslashes.  When such a match is inserted into the
+		command line each space, tab and backslash is preceded by a
+		backslash so the value is preserved as a single argument.  The
+		unescaped form is used for display (popup menu / wildmenu /
+		|getcompletion()|).  The ArgLead passed to the completion
+		function is also unescaped: when the user types
+		`:Cmd foo\ b<Tab>` the function is called with `foo b`, not
+		`foo\ b` .  In the command's replacement text |<q-args>| and
+		|<f-args>| likewise yield the unescaped value.
+
+Example: >
+    :func MyComplete(ArgLead, CmdLine, CursorPos)
+    :    return filter(['hello world', 'good morning'],
+    :    \              {_, v -> stridx(v, a:ArgLead) ==# 0})
+    :endfunc
+    :com! -nargs=1 -complete=customlist,MyComplete -completeopt=escape MyCmd
+		\ echo <q-args>
+<
+After `:MyCmd <Tab>` the popup shows `hello world` and `good morning`.  Typing
+`:MyCmd hello\ w<Tab>` calls MyComplete with ArgLead set to `hello w` (the
+backslash before the space is removed), the filter finds `hello world`, and
+`<Tab>` inserts it as `:MyCmd hello\ world`.  `<q-args>` then evaluates to the
+logical `hello world`.
+
+Without -completeopt=escape the literal string `hello world` would be inserted
+into the command line, so Vim's argument splitter would treat it as two
+arguments.
+
+-completeopt=escape and -nargs=_ (see |:command-nargs|) target different
+shapes; they are not competing solutions for the same one:
+	"whole line as one argument, no escaping"
+			use -nargs=_
+	"multiple arguments, each may contain spaces"
+			use -nargs=+ or -nargs=* with -completeopt=escape
+Because -nargs=_ disables the argument splitter, escaping has no effect there,
+so combining -nargs=_ with -completeopt=escape is an error (E1579).
+
 
 Range handling ~
 				*E177* *E178* *:command-range* *:command-count*