Merge pull request #74 from vim-denops/input

👍  Improve `input()` and related functions

Author: lambdalisue

denops_std/function/_generated.ts

@@ -3272,140 +3272,6 @@ export function index(denops: Denops, ...args: unknown[]): Promise<unknown> {
   return denops.call("index", ...args);
 }
 
-/**
- * The result is a String, which is whatever the user typed on
- * the command-line.  The {prompt} argument is either a prompt
- * string, or a blank string (for no prompt).  A '\n' can be used
- * in the prompt to start a new line.
- * The highlighting set with |:echohl| is used for the prompt.
- * The input is entered just like a command-line, with the same
- * editing commands and mappings.  There is a separate history
- * for lines typed for input().
- * Example:
- * 	:if input("Coffee or beer? ") == "beer"
- * 	:  echo "Cheers!"
- * 	:endif
- * If the optional {text} argument is present and not empty, this
- * is used for the default reply, as if the user typed this.
- * Example:
- * 	:let color = input("Color? ", "white")
- * The optional {completion} argument specifies the type of
- * completion supported for the input.  Without it completion is
- * not performed.  The supported completion types are the same as
- * that can be supplied to a user-defined command using the
- * "-complete=" argument.  Refer to |:command-completion| for
- * more information.  Example:
- * 	let fname = input("File: ", "", "file")
- * NOTE: This function must not be used in a startup file, for
- * the versions that only run in GUI mode (e.g., the Win32 GUI).
- * Note: When input() is called from within a mapping it will
- * consume remaining characters from that mapping, because a
- * mapping is handled like the characters were typed.
- * Use |inputsave()| before input() and |inputrestore()|
- * after input() to avoid that.  Another solution is to avoid
- * that further characters follow in the mapping, e.g., by using
- * |:execute| or |:normal|.
- * Example with a mapping:
- * 	:nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR
- * 	:function GetFoo()
- * 	:  call inputsave()
- * 	:  let g:Foo = input("enter search pattern: ")
- * 	:  call inputrestore()
- * 	:endfunction
- * Can also be used as a |method|:
- * 	GetPrompt()->input()
- */
-export function input(
-  denops: Denops,
-  prompt: unknown,
-  text?: unknown,
-  completion?: unknown,
-): Promise<unknown>;
-export function input(denops: Denops, ...args: unknown[]): Promise<unknown> {
-  return denops.call("input", ...args);
-}
-
-/**
- * {textlist} must be a |List| of strings.  This |List| is
- * displayed, one string per line.  The user will be prompted to
- * enter a number, which is returned.
- * The user can also select an item by clicking on it with the
- * mouse.  For the first string 0 is returned.  When clicking
- * above the first item a negative number is returned.  When
- * clicking on the prompt one more than the length of {textlist}
- * is returned.
- * Make sure {textlist} has less than 'lines' entries, otherwise
- * it won't work.  It's a good idea to put the entry number at
- * the start of the string.  And put a prompt in the first item.
- * Example:
- * 	let color = inputlist(['Select color:', '1. red',
- * 		\ '2. green', '3. blue'])
- * Can also be used as a |method|:
- * 	GetChoices()->inputlist()
- */
-export function inputlist(denops: Denops, textlist: unknown): Promise<unknown>;
-export function inputlist(
-  denops: Denops,
-  ...args: unknown[]
-): Promise<unknown> {
-  return denops.call("inputlist", ...args);
-}
-
-/**
- * Restore typeahead that was saved with a previous |inputsave()|.
- * Should be called the same number of times inputsave() is
- * called.  Calling it more often is harmless though.
- * Returns 1 when there is nothing to restore, 0 otherwise.
- */
-export function inputrestore(denops: Denops): Promise<unknown>;
-export function inputrestore(
-  denops: Denops,
-  ...args: unknown[]
-): Promise<unknown> {
-  return denops.call("inputrestore", ...args);
-}
-
-/**
- * Preserve typeahead (also from mappings) and clear it, so that
- * a following prompt gets input from the user.  Should be
- * followed by a matching inputrestore() after the prompt.  Can
- * be used several times, in which case there must be just as
- * many inputrestore() calls.
- * Returns 1 when out of memory, 0 otherwise.
- */
-export function inputsave(denops: Denops): Promise<unknown>;
-export function inputsave(
-  denops: Denops,
-  ...args: unknown[]
-): Promise<unknown> {
-  return denops.call("inputsave", ...args);
-}
-
-/**
- * This function acts much like the |input()| function with but
- * two exceptions:
- * a) the user's response will be displayed as a sequence of
- * asterisks ("*") thereby keeping the entry secret, and
- * b) the user's response will not be recorded on the input
- * |history| stack.
- * The result is a String, which is whatever the user actually
- * typed on the command-line in response to the issued prompt.
- * NOTE: Command-line completion is not supported.
- * Can also be used as a |method|:
- * 	GetPrompt()->inputsecret()
- */
-export function inputsecret(
-  denops: Denops,
-  prompt: unknown,
-  text?: unknown,
-): Promise<unknown>;
-export function inputsecret(
-  denops: Denops,
-  ...args: unknown[]
-): Promise<unknown> {
-  return denops.call("inputsecret", ...args);
-}
-
 /**
  * When {object} is a |List| or a |Blob| insert {item} at the start
  * of it.

denops_std/function/_manual.ts

@@ -1,5 +1,6 @@
 export * from "./buffer.ts";
 export * from "./common.ts";
 export * from "./cursor.ts";
+export * from "./input.ts";
 export * from "./types.ts";
 export * from "./various.ts";

denops_std/function/input.ts

@@ -0,0 +1,126 @@
+import { Denops } from "../deps.ts";
+import { BuiltinCompletion, isValidBuiltinCompletion } from "./types.ts";
+
+/**
+ * The result is a String, which is whatever the user typed on
+ * the command-line.  The {prompt} argument is either a prompt
+ * string, or a blank string (for no prompt).  A '\n' can be used
+ * in the prompt to start a new line.
+ * The highlighting set with |:echohl| is used for the prompt.
+ * The input is entered just like a command-line, with the same
+ * editing commands and mappings.  There is a separate history
+ * for lines typed for input().
+ * Example:
+ * 	:if input("Coffee or beer? ") == "beer"
+ * 	:  echo "Cheers!"
+ * 	:endif
+ * If the optional {text} argument is present and not empty, this
+ * is used for the default reply, as if the user typed this.
+ * Example:
+ * 	:let color = input("Color? ", "white")
+ * The optional {completion} argument specifies the type of
+ * completion supported for the input.  Without it completion is
+ * not performed.  The supported completion types are the same as
+ * that can be supplied to a user-defined command using the
+ * "-complete=" argument.  Refer to |:command-completion| for
+ * more information.  Example:
+ * 	let fname = input("File: ", "", "file")
+ * NOTE: This function must not be used in a startup file, for
+ * the versions that only run in GUI mode (e.g., the Win32 GUI).
+ * Note: When input() is called from within a mapping it will
+ * consume remaining characters from that mapping, because a
+ * mapping is handled like the characters were typed.
+ * Use |inputsave()| before input() and |inputrestore()|
+ * after input() to avoid that.  Another solution is to avoid
+ * that further characters follow in the mapping, e.g., by using
+ * |:execute| or |:normal|.
+ * Example with a mapping:
+ * 	:nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR
+ * 	:function GetFoo()
+ * 	:  call inputsave()
+ * 	:  let g:Foo = input("enter search pattern: ")
+ * 	:  call inputrestore()
+ * 	:endfunction
+ * Can also be used as a |method|:
+ * 	GetPrompt()->input()
+ */
+export function input(
+  denops: Denops,
+  prompt: string,
+  text = "",
+  completion?: BuiltinCompletion | string,
+): Promise<string> {
+  if (completion && !isValidBuiltinCompletion(completion)) {
+    if (
+      !completion.startsWith("custom,") && !completion.startsWith("customlist,")
+    ) {
+      throw new Error(`Invalid completion '${completion}' specified.`);
+    }
+  }
+  return denops.call("input", prompt, text, completion) as Promise<string>;
+}
+
+/**
+ * {textlist} must be a |List| of strings.  This |List| is
+ * displayed, one string per line.  The user will be prompted to
+ * enter a number, which is returned.
+ * The user can also select an item by clicking on it with the
+ * mouse.  For the first string 0 is returned.  When clicking
+ * above the first item a negative number is returned.  When
+ * clicking on the prompt one more than the length of {textlist}
+ * is returned.
+ * Make sure {textlist} has less than 'lines' entries, otherwise
+ * it won't work.  It's a good idea to put the entry number at
+ * the start of the string.  And put a prompt in the first item.
+ * Example:
+ * 	let color = inputlist(['Select color:', '1. red',
+ * 		\ '2. green', '3. blue'])
+ * Can also be used as a |method|:
+ * 	GetChoices()->inputlist()
+ */
+export function inputlist(denops: Denops, textlist: string[]): Promise<number> {
+  return denops.call("inputlist", textlist) as Promise<number>;
+}
+
+/**
+ * Restore typeahead that was saved with a previous |inputsave()|.
+ * Should be called the same number of times inputsave() is
+ * called.  Calling it more often is harmless though.
+ * Returns 1 when there is nothing to restore, 0 otherwise.
+ */
+export function inputrestore(denops: Denops): Promise<void> {
+  return denops.call("inputrestore") as Promise<void>;
+}
+
+/**
+ * Preserve typeahead (also from mappings) and clear it, so that
+ * a following prompt gets input from the user.  Should be
+ * followed by a matching inputrestore() after the prompt.  Can
+ * be used several times, in which case there must be just as
+ * many inputrestore() calls.
+ * Returns 1 when out of memory, 0 otherwise.
+ */
+export function inputsave(denops: Denops): Promise<void> {
+  return denops.call("inputsave") as Promise<void>;
+}
+
+/**
+ * This function acts much like the |input()| function with but
+ * two exceptions:
+ * a) the user's response will be displayed as a sequence of
+ * asterisks ("*") thereby keeping the entry secret, and
+ * b) the user's response will not be recorded on the input
+ * |history| stack.
+ * The result is a String, which is whatever the user actually
+ * typed on the command-line in response to the issued prompt.
+ * NOTE: Command-line completion is not supported.
+ * Can also be used as a |method|:
+ * 	GetPrompt()->inputsecret()
+ */
+export function inputsecret(
+  denops: Denops,
+  prompt: string,
+  text = "",
+): Promise<string> {
+  return denops.call("inputsecret", prompt, text) as Promise<string>;
+}