vim-patch:9.1.1068: getchar() can't distinguish between C-I and Tab (#32295)

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: vim/vim#10603
closes: vim/vim#16554

https://github.com/vim/vim/commit/e0a2ab397fd13a71efec85b017d5d4d62baf7f63

Cherry-pick tv_dict_has_key() from patch 8.2.4683.

1 files changed, 32 insertions, 19 deletions

diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index ecb213c811..82e3992287 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -3471,15 +3471,17 @@ M.funcs = {
     signature = 'getchangelist([{buf}])',
   },
   getchar = {
-    args = { 0, 1 },
+    args = { 0, 2 },
     desc = [=[
       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
@@ -3489,7 +3491,8 @@ M.funcs = {
       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
@@ -3501,6 +3504,24 @@ M.funcs = {
 
       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|.
@@ -3538,9 +3559,9 @@ M.funcs = {
       <
     ]=],
     name = 'getchar',
-    params = { { 'expr', '0|1' } },
-    returns = 'integer',
-    signature = 'getchar([{expr}])',
+    params = { { 'expr', '-1|0|1' }, { 'opts', 'table' } },
+    returns = 'integer|string',
+    signature = 'getchar([{expr} [, {opts}]])',
   },
   getcharmod = {
     desc = [=[
@@ -3613,21 +3634,13 @@ M.funcs = {
     signature = 'getcharsearch()',
   },
   getcharstr = {
-    args = { 0, 1 },
+    args = { 0, 2 },
     desc = [=[
-      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.
+      The same as |getchar()|, except that this always returns a
+      String, and "number" isn't allowed in {opts}.
     ]=],
     name = 'getcharstr',
-    params = { { 'expr', '0|1' } },
+    params = { { 'expr', '-1|0|1' }, { 'opts', 'table' } },
     returns = 'string',
     signature = 'getcharstr([{expr}])',
   },