patch 9.1.1068: getchar() can't distinguish between C-I and Tab
Problem: getchar() can't distinguish between C-I and Tab.
Solution: Add {opts} to pass extra flags to getchar() and getcharstr(),
with "number" and "simplify" keys.
related: #10603
closes: #16554
Signed-off-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index e222d7c..46c3ba8 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/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 02
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -228,12 +228,12 @@
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 @@
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 @@
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,24 @@
Use getcharmod() to obtain any additional modifiers.
+ The optional argument {opts} is a Dict and supports the
+ following items:
+
+ 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 +4083,9 @@
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|