Merge pull request #136 from vim-denops/fix-echo

🐛 Fix behavior of `helper.echo/echoerr` and add a way to silence messages

Author: lambdalisue

denops_std/autocmd/group.ts

@@ -14,11 +14,11 @@ export type GroupRemoveOptions = Omit<RemoveOptions, "group">;
 export async function group(
   denops: Denops,
   name: string,
-  main: (helper: GroupHelper) => void,
+  executor: (helper: GroupHelper) => void,
 ): Promise<void> {
   const commands: string[] = [];
   const helper = new GroupHelper(commands);
-  main(helper);
+  executor(helper);
   await execute(denops, [
     `aug ${name}`,
     ...commands,

denops_std/batch/batch.ts

@@ -86,11 +86,11 @@ class BatchHelper implements Denops {
  */
 export async function batch(
   denops: Denops,
-  main: (helper: BatchHelper) => Promise<void>,
+  executor: (helper: BatchHelper) => Promise<void>,
 ): Promise<void> {
   const helper = new BatchHelper(denops);
   try {
-    await main(helper);
+    await executor(helper);
   } finally {
     BatchHelper.close(helper);
   }

denops_std/batch/gather.ts

@@ -88,11 +88,11 @@ class GatherHelper implements Denops {
  */
 export async function gather(
   denops: Denops,
-  main: (helper: GatherHelper) => Promise<void>,
+  executor: (helper: GatherHelper) => Promise<void>,
 ): Promise<unknown[]> {
   const helper = new GatherHelper(denops);
   try {
-    await main(helper);
+    await executor(helper);
   } finally {
     GatherHelper.close(helper);
   }

denops_std/buffer/buffer.ts

@@ -256,10 +256,10 @@ export async function concrete(
 /**
  * Ensure the executor is executed under the specified buffer
  */
-export async function ensure<T = void>(
+export async function ensure<T>(
   denops: Denops,
   bufnr: number,
-  executor: () => Promise<T>,
+  executor: () => T,
 ): Promise<T> {
   const [bufnrCur, winidCur, winidNext] = await batch.gather(
     denops,
@@ -295,10 +295,10 @@ export async function ensure<T = void>(
 /**
  * Ensure the executor is executed under a modifiable buffer
  */
-export async function modifiable<T = void>(
+export async function modifiable<T>(
   denops: Denops,
   bufnr: number,
-  executor: () => Promise<T>,
+  executor: () => T,
 ): Promise<T> {
   const [modified, modifiable, foldmethod] = await batch.gather(
     denops,

denops_std/helper/README.md

@@ -22,6 +22,75 @@ export async function main(denops: Denops): Promise<void> {
 }
 ```
 
+##### Warning
+
+In order to make the behavior of Vim and Neovim consistent, `timer_start()` is
+used internally not only in Vim but also in Neovim. Note that this means that
+you cannot control the message by prepending `silent` when calling it from the
+Vim script. If you want to control the message, use the `setSilent` function to
+change the silent state to `'silent'` or `'silent!'` in advance, or use the
+`ensureSilent` function to fix the silent state to `'silent'` or `'silent!'`
+during execution of any function.
+
+### setSilent / getSilent
+
+By setting the silent state with `setSilent`, you can control `silent` and
+`silent!` messages as follows.
+
+```typescript
+import { Denops } from "../mod.ts";
+import { echo, echoerr, getSilent, setSilent } from "../helper/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  // Because silent is "silent!", `echo` and `echoerr` doesn't show messages.
+  setSilent(denops, "silent!");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+
+  // Because silent is "silent", `echo` doesn't show messages.
+  setSilent(denops, "silent");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+
+  // Because silent is "", both show messages.
+  setSilent(denops, "");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+}
+```
+
+Use the `getSilent()` function to get the current silent state.
+
+### ensureSilent
+
+To control `silent` and `silent!` messages while executing a particular
+function, use `ensureSilent` as follows
+
+```typescript
+import { Denops } from "../mod.ts";
+import { echo, echoerr, ensureSilent } from "../helper/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  // Because silent is "silent!", `echo` and `echoerr` doesn't show messages.
+  await ensureSilent(denops, "silent!", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+
+  // Because silent is "silent", `echo` doesn't show messages.
+  await ensureSilent(denops, "silent", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+
+  // Because silent is "", both shows messages.
+  await ensureSilent(denops, "", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+}
+```
+
 ### friendlyCall
 
 Use `friendlyCall()` to call given function and print a friendly error message

denops_std/helper/echo.ts

@@ -4,6 +4,7 @@ import { batch } from "../batch/mod.ts";
 import { generateUniqueString } from "../util.ts";
 
 const cacheKey = Symbol("denops_std/helper/echo");
+const cacheKeySilent = Symbol("denops_std/helper/echo/silent");
 const suffix = generateUniqueString();
 
 async function ensurePrerequisites(denops: Denops): Promise<string> {
@@ -13,9 +14,11 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
   denops.context[cacheKey] = true;
   const script = `
   let g:loaded_denops_std_helper_echo_${suffix} = 1
+  let s:denops_std_helper_echo_timer = 0
 
   function! DenopsStdHelperEcho_${suffix}(message) abort
-    call timer_start(0, { -> s:DenopsStdHelperEchoInternal_${suffix}(a:message) })
+    call timer_stop(s:denops_std_helper_echo_timer)
+    let s:denops_std_helper_echo_timer = timer_start(0, { -> s:DenopsStdHelperEchoInternal_${suffix}(a:message) })
   endfunction
 
   function! s:DenopsStdHelperEchoInternal_${suffix}(message) abort
@@ -26,6 +29,39 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
   return suffix;
 }
 
+export type Silent = "" | "silent" | "silent!";
+
+/**
+ * Get global silent status
+ */
+export function getSilent(denops: Denops): Silent {
+  return (denops.context[cacheKeySilent] ?? "") as Silent;
+}
+
+/**
+ * Set global silent status
+ */
+export function setSilent(denops: Denops, silent: Silent): void {
+  denops.context[cacheKeySilent] = silent;
+}
+
+/**
+ * Ensure global silent status during given function
+ */
+export async function ensureSilent<T>(
+  denops: Denops,
+  silent: Silent,
+  executor: () => T,
+): Promise<T> {
+  const saved = denops.context[cacheKeySilent];
+  denops.context[cacheKeySilent] = silent;
+  try {
+    return await executor();
+  } finally {
+    denops.context[cacheKeySilent] = saved;
+  }
+}
+
 /**
  * Echo message as like `echo` on Vim script.
  *
@@ -36,29 +72,68 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
  *
  * Note that it does nothing and return immediately when denops is
  * running as 'test' mode to avoid unwilling test failures.
+ *
+ * WARNING:
+ * In order to make the behavior of Vim and Neovim consistent,
+ * `timer_start()` is used internally not only in Vim but also in
+ * Neovim. Note that this means that you cannot control the message
+ * by prepending `silent` when calling it from the Vim script.
+ * If you want to control the message, use the `setSilent` function
+ * to change the silent state to `'silent'` or `'silent!'` in
+ * advance, or use the `ensureSilent` function to fix the silent state
+ * to `'silent'` or `'silent!'` during execution of any function.
  */
-export function echo(denops: Denops, message: string): Promise<void> {
+export function echo(
+  denops: Denops,
+  message: string,
+): Promise<void> {
+  const silent = getSilent(denops);
+  switch (silent) {
+    case "silent":
+    case "silent!":
+      return Promise.resolve();
+  }
   if (denops.meta.mode === "test") {
     return Promise.resolve();
-  } else if (denops.meta.host === "vim") {
-    return echoVim(denops, message);
   } else {
-    return denops.cmd("redraw | echo message", { message });
+    return echoInternal(denops, message);
   }
 }
 
 /**
  * Echo message as an error message.
  *
- * Note that this function just use ErrorMsg highlight and is not equivalent
- * to `echoerr` command in Vim/Neovim.
+ * Note that this function just use ErrorMsg highlight and is not
+ * equivalent to `echoerr` command in Vim/Neovim.
+ *
+ * WARNING:
+ * In order to make the behavior of Vim and Neovim consistent,
+ * `timer_start()` is used internally not only in Vim but also in
+ * Neovim. Note that this means that you cannot control the message
+ * by prepending `silent` when calling it from the Vim script.
+ * If you want to control the message, use the `setSilent` function
+ * to change the silent state to `'silent!'` in advance, or use the
+ * `ensureSilent` function to fix the silent state to `'silent!'`
+ * during execution of any function.
  */
-export async function echoerr(denops: Denops, message: string): Promise<void> {
-  await batch(denops, async (denops) => {
-    await denops.cmd("echohl ErrorMsg");
-    await echo(denops, message);
-    await denops.cmd("echohl None");
-  });
+export async function echoerr(
+  denops: Denops,
+  message: string,
+): Promise<void> {
+  const silent = getSilent(denops);
+  switch (silent) {
+    case "silent!":
+      return Promise.resolve();
+  }
+  if (denops.meta.mode === "test") {
+    return Promise.resolve();
+  } else {
+    await batch(denops, async (denops) => {
+      await denops.cmd("echohl ErrorMsg");
+      await echoInternal(denops, message);
+      await denops.cmd("echohl None");
+    });
+  }
 }
 
 /**
@@ -85,7 +160,7 @@ export async function friendlyCall(
   }
 }
 
-async function echoVim(denops: Denops, message: string): Promise<void> {
+async function echoInternal(denops: Denops, message: string): Promise<void> {
   const suffix = await ensurePrerequisites(denops);
   await denops.call(`DenopsStdHelperEcho_${suffix}`, message);
 }