Merge pull request #1944 from h-east/update-builtin

Update builtin.{txt,jax}

Author: h-east

doc/builtin.jax

@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim バージョン 9.1.  Last change: 2025 Feb 01
+*builtin.txt*	For Vim バージョン 9.1.  Last change: 2025 Feb 06
 
 
 		VIMリファレンスマニュアル    by Bram Moolenaar
@@ -247,11 +247,12 @@ getbufvar({buf}, {varname} [, {def}])
 getcellpixels()			リスト	文字のセルのピクセルサイズを取得する
 getcellwidths()			リスト	文字のセル幅の上書き設定を取得
 getchangelist([{buf}])		リスト	変更リスト要素のリスト
-getchar([{expr}])		数値/文字列	ユーザーから1文字を取得する
+getchar([{expr} [, {opts}]])	数値/文字列
+					ユーザーから1文字を取得する
 getcharmod()			数値	修飾キーの状態を表す数値を取得
 getcharpos({expr})		リスト	カーソル、マーク、その他のカーソル位置
 getcharsearch()			辞書	最後の文字検索を取得
-getcharstr([{expr}])		文字列	ユーザーから1文字を取得する
+getcharstr([{expr} [, {opts}]])	文字列	ユーザーから1文字を取得する
 getcmdcomplpat()		文字列	現在のコマンドライン補完の補完パターン
 					を返す
 getcmdcompltype()		文字列	現在のコマンドライン補完のタイプを返す
@@ -3915,15 +3916,17 @@ getchangelist([{buf}])					*getchangelist()*
 		戻り値の型: list<any>
 
 
-getchar([{expr}])					*getchar()*
+getchar([{expr} [, {opts}]])				*getchar()*
 		ユーザーまたは入力ストリームから1文字を取得する。
-		{expr} が省略された場合、1文字を取得できるまで待つ。
+		{expr} が省略されているか -1 の場合は、1文字を取得できるまで待
+			つ。
 		{expr} が0の場合、1文字を取得できる時だけ取得する。取得できな
 			い時は0を返す。
 		{expr} が1の場合は、1文字を取得できるかを判定するだけである。
 			入力は消費されない。取得できないと判定された時は0を返
 			す。
-		常に文字列として取得したい場合は |getcharstr()| を使用する。
+		常に文字列として取得したい場合は |getcharstr()| を使用するか、
+		{opts} で "number" に |FALSE| を指定する。
 
 		{expr} が省略されたときや {expr} が0のときは、文字全体または特
 		殊キーを返す。それが1文字なら戻り値は数値である。これを文字列
@@ -3932,6 +3935,8 @@ getchar([{expr}])					*getchar()*
 		特殊キーとは0x80(10進数で128)で始まるバイト列からなる文字列で
 		ある。これは文字列 "\<Key>" と同じ値である(例: "\<Left>")。戻
 		り値は文字列であり、修飾キー(shift, control, alt)は含まれない。
+		|keytrans()| は、返された文字列を読み取り可能な形式に変換する
+		ためにも使用できる。
 
 		{expr} が0や Esc が入力された場合は、これがエスケープシーケン
 		スの始まりであるかどうかをVimが知るために待つ間、短い遅延があ
@@ -3943,6 +3948,29 @@ getchar([{expr}])					*getchar()*
 
 		修飾キーを取得するには getcharmod() を使う。
 
+		オプション引数 {opts} は Dict であり、次の項目をサポートする:
+
+			cursor		文字を待機するときのカーソルの動作を指
+					定する文字列。
+					"hide": カーソルを非表示にする。
+					"keep": 現在のカーソルを変更しない。
+					"msg": カーソルをメッセージ領域に移動
+						する。
+					(デフォルト: "msg")
+
+			number		|TRUE| の場合、単一文字を取得するとき
+					に数値を返す。
+					|FALSE| の場合、戻り値は常に文字列に変
+					換され、文字が利用できない場合は (0 で
+					はなく) 空の文字列が返される。
+					(デフォルト: |TRUE|)
+
+			simplify	|TRUE| の場合、可能であれば文字に修飾
+					子を含める。例えば、CTRL-I と <Tab> に
+					同じ値を返す。|FALSE| の場合、文字に修
+					飾子を含めない。
+					(デフォルト: |TRUE|)
+
 		ユーザーがマウスをクリックしたときはマウスイベントを返す。クリッ
 		クした位置は|v:mouse_col|, |v:mouse_lnum|, |v:mouse_winid|,
 		|v:mouse_win|で得られる。|getmousepos()| も使える。マウスの移
@@ -4053,16 +4081,9 @@ getcharsearch()						*getcharsearch()*
 		戻り値の型: dict<any>
 
 
-getcharstr([{expr}])					*getcharstr()*
-		ユーザーまたは入力ストリームから1文字を文字列として取得する。
-		{expr} が省略された場合、1文字を取得できるまで待つ。
-		{expr} が0もしくは偽の場合、1文字を取得できる時だけ取得する。
-			取得できない時は空文字列を返す。
-		{expr} が1もしくは真の場合は、1文字を取得できるかを判定するだ
-			けである。入力は消費されない。取得できないと判定された
-			時は空文字列を返す。
-		結果の数値が文字列に変換される以外は |getchar()| と同様に動作
-		する。
+getcharstr([{expr} [, {opts}]])				*getcharstr()*
+		|getchar()| と同じだが、常に文字列を返し、{opts} では "number"
+		は許可されない。
 
 		戻り値の型: |String|
 
@@ -12454,6 +12475,7 @@ gui_win32s		Win32sのGUIが有効である (Windows 3.1)
 haiku			Haikuバージョン
 hangul_input		ハングル入力サポート
 hpux			HP-UXバージョン
+hurd			GNU/Hurd バージョン
 iconv			iconv()をサポート
 insert_expand		挿入モード時にCTRL-Xの展開がサポートされる (常に true)
 job			|channel| プロセス間通信と |job| ジョブをサポート

en/builtin.txt

@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2025 Feb 01
+*builtin.txt*	For Vim version 9.1.  Last change: 2025 Feb 06
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -228,12 +228,12 @@ getbufvar({buf}, {varname} [, {def}])
 getcellpixels()			List	get character cell pixel size
 getcellwidths()			List	get character cell width overrides
 getchangelist([{buf}])		List	list of change list items
-getchar([{expr}])		Number or String
+getchar([{expr} [, {opts}]])	Number or String
 					get one character from the user
 getcharmod()			Number	modifiers for the last typed character
 getcharpos({expr})		List	position of cursor, mark, etc.
 getcharsearch()			Dict	last character search
-getcharstr([{expr}])		String	get one character from the user
+getcharstr([{expr} [, {opts}]])	String	get one character from the user
 getcmdcomplpat()		String	return the completion pattern of the
 					current command-line completion
 getcmdcompltype()		String	return the type of the current
@@ -3918,14 +3918,16 @@ getchangelist([{buf}])					*getchangelist()*
 		Return type: list<any>
 
 
-getchar([{expr}])					*getchar()*
+getchar([{expr} [, {opts}]])				*getchar()*
 		Get a single character from the user or input stream.
-		If {expr} is omitted, wait until a character is available.
+		If {expr} is omitted or is -1, wait until a character is
+			available.
 		If {expr} is 0, only get a character when one is available.
 			Return zero otherwise.
 		If {expr} is 1, only check if a character is available, it is
 			not consumed.  Return zero if no character available.
-		If you prefer always getting a string use |getcharstr()|.
+		If you prefer always getting a string use |getcharstr()|, or
+		specify |FALSE| as "number" in {opts}.
 
 		Without {expr} and when {expr} is 0 a whole character or
 		special key is returned.  If it is a single character, the
@@ -3935,7 +3937,8 @@ getchar([{expr}])					*getchar()*
 		starting with 0x80 (decimal: 128).  This is the same value as
 		the String "\<Key>", e.g., "\<Left>".  The returned value is
 		also a String when a modifier (shift, control, alt) was used
-		that is not included in the character.
+		that is not included in the character.  |keytrans()| can also
+		be used to convert a returned String into a readable form.
 
 		When {expr} is 0 and Esc is typed, there will be a short delay
 		while Vim waits to see if this is the start of an escape
@@ -3947,6 +3950,31 @@ getchar([{expr}])					*getchar()*
 
 		Use getcharmod() to obtain any additional modifiers.
 
+		The optional argument {opts} is a Dict and supports the
+		following items:
+
+			cursor		A String specifying cursor behavior
+					when waiting for a character.
+					"hide": hide the cursor.
+					"keep": keep current cursor unchanged.
+					"msg": move cursor to message area.
+					(default: "msg")
+
+			number		If |TRUE|, return a Number when getting
+					a single character.
+					If |FALSE|, the return value is always
+					converted to a String, and an empty
+					String (instead of 0) is returned when
+					no character is available.
+					(default: |TRUE|)
+
+			simplify	If |TRUE|, include modifiers in the
+					character if possible.  E.g., return
+					the same value for CTRL-I and <Tab>.
+					If |FALSE|, don't include modifiers in
+					the character.
+					(default: |TRUE|)
+
 		When the user clicks a mouse button, the mouse event will be
 		returned.  The position can then be found in |v:mouse_col|,
 		|v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
@@ -4062,17 +4090,9 @@ getcharsearch()						*getcharsearch()*
 		Return type: dict<any>
 
 
-getcharstr([{expr}])					*getcharstr()*
-		Get a single character from the user or input stream as a
-		string.
-		If {expr} is omitted, wait until a character is available.
-		If {expr} is 0 or false, only get a character when one is
-			available.  Return an empty string otherwise.
-		If {expr} is 1 or true, only check if a character is
-			available, it is not consumed.  Return an empty string
-			if no character is available.
-		Otherwise this works like |getchar()|, except that a number
-		result is converted to a string.
+getcharstr([{expr} [, {opts}]])				*getcharstr()*
+		The same as |getchar()|, except that this always returns a
+		String, and "number" isn't allowed in {opts}.
 
 		Return type: |String|
 
@@ -12730,6 +12750,7 @@ gui_win32s		idem, and Win32s system being used (Windows 3.1)
 haiku			Haiku version of Vim.
 hangul_input		Compiled with Hangul input support. |hangul|
 hpux			HP-UX version of Vim.
+hurd			GNU/Hurd version of Vim
 iconv			Can use iconv() for conversion.
 insert_expand		Compiled with support for CTRL-X expansion commands in
 			Insert mode. (always true)